Struct PremulColor

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

A color with premultiplied alpha.

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

Following the convention of CSS Color 4, in cylindrical color spaces the hue channel is not premultiplied. If it were, interpolation would give undesirable results.

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, and are premultiplied with the alpha value. The fourth component is alpha.

Note that in cylindrical color spaces, the hue component is not premultiplied, as specified in the CSS Color 4 spec. The methods on this type take care of that for you, but if you’re manipulating the components yourself, be aware.

cs: PhantomData<CS>

The color space.

Implementations

impl<CS: ColorSpace> PremulColor<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 discard_alpha(self) -> OpaqueColor<CS>

Split out the opaque components, discarding the alpha.

This is a shorthand for un-premultiplying the alpha and calling AlphaColor::discard_alpha.

The result of calling this on a fully transparent color will be the color black.

pub fn convert<TargetCS: ColorSpace>(self) -> PremulColor<TargetCS>

Convert a color into a different color space.

pub const fn un_premultiply(self) -> AlphaColor<CS>

Convert a color to the corresponding separate alpha form.

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

Interpolate colors.

Note: this function doesn’t fix up hue in cylindrical spaces. It is still useful if the hue angles are compatible, particularly if the fixup has been applied.

pub fn fixup_hues(self, other: &mut Self, direction: HueDirection)

Apply hue fixup for interpolation.

Adjust the hue angle of other so that linear interpolation results in the expected hue direction.

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 difference(self, other: Self) -> f32

Difference between two colors by Euclidean metric.

pub fn to_rgba8(self) -> PremulRgba8

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, see the note on AlphaColor::to_rgba8.

impl PremulColor<Srgb>

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

Create a color from pre-multiplied 8-bit rgba values.

Note: for conversion from the PremulRgba8 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 PremulColor<CS>

Component-wise addition of components.

type Output = PremulColor<CS>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<CS> BitEq for PremulColor<CS>

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

Returns true if self is equal to other.

impl<CS> BitHash for PremulColor<CS>

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

Feeds this value into the given Hasher.

impl<CS: Clone> Clone for PremulColor<CS>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<CS: Debug> Debug for PremulColor<CS>

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

Formats the value using the given formatter.

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

Divide components by a scalar.

type Output = PremulColor<CS>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<CS: ColorSpace> From<OpaqueColor<CS>> for PremulColor<CS>

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

Converts to this type from the input type.

impl From<PremulRgba8> for PremulColor<Srgb>

fn from(value: PremulRgba8) -> Self

Converts to this type from the input type.

impl<CS: ColorSpace> FromStr for PremulColor<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<PremulColor<CS>> for f32

Multiply components by a scalar.

type Output = PremulColor<CS>

The resulting type after applying the * operator.

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

Performs the * operation.

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

Multiply components by a scalar.

For rectangular color spaces, this is equivalent to multiplying alpha, but for cylindrical color spaces, PremulColor::multiply_alpha is the preferred method.

type Output = PremulColor<CS>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<CS: ColorSpace> PartialEq for PremulColor<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 PremulColor<CS>

Component-wise subtraction of components.

type Output = PremulColor<CS>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<CS: ColorSpace> TransparentWrapper<[f32; 4]> for PremulColor<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 PremulColor<CS>

fn zeroed() -> Self

Calls zeroed.

impl<CS: Copy> Copy for PremulColor<CS>

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