Module 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 Vecs, 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§

  • BoxedSliceCastError
    The error type returned when casting a boxed slice of components fails.
  • Packed
    A color packed into a compact format, such as an unsigned integer.
  • SliceCastError
    The error type returned when casting a slice of components fails.
  • VecCastError
    The error type returned when casting a Vec of components fails.

Enums§

  • VecCastErrorKind
    The type of error that is returned when casting a Vec of components.

Traits§

  • ArrayCast
    Marker trait for types that can be represented as a fixed size array.
  • ArraysAs
    Trait for casting a reference to collection of arrays into a reference to collection of colors without copying.
  • ArraysAsMut
    Trait for casting a mutable reference to collection of arrays into a mutable reference to collection of colors without copying.
  • ArraysFrom
    Trait for casting a collection of arrays from a collection of colors without copying.
  • ArraysInto
    Trait for casting a collection of arrays into a collection of colors without copying.
  • AsArrays
    Trait for casting a reference to a collection of colors into a reference to a collection of arrays without copying.
  • AsArraysMut
    Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of arrays without copying.
  • AsComponents
    Trait for casting a reference to a collection of colors into a reference to a collection of color components without copying.
  • AsComponentsMut
    Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of color components without copying.
  • AsUints
    Trait for casting a reference to a collection of colors into a reference to a collection of unsigned integers without copying.
  • AsUintsMut
    Trait for casting a mutable reference to a collection of colors into a mutable reference to a collection of unsigned integers without copying.
  • ComponentOrder
    Packs and unpacks color types with some component order.
  • ComponentsAs
    Trait for casting a reference to collection of color components into a reference to collection of colors without copying.
  • ComponentsAsMut
    Trait for casting a mutable reference to collection of color components into a mutable reference to collection of colors without copying.
  • ComponentsFrom
    Trait for casting a collection of color components into a collection of colors without copying.
  • ComponentsInto
    Trait for casting a collection of color components from a collection of colors without copying.
  • FromArrays
    Trait for casting a collection of colors from a collection of arrays without copying.
  • FromComponents
    Trait for casting a collection of colors from a collection of color components without copying.
  • FromUints
    Trait for casting a collection of colors from a collection of unsigned integers without copying.
  • IntoArrays
    Trait for casting a collection of colors into a collection of arrays without copying.
  • IntoComponents
    Trait for casting a collection of colors into a collection of color components without copying.
  • IntoUints
    Trait for casting a collection of colors into a collection of unsigned integers without copying.
  • TryComponentsAs
    Trait for trying to cast a reference to collection of color components into a reference to collection of colors without copying.
  • TryComponentsAsMut
    Trait for trying to cast a mutable reference to collection of color components into a mutable reference to collection of colors without copying.
  • TryComponentsInto
    Trait for trying to cast a collection of color components from a collection of colors without copying.
  • TryFromComponents
    Trait for trying to cast a collection of colors from a collection of color components without copying.
  • UintCast
    Marker trait for types that can be represented as an unsigned integer.
  • UintsAs
    Trait for casting a reference to a collection of unsigned integers into a reference to a collection of colors without copying.
  • UintsAsMut
    Trait for casting a mutable reference to a collection of unsigned integers into a mutable reference to a collection of colors without copying.
  • UintsFrom
    Trait for casting a collection of unsigned integers from a collection of colors without copying.
  • UintsInto
    Trait for casting a collection of unsigned integers into a collection of colors without copying.

Functions§

Derive Macros§