Struct AlphaColor

#[repr(transparent)]
pub struct AlphaColor<CS> {
    pub components: [f32; 4],
    pub cs: PhantomData<CS>,
}

A color with an alpha channel.

A color in a color space known at compile time, with an alpha channel.

See OpaqueColor for a discussion of arithmetic traits and interpolation.

Fields

components: [f32; 4]

The components, which may be manipulated directly.

The interpretation of the first three components depends on the color space. The fourth component is separate alpha.

cs: PhantomData<CS>

The color space.

Implementations

impl<CS: ColorSpace> AlphaColor<CS>

pub const BLACK: Self

A black color.

More comprehensive pre-defined colors are available in the color::palette module.

pub const TRANSPARENT: Self

A transparent color.

This is a black color with full alpha.

More comprehensive pre-defined colors are available in the color::palette module.

pub const WHITE: Self

A white color.

This value is specific to the color space.

More comprehensive pre-defined colors are available in the color::palette module.

pub const fn new(components: [f32; 4]) -> Self

Create a new color from the given components.

pub const fn split(self) -> (OpaqueColor<CS>, f32)

Split into opaque and alpha components.

This function is the inverse of OpaqueColor::with_alpha.

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 AlphaColor::multiply_alpha or AlphaColor::map.

let c = color::palette::css::GOLDENROD.with_alpha(0.5);
assert_eq!(0.5, c.split().1);

pub const fn discard_alpha(self) -> OpaqueColor<CS>

Split out the opaque components, discarding the alpha.

This is a shorthand for calling split.

pub fn convert<TargetCs: ColorSpace>(self) -> AlphaColor<TargetCs>

Convert a color into a different color space.

pub const fn premultiply(self) -> PremulColor<CS>

Convert a color to the corresponding premultiplied form.

pub fn lerp_rect(self, other: Self, t: f32) -> Self

Linearly interpolate colors, without hue fixup.

This method produces meaningful results in rectangular color spaces, or if hue fixup has been applied.

pub fn lerp(self, other: Self, t: f32, direction: HueDirection) -> Self

Linearly interpolate colors, with hue fixup if needed.

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

Multiply alpha by the given factor.

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

Scale the chroma by the given amount.

See ColorSpace::scale_chroma for more details.

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

Map components.

pub fn map_in<TargetCS: ColorSpace>( self, 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.

Examples

use color::{AlphaColor, Lab};

let color = AlphaColor::<Lab>::new([40., 4., -17., 1.]);
let lighter = color.map_lightness(|l| l + 0.2);
let expected = AlphaColor::<Lab>::new([60., 4., -17., 1.]);

assert!(lighter.premultiply().difference(expected.premultiply()) < 1e-4);

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.

Examples

use color::{AlphaColor, Oklab};

let color = AlphaColor::<Oklab>::new([0.5, 0.2, -0.1, 1.]);
let complementary = color.map_hue(|h| (h + 180.) % 360.);
let expected = AlphaColor::<Oklab>::new([0.5, -0.2, 0.1, 1.]);

assert!(complementary.premultiply().difference(expected.premultiply()) < 1e-4);

pub fn to_rgba8(self) -> Rgba8

Convert the color to sRGB if not already in sRGB, and pack into 8 bit per component integer encoding.

The RGBA components are mapped from the floating point range of 0.0-1.0 to the integer range of 0-255. Component values outside of this range are saturated to 0 or 255.

Implementation note

This performs almost-correct rounding to be fast on both x86 and AArch64 hardware. Within the saturated output range of this method, 0-255, there is a single color component value where results differ: 0.0019607842. This method maps that component to integer value 1; it would more precisely be mapped to 0.

impl AlphaColor<Srgb>

pub const fn from_rgba8(r: u8, g: u8, b: u8, a: u8) -> Self

Create a color from 8-bit rgba values.

Note: for conversion from the Rgba8 type, just use the From trait.

pub const fn from_rgb8(r: u8, g: u8, b: u8) -> Self

Create a color from 8-bit rgb values with an opaque alpha.

Note: for conversion from the Rgba8 type, just use the From trait.

Trait Implementations

impl<CS: ColorSpace> Add for AlphaColor<CS>

Component-wise addition of components.

type Output = AlphaColor<CS>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self

Performs the + operation.

impl<CS> BitEq for AlphaColor<CS>

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

Returns true if self is equal to other.

impl<CS> BitHash for AlphaColor<CS>

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

Feeds this value into the given Hasher.

impl<CS: Clone> Clone for AlphaColor<CS>

fn clone(&self) -> AlphaColor<CS>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<CS: Debug> Debug for AlphaColor<CS>

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

Formats the value using the given formatter.

impl<CS: ColorSpace> Div<f32> for AlphaColor<CS>

Divide components by a scalar.

type Output = AlphaColor<CS>

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Self

Performs the / operation.

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<CS: ColorSpace> From<OpaqueColor<CS>> for AlphaColor<CS>

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

Converts to this type from the input type.

impl From<Rgba8> for AlphaColor<Srgb>

fn from(value: Rgba8) -> Self

Converts to this type from the input type.

impl<CS: ColorSpace> FromStr for AlphaColor<CS>

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<CS: ColorSpace> Mul<AlphaColor<CS>> for f32

Multiply components by a scalar.

type Output = AlphaColor<CS>

The resulting type after applying the * operator.

fn mul(self, rhs: AlphaColor<CS>) -> Self::Output

Performs the * operation.

impl<CS: ColorSpace> Mul<f32> for AlphaColor<CS>

Multiply components by a scalar.

type Output = AlphaColor<CS>

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self

Performs the * operation.

impl<CS: ColorSpace> PartialEq for AlphaColor<CS>

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

Tests for self and other values to be equal, and is used by ==.

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<CS: ColorSpace> Sub for AlphaColor<CS>

Component-wise subtraction of components.

type Output = AlphaColor<CS>

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self

Performs the - operation.

impl<CS: ColorSpace> TransparentWrapper<[f32; 4]> for AlphaColor<CS>

fn wrap(s: Inner) -> Self

where Self: Sized,

Convert the inner type into the wrapper type.

fn wrap_ref(s: &Inner) -> &Self

Convert a reference to the inner type into a reference to the wrapper type.

fn wrap_mut(s: &mut Inner) -> &mut Self

Convert a mutable reference to the inner type into a mutable reference to the wrapper type.

fn wrap_slice(s: &[Inner]) -> &[Self]

where Self: Sized,

Convert a slice to the inner type into a slice to the wrapper type.

fn wrap_slice_mut(s: &mut [Inner]) -> &mut [Self]

where Self: Sized,

Convert a mutable slice to the inner type into a mutable slice to the wrapper type.

fn peel(s: Self) -> Inner

where Self: Sized,

Convert the wrapper type into the inner type.

fn peel_ref(s: &Self) -> &Inner

Convert a reference to the wrapper type into a reference to the inner type.

fn peel_mut(s: &mut Self) -> &mut Inner

Convert a mutable reference to the wrapper type into a mutable reference to the inner type.

fn peel_slice(s: &[Self]) -> &[Inner]

where Self: Sized,

Convert a slice to the wrapped type into a slice to the inner type.

fn peel_slice_mut(s: &mut [Self]) -> &mut [Inner]

where Self: Sized,

Convert a mutable slice to the wrapped type into a mutable slice to the inner type.

impl<CS: ColorSpace> Zeroable for AlphaColor<CS>

fn zeroed() -> Self

Calls zeroed.

impl<CS: Copy> Copy for AlphaColor<CS>

impl<CS: ColorSpace> Pod for AlphaColor<CS>