Module cosmic::cosmic_theme::palette::cast
source · Expand description
Traits and functions for casting colors to and from other data types.
The functions and traits in this module cast without changing the underlying
data. See the convert
module for how to convert between
color spaces.
§Traits or Functions?
This module provides both a set of traits (FromComponents
,
IntoUints
, etc.) and a set of functions (from_component_slice
,
into_uint_array
, etc.) that effectively implement the same
functionality. The traits are all implemented using the functions, so they
can be seen as bits of more implicit syntax sugar for the more explicit
functions.
A general recommendation is to use the traits, since they provide mostly better ergonomics.
§Arrays and Slices
Types that implement ArrayCast
can be cast to and from arrays and slices
with little to no overhead. This makes it easy to work with image buffers
and types from other crates without having to copy the data first.
Casting can be either be done with the free functions in this module, or using the helper traits.
§Casting Arrays
Arrays can be type checked to have the correct size at compile time, making
casting free after optimization has removed the overhead from asserts. The
same is true for arrays in slices and Vec
s, because the length stays the
same after casting.
use palette::{cast::{self, ArraysAsMut}, Srgb, IntoColor};
let color = cast::from_array::<Srgb<u8>>([23, 198, 76]).into_linear();
// Note: `Srgb::<u8>::from([23, 198, 76])` works too.
let mut buffer = [[64, 139, 10], [93, 18, 214]];
let color_buffer: &mut [Srgb<u8>] = buffer.arrays_as_mut();
for destination in color_buffer {
let linear_dst = destination.into_linear::<f32>();
*destination = (linear_dst + color).into_encoding();
}
Trying to cast a single array of the wrong size will not compile:
use palette::{cast, Srgb};
let color = cast::from_array::<Srgb<u8>>([23, 198]); // Too few components.
§Casting Component Buffers
This is a common situation is image processing, where you have an image
buffer, such as &mut [u8]
, &mut [f32]
, Vec<u8>
or Vec<f32>
, that you
want to work with as colors. This buffer may, for example, be the content of
an image file or shared with the GPU.
The downside, compared to having fixed size arrays, is that the length cannot be statically known to be a multiple of the color type’s array length. This adds a bit of error handling overhead, as well as for dividing or multiplying the length.
use palette::{cast::{self, TryComponentsAs}, Srgb};
let correct_buffer = [64, 139, 10, 93, 18, 214];
let should_be_ok: Result<&[Srgb<u8>], _> = correct_buffer.try_components_as();
assert!(should_be_ok.is_ok());
let incorrect_buffer = [64, 139, 10, 93, 18, 214, 198, 76];
let should_be_err: Result<&[Srgb<u8>], _> = incorrect_buffer.try_components_as();
assert!(should_be_err.is_err());
An alternative, for when the length can be trusted to be correct, is to use
methods without the try_*
prefix, such as ComponentsAs::components_as
,
or the from_component_*
functions, that panic on error.
This works:
use palette::{cast::ComponentsAs, Srgb};
let correct_buffer = [64, 139, 10, 93, 18, 214];
let color_buffer: &[Srgb<u8>] = correct_buffer.components_as();
But this panics:
use palette::{cast::ComponentsAs, Srgb};
let incorrect_buffer = [64, 139, 10, 93, 18, 214, 198, 76];
let color_buffer: &[Srgb<u8>] = incorrect_buffer.components_as();
§Casting Single Colors
The built-in color types implement AsRef
, AsMut
, From
, Into
,
TryFrom
and TryInto
in addition to ArrayCast
for convenient casting of
single colors:
use core::convert::TryFrom;
use palette::Srgb;
let color = Srgb::from([23u8, 198, 76]);
let array: [u8; 3] = color.into();
let slice: &[u8] = color.as_ref();
assert!(<&Srgb<u8>>::try_from(slice).is_ok());
let short_slice: &[f32] = &[0.1, 0.5];
assert!(<&Srgb>::try_from(short_slice).is_err()); // Too few components.
§Component Order
The component order in an array or slice is not always the same as in the
color types. For example, a byte buffer that is encoded as ARGB will not
cast to correct Rgba
values. The components can be reordered after casting
by using the Packed
wrapper as an intermediate representation.
// `PackedArgb` is an alias for `Packed<rgb::channels::Argb, P = u32>`.
use palette::{rgb::PackedArgb, cast::ComponentsAs, Srgba};
let components = [1.0f32, 0.8, 0.2, 0.3, 1.0, 0.5, 0.7, 0.6];
let colors: &[PackedArgb<_>] = components.components_as();
// Notice how the alpha values have moved from the beginning to the end:
assert_eq!(Srgba::from(colors[0]), Srgba::new(0.8, 0.2, 0.3, 1.0));
assert_eq!(Srgba::from(colors[1]), Srgba::new(0.5, 0.7, 0.6, 1.0));
§Unsigned Integers
Types that implement UintCast
can be cast to and from unsigned integers
of the same size. It’s a bit more limited than slices and arrays but it’s
useful for common patterns like representing RGBA values as hexadecimal
unsigned integers.
The Packed
wrapper can be used as an intermediate format to make
unpacking the values as simple as from
or into
. It’s also possible to
choose a channel order to be something other than what the default From
implementations would use.
// `PackedArgb` is an alias for `Packed<rgb::channels::Argb, P = u32>`.
use palette::{rgb::PackedArgb, cast::UintsAs, Srgba};
let raw = [0xFF7F0080u32, 0xFF60BBCC];
let colors: &[PackedArgb] = raw.uints_as();
assert_eq!(colors.len(), 2);
assert_eq!(Srgba::from(colors[0]), Srgba::new(0x7F, 0x00, 0x80, 0xFF));
assert_eq!(Srgba::from(colors[1]), Srgba::new(0x60, 0xBB, 0xCC, 0xFF));
Structs§
- The error type returned when casting a boxed slice of components fails.
- A color packed into a compact format, such as an unsigned integer.
- The error type returned when casting a slice of components fails.
- The error type returned when casting a
Vec
of components fails.
Enums§
- The type of error that is returned when casting a
Vec
of components.
Traits§
- Marker trait for types that can be represented as a fixed size array.
- Trait for casting a reference to collection of arrays into a reference to collection of colors without copying.
- Trait for casting a mutable reference to collection of arrays into a mutable reference to collection of colors without copying.
- Trait for casting a collection of arrays from a collection of colors without copying.
- Trait for casting a collection of arrays into a collection of colors without copying.
- Trait for casting a reference to a collection of colors into a reference to a collection of arrays without copying.
- Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of arrays without copying.
- Trait for casting a reference to a collection of colors into a reference to a collection of color components without copying.
- Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of color components without copying.
- Trait for casting a reference to a collection of colors into a reference to a collection of unsigned integers without copying.
- Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of unsigned integers without copying.
- Packs and unpacks color types with some component order.
- Trait for casting a reference to collection of color components into a reference to collection of colors without copying.
- Trait for casting a mutable reference to collection of color components into a mutable reference to collection of colors without copying.
- Trait for casting a collection of color components into a collection of colors without copying.
- Trait for casting a collection of color components from a collection of colors without copying.
- Trait for casting a collection of colors from a collection of arrays without copying.
- Trait for casting a collection of colors from a collection of color components without copying.
- Trait for casting a collection of colors from a collection of unsigned integers without copying.
- Trait for casting a collection of colors into a collection of arrays without copying.
- Trait for casting a collection of colors into a collection of color components without copying.
- Trait for casting a collection of colors into a collection of unsigned integers without copying.
- Trait for trying to cast a reference to collection of color components into a reference to collection of colors without copying.
- Trait for trying to cast a mutable reference to collection of color components into a mutable reference to collection of colors without copying.
- Trait for trying to cast a collection of color components from a collection of colors without copying.
- Trait for trying to cast a collection of colors from a collection of color components without copying.
- Marker trait for types that can be represented as an unsigned integer.
- Trait for casting a reference to a collection of unsigned integers into a reference to a collection of colors without copying.
- Trait for casting a mutable reference to a collection of unsigned integers into a mutable reference to a collection of colors without copying.
- Trait for casting a collection of unsigned integers from a collection of colors without copying.
- Trait for casting a collection of unsigned integers into a collection of colors without copying.
Functions§
- Cast from an array to a color type.
- Cast from an array of arrays to an array of colors.
- Cast from a boxed array to a boxed color type.
- Cast from a mutable array reference to a mutable color type reference.
- Cast from an array reference to a color type reference.
- Cast from a slice of arrays to a slice of colors.
- Cast from a boxed slice of arrays to a boxed slice of colors.
- Cast from a mutable slice of arrays to a mutable slice of colors.
- Cast from a
Vec
of arrays to aVec
of colors. - Cast from an array of color components to an array of colors.
- The same as
try_from_component_slice
but panics on error. - The same as
try_from_component_slice_box
but panics on error. - The same as
try_from_component_slice_mut
but panics on error. - The same as
try_from_component_vec
but panics on error. - Cast from an unsigned integer to a color type.
- Cast from an array of unsigned integers to an array of colors.
- Cast from a mutable unsigned integer reference to a mutable color type reference.
- Cast from an unsigned integer reference to a color type reference.
- Cast from a slice of unsigned integers to a slice of colors.
- Cast from a boxed slice of unsigned integers to a boxed slice of colors.
- Cast from a mutable slice of unsigned integers to a mutable slice of colors.
- Cast from a
Vec
of unsigned integers to aVec
of colors. - Cast from a color type to an array.
- Cast from an array of colors to an array of arrays.
- Cast from a boxed color type to a boxed array.
- Cast from a mutable color type reference to a mutable array reference.
- Cast from a color type reference to an array reference.
- Cast from a slice of colors to a slice of arrays.
- Cast from a boxed slice of colors to a boxed slice of arrays.
- Cast from a mutable slice of colors to a mutable slice of arrays.
- Cast from a
Vec
of colors to aVec
of arrays. - Cast from an array of colors to an array of color components.
- Cast from a slice of colors to a slice of color components.
- Cast from a boxed slice of colors to a boxed slice of color components.
- Cast from a slice of colors to a slice of color components.
- Cast from a
Vec
of colors to aVec
of color components. - Cast from a color type to an unsigned integer.
- Cast from an array of colors to an array of unsigned integers.
- Cast from a mutable color type reference to a mutable unsigned integer reference.
- Cast from a color type reference to an unsigned integer reference.
- Cast from a slice of colors to a slice of unsigned integers.
- Cast from a boxed slice of colors to a boxed slice of unsigned integers.
- Cast from a mutable slice of colors to a mutable slice of unsigned integers.
- Cast from a
Vec
of colors to aVec
of unsigned integers. - Map values of color A to values of color B without creating a new
Box<[B]>
. - Map values of color A to values of color B without creating a new
Vec
. - Cast from a slice of color components to a slice of colors.
- Cast from a boxed slice of color components to a boxed slice of colors.
- Cast from a mutable slice of color components to a slice of colors.
- Cast from a
Vec
of color components to aVec
of colors.