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>(self) -> AlphaColor<CS>

where CS: ColorSpace,

Convert to AlphaColor with a static color space.

Missing components are interpreted as 0.

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

where CS: ColorSpace,

Convert from AlphaColor.

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

Convert to a different color space.

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

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, ) -> DynamicColor

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.

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

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) -> DynamicColor

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) -> DynamicColor

Scale the chroma by the given amount.

See ColorSpace::scale_chroma for more details.

pub fn clip(self) -> DynamicColor

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.

pub fn interpolate( self, other: DynamicColor, 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 interpolate_unpremultiplied( self, other: DynamicColor, cs: ColorSpaceTag, direction: HueDirection, ) -> UnpremultipliedInterpolator

Interpolate two colors without alpha premultiplication.

Similar to DynamicColor::interpolate, but colors are interpolated without premultiplying their color channels by the alpha channel. This is almost never what you want.

This causes color information to leak out of transparent colors. For example, when interpolating from a fully transparent red to a fully opaque blue in sRGB, this method will go through an intermediate purple.

This matches behavior of gradients in the HTML canvas element. See The 2D rendering context § Fill and stroke styles of the HTML 2D Canvas specification.

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 UnpremultipliedInterpolator 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_unpremultiplied(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]) -> DynamicColor

Map components.

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

Map components in a given color space.

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

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) -> DynamicColor

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: &DynamicColor) -> bool

Returns true if self is equal to other.

impl BitHash for DynamicColor

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

where H: Hasher,

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<(), Error>

Formats the value using the given formatter.

impl Display for DynamicColor

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

Formats the value using the given formatter.

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

where CS: ColorSpace, 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>) -> DynamicColor

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<DynamicColor, <DynamicColor as FromStr>::Err>

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

impl PartialEq for DynamicColor

fn eq(&self, other: &DynamicColor) -> 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