Struct DynamicColor

pub struct DynamicColor {
    pub cs: ColorSpaceTag,
    pub flags: Flags,
    pub components: [f32; 4],
}

A color with a color space tag decided at runtime.

This type is roughly equivalent to AlphaColor except with a tag for color space as opposed being determined at compile time. It can also represent missing components, which are a feature of the CSS Color 4 spec.

Missing components are mostly useful for interpolation, and in that context take the value of the other color being interpolated. For example, interpolating a color in Oklch with oklch(none 0 none) fades the color saturation, ending in a gray with the same lightness.

In other contexts, missing colors are interpreted as a zero value. When manipulating components directly, setting them nonzero when the corresponding missing flag is set may yield unexpected results.

Fields

cs: ColorSpaceTag

The color space.

flags: Flags

The state of this color, tracking whether it has missing components and how it was constructed. See the documentation of Flags for more information.

components: [f32; 4]

The components.

The first three components are interpreted according to the color space tag. The fourth component is alpha, interpreted as separate alpha.

Implementations

impl DynamicColor

pub fn to_alpha_color<CS: ColorSpace>(self) -> AlphaColor<CS>

Convert to AlphaColor with a static color space.

Missing components are interpreted as 0.

pub fn from_alpha_color<CS: ColorSpace>(color: AlphaColor<CS>) -> Self

Convert from AlphaColor.

fn convert_impl<const ABSOLUTE: bool>(self, cs: ColorSpaceTag) -> Self

The const-generic parameter ABSOLUTE indicates whether the conversion performs chromatic adaptation. When ABSOLUTE is true, no chromatic adaptation is performed.

pub fn convert(self, cs: ColorSpaceTag) -> Self

Convert to a different color space.

pub fn convert_absolute(self, cs: ColorSpaceTag) -> Self

Convert to a different color space, without chromatic adaptation.

For most use-cases you should consider using the chromatically-adapting DynamicColor::convert instead. See the documentation on ColorSpace::convert_absolute for more information.

pub fn chromatically_adapt(self, from: Chromaticity, to: Chromaticity) -> Self

Chromatically adapt the color between the given white point chromaticities.

The color is assumed to be under a reference white point of from and is chromatically adapted to the given white point to. The linear Bradford transform is used to perform the chromatic adaptation.

fn zero_missing_components(self) -> Self

Set any missing components to zero.

We have a soft invariant that any bit set in the missing bitflag has a corresponding component which is 0. This method restores that invariant after manipulation which might invalidate it.

pub const fn multiply_alpha(self, rhs: f32) -> Self

Multiply alpha by the given factor.

If the alpha channel is missing, then the new alpha channel will be ignored and the color returned unchanged.

pub const fn with_alpha(self, alpha: f32) -> Self

Set the alpha channel.

This replaces the existing alpha channel. To scale or or otherwise modify the existing alpha channel, use DynamicColor::multiply_alpha or DynamicColor::map.

If the alpha channel is missing, then the new alpha channel will be ignored and the color returned unchanged.

let c = parse_color("lavenderblush").unwrap().with_alpha(0.7);
assert_eq!(0.7, c.to_alpha_color::<Srgb>().split().1);

pub fn scale_chroma(self, scale: f32) -> Self

Scale the chroma by the given amount.

See ColorSpace::scale_chroma for more details.

pub fn clip(self) -> Self

Clip the color’s components to fit within the natural gamut of the color space, and clamp the color’s alpha to be in the range [0, 1].

See ColorSpace::clip for more details.

fn premultiply_split(self) -> ([f32; 3], f32)

fn powerless_to_missing(&mut self)

pub fn interpolate( self, other: Self, cs: ColorSpaceTag, direction: HueDirection, ) -> Interpolator

Interpolate two colors.

The colors are interpolated linearly from self to other in the color space given by cs. When interpolating in a cylindrical color space, the hue can be interpolated in multiple ways. The direction parameter controls the way in which the hue is interpolated.

The interpolation proceeds according to CSS Color Module Level 4 § 12.

This method does a bunch of precomputation, resulting in an Interpolator object that can be evaluated at various t values.

Example

use color::{AlphaColor, ColorSpaceTag, DynamicColor, HueDirection, Srgb};

let start = DynamicColor::from_alpha_color(AlphaColor::<Srgb>::new([1., 0., 0., 1.]));
let end = DynamicColor::from_alpha_color(AlphaColor::<Srgb>::new([0., 1., 0., 1.]));

let interp = start.interpolate(end, ColorSpaceTag::Hsl, HueDirection::Increasing);
let mid = interp.eval(0.5);
assert_eq!(mid.cs, ColorSpaceTag::Hsl);
assert!((mid.components[0] - 60.).abs() < 0.01);

pub fn relative_luminance(self) -> f32

Compute the relative luminance of the color.

This can be useful for choosing contrasting colors, and follows the WCAG 2.1 spec.

Note that this method only considers the opaque color, not the alpha. Blending semi-transparent colors will reduce contrast, and that should also be taken into account.

pub fn map(self, f: impl Fn(f32, f32, f32, f32) -> [f32; 4]) -> Self

Map components.

pub fn map_in( self, cs: ColorSpaceTag, f: impl Fn(f32, f32, f32, f32) -> [f32; 4], ) -> Self

Map components in a given color space.

pub fn map_lightness(self, f: impl Fn(f32) -> f32) -> Self

Map the lightness of the color.

In a color space that naturally has a lightness component, map that value. Otherwise, do the mapping in Oklab. The lightness range is normalized so that 1.0 is white. That is the normal range for Oklab but differs from the range in Lab, Lch, and Hsl.

pub fn map_hue(self, f: impl Fn(f32) -> f32) -> Self

Map the hue of the color.

In a color space that naturally has a hue component, map that value. Otherwise, do the mapping in Oklch. The hue is in degrees.

Trait Implementations

impl BitEq for DynamicColor

fn bit_eq(&self, other: &Self) -> bool

Returns true if self is equal to other.

impl BitHash for DynamicColor

fn bit_hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

impl Clone for DynamicColor

fn clone(&self) -> DynamicColor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynamicColor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DynamicColor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<CS: ColorSpace> From<AlphaColor<CS>> for DynamicColor

where ColorSpaceTag: From<CS>,

Note that the conversion is only lossless for color spaces that have a corresponding tag. This is why we have this additional trait bound. See also https://github.com/linebender/color/pull/155 for more discussion.

fn from(value: AlphaColor<CS>) -> Self

Converts to this type from the input type.

impl FromStr for DynamicColor

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq for DynamicColor

fn eq(&self, other: &Self) -> bool

Equality is not perceptual, but requires the component values to be equal.

See also CacheKey.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for DynamicColor