Expand description
cint - color interop
This library provides a lean, minimal, and stable set of types
for color interoperation between crates in Rust. Its goal is to serve the same
function that mint provides for (linear algebra) math types.
It does not actually provide any conversion, math, etc. for these types, but rather
serves as a stable interface that multiple libraries can rely on and then convert
to their own internal representations to actually use. It is also #![no_std].
bytemuck impls are provided with the bytemuck feature.
How to Use
If you have no idea about color management or encoding principles but you want to use this crate in your own, here’s a very basic rundown.
If you have a color that you loaded from an 8-bit format like a PNG, JPG, etc.,
or if you have a color that you picked from some sort of online color picker
or in Photoshop or Aseprite, then what you have is almost certainly an EncodedSrgb<u8>
color. If you have a color that you loaded
from a similar format but has floating point values instead of u8 ints, then you
almost certainly instead have a EncodedSrgb<f32> color.
If you “linearized” or performed “inverse gamma correction” on such a color, then you instead
might have a LinearSrgb<f32>.
If you are more familiar with color encoding, then you’ll find a collection of other color spaces
represented, as well as the generic color types (like GenericColor3<ComponentTy>) which
can be used if the color space you wish to use is not represented.
All spaces are also collected into the Spaces enum, and you can get the variant represented
by any of the concrete color types by taking advantage of the ColorType’s SPACE associated
type, i.e. EncodedSrgb::SPACE will give Spaces::EncodedSrgb.
The ColorInterop trait exists to provide a “canonical” transformation to and from cint types.
Since it is often possible to convert a color to and from multiple cint types, and because of
how the Rust type inference system works, it can often be inconvenient to chain together from
or into calls from the From/Into trait. ColorInterop solves this by providing a strongly
typed “reference” conversion to/from cint types. This way, you can do things like:
let color_crate1 = color_crate2.into_cint().into();
// or
let color_crate2 = ColorCrate2::from_cint(color_crate1.into());which would otherwise be quite inconvenient. Provider crates (those that provide their own color
types) should implement the relevant From/Into implementations to and from cint types, and
also the ColorInterop trait once for each color type. The into_cint and
from_cint methods will then be provided automatically.
Colors with alpha channels
cint provides the Alpha<ColorTy> and PremultipliedAlpha<ColorTy>
structs, which are generic over the inner ColorTy.
To represent an EncodedSrgb<u8> color with a premultiplied alpha component,
you’d use PremultipliedAlpha<EncodedSrgb<u8>>. If, on the other hand, you want to represent
an Oklab<f32> color with an independent alpha component, you’d use Alpha<Oklab<f32>>
Structs
A color in the ACES 2065-1 color space.
A color in the ACEScc color space.
A color in the ACEScct color space.
A color in the ACEScg color space.
A color with an alpha component.
A color in the BT.2020 color space.
A color in the BT.2100 color space.
A color in the CIE L*C*h° color space.
A color in the CIE L*a*b* color space.
A color in the CIE XYZ color space.
A color in the DCI-P3 (aka P3 DCI and P3 D60) color space.
A color in the X’Y’Z’ color space, a DCI specification used for digital cinema mastering.
A color in the Display P3 (aka P3 D65) color space.
A color in the encoded BT.2020 color space.
A color in the encoded BT.2100 color space with HLG (Hybrid Log-Gamma) transfer function.
A color in the encoded BT.2100 color space with PQ (Perceptual Quantizer) transfer function.
A color in the Display P3 (aka P3 D65) color space.
A color in the encoded Rec.709/BT.709 color space.
A color in the encoded sRGB color space.
A color in a generic color space that can be represented by 1 component. The user is responsible for ensuring that the correct color space is respected.
A color in a generic color space that can be represented by 3 components. The user is responsible for ensuring that the correct color space is respected.
A color in the HSL color space.
A color in the HSV color space.
A color in the ICtCp color space with HLG (Hybrid Log-Gamma) nonlinearity.
A color in the ICtCp color space with PQ (Perceptual Quantizer) nonlinearity.
A color in the linear (decoded) sRGB color space.
A single-channel CIE luma (non-linear transform from luminance).
A single-channel CIE luminance.
A color in the Oklab color space.
A color in the Oklch color space (a transformation from Oklab to LCh° coordinates).
A premultiplied color with an alpha component.
A color in the Rec.709/BT.709 color space.
A color in the YCbCr color space. See discussion of the difference between YCbCr, YUV, and YPbPr in YCbCr Wikipedia article
A color in the YCxCz (also called YyCxCz) color space, originally defined in “Optimized universal color palette design for error diffusion” by B. W. Kolpatzik and C. A. Bouman. Can be thought of as a “linear CIE Lab”.
A color in the YPbPr color space. See discussion of the difference between YCbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article
A color in the Y’CbCr color space. See discussion of the difference between YCbCr, Y’CbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article
A color in the Y’PbPr color space. See discussion of the difference between YCbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article
A color in the YUV color space. See discussion of the difference between YCbCr, YUV, and YPbPr in YCbCr Wikipedia article
Enums
An enum with a variant for each of the color spaces supported by the library. Useful for tracking as metadata in something like an image type, and for runtime-determined color types.
Traits
A trait that should be implemented by provider crates on their local color types so that you can call
color.to_cint() and Color::from_cint(cint_color).
A trait used to simpify the interface of the Alpha and PremultipliedAlpha types and
allow use with Spaces enum.