Struct Color32

#[repr(C)]
pub struct Color32(pub(crate) [u8; 4]);

This format is used for space-efficient color representation (32 bits).

Instead of manipulating this directly it is often better to first convert it to either Rgba or crate::Hsva.

Internally this uses 0-255 gamma space sRGBA color with premultiplied alpha.

It’s the non-linear (“gamma”) values that are multiplied with the alpha.

Premultiplied alpha means that the color values have been pre-multiplied with the alpha (opacity). This is in contrast with “normal” RGBA, where the alpha is separate (or “unmultiplied”). Using premultiplied alpha has some advantages:

• It allows encoding additive colors
• It is the better way to blend colors, e.g. when filtering texture colors
• Because the above, it is the better way to encode colors in a GPU texture

The color space is assumed to be sRGB.

All operations on Color32 are done in “gamma space” (see https://en.wikipedia.org/wiki/SRGB). This is not physically correct, but it is fast and sometimes more perceptually even than linear space. If you instead want to perform these operations in linear-space color, use Rgba.

An alpha=0 means the color is to be treated as an additive color.

Tuple Fields

0: [u8; 4]

Implementations

impl Color32

pub const TRANSPARENT: Self

pub const BLACK: Self

pub const DARK_GRAY: Self

pub const GRAY: Self

pub const LIGHT_GRAY: Self

pub const WHITE: Self

pub const BROWN: Self

pub const DARK_RED: Self

pub const RED: Self

pub const LIGHT_RED: Self

pub const CYAN: Self

pub const MAGENTA: Self

pub const YELLOW: Self

pub const ORANGE: Self

pub const LIGHT_YELLOW: Self

pub const KHAKI: Self

pub const DARK_GREEN: Self

pub const GREEN: Self

pub const LIGHT_GREEN: Self

pub const DARK_BLUE: Self

pub const BLUE: Self

pub const LIGHT_BLUE: Self

pub const PURPLE: Self

pub const GOLD: Self

pub const DEBUG_COLOR: Self

pub const PLACEHOLDER: Self

An ugly color that is planned to be replaced before making it to the screen.

This is an invalid color, in that it does not correspond to a valid multiplied color, nor to an additive color.

This is used as a special color key, i.e. often taken to mean “no color”.

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

From RGB with alpha of 255 (opaque).

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

From RGB into an additive color (will make everything it blend with brighter).

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

From sRGBA with premultiplied alpha.

You likely want to use Self::from_rgba_unmultiplied instead.

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

From sRGBA with separate alpha.

This is a “normal” RGBA value that you would find in a color picker or a table somewhere.

You can use Self::to_srgba_unmultiplied to get back these values, but for transparent colors what you get back might be slightly different (rounding errors).

pub const fn from_gray(l: u8) -> Self

Opaque gray.

pub const fn from_black_alpha(a: u8) -> Self

Black with the given opacity.

pub fn from_white_alpha(a: u8) -> Self

White with the given opacity.

pub const fn from_additive_luminance(l: u8) -> Self

Additive white.

pub const fn is_opaque(&self) -> bool

pub const fn r(&self) -> u8

Red component multiplied by alpha.

pub const fn g(&self) -> u8

Green component multiplied by alpha.

pub const fn b(&self) -> u8

Blue component multiplied by alpha.

pub const fn a(&self) -> u8

Alpha (opacity).

pub fn to_opaque(self) -> Self

Returns an opaque version of self

pub const fn additive(self) -> Self

Returns an additive version of self

pub fn is_additive(self) -> bool

Is the alpha=0 ?

pub const fn to_array(&self) -> [u8; 4]

Premultiplied RGBA

pub const fn to_tuple(&self) -> (u8, u8, u8, u8)

Premultiplied RGBA

pub fn to_srgba_unmultiplied(&self) -> [u8; 4]

Convert to a normal “unmultiplied” RGBA color (i.e. with separate alpha).

This will unmultiply the alpha.

This is the inverse of Self::from_rgba_unmultiplied, but due to precision problems it may return slightly different values for transparent colors.

pub fn gamma_multiply(self, factor: f32) -> Self

Multiply with 0.5 to make color half as opaque, perceptually.

Fast multiplication in gamma-space.

This is perceptually even, and faster that Self::linear_multiply.

pub fn gamma_multiply_u8(self, factor: u8) -> Self

Multiply with 127 to make color half as opaque, perceptually.

Fast multiplication in gamma-space.

This is perceptually even, and faster that Self::linear_multiply.

pub fn linear_multiply(self, factor: f32) -> Self

Multiply with 0.5 to make color half as opaque in linear space.

This is using linear space, which is not perceptually even. You likely want to use Self::gamma_multiply instead.

pub fn to_normalized_gamma_f32(self) -> [f32; 4]

Converts to floating point values in the range 0-1 without any gamma space conversion.

Use this with great care! In almost all cases, you want to convert to crate::Rgba instead in order to obtain linear space color values.

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

Lerp this color towards other by t in gamma space.

pub fn blend(self, on_top: Self) -> Self

Blend two colors in gamma space, so that self is behind the argument.

pub fn intensity(&self) -> f32

Intensity of the color.

Returns a value in the range 0-1. The brighter the color, the closer to 1.

impl Color32

pub fn from_hex(hex: &str) -> Result<Self, ParseHexColorError>

Parses a color from a hex string.

Supports the 3, 4, 6, and 8-digit formats, according to the specification in https://drafts.csswg.org/css-color-4/#hex-color

To parse hex colors from string literals with compile-time checking, use the macro [crate::hex_color!] instead.

Example

use ecolor::Color32;
assert_eq!(Ok(Color32::RED), Color32::from_hex("#ff0000"));
assert_eq!(Ok(Color32::GREEN), Color32::from_hex("#00ff00ff"));
assert_eq!(Ok(Color32::BLUE), Color32::from_hex("#00f"));
assert_eq!(Ok(Color32::TRANSPARENT), Color32::from_hex("#0000"));

Errors

Returns an error if the string doesn’t start with the hash # character, if the remaining length does not correspond to one of the standard formats (3, 4, 6, or 8), if it contains non-hex characters.

pub fn to_hex(&self) -> String

Formats the color as a hex string.

Example

use ecolor::Color32;
assert_eq!(Color32::RED.to_hex(), "#ff0000ff");
assert_eq!(Color32::GREEN.to_hex(), "#00ff00ff");
assert_eq!(Color32::BLUE.to_hex(), "#0000ffff");
assert_eq!(Color32::TRANSPARENT.to_hex(), "#00000000");

Uses the 8-digit format described in https://drafts.csswg.org/css-color-4/#hex-color, as that is the only format that is lossless. For other formats, see HexColor.

Trait Implementations

impl Add for Color32

type Output = Color32

The resulting type after applying the + operator.

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

Performs the + operation.

impl Clone for Color32

fn clone(&self) -> Color32

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Color32

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

Prints the contents with premultiplied alpha!

impl Default for Color32

fn default() -> Color32

Returns the “default value” for a type.

impl From<Color32> for Hsva

fn from(srgba: Color32) -> Self

Converts to this type from the input type.

impl From<Color32> for HsvaGamma

fn from(srgba: Color32) -> Self

Converts to this type from the input type.

impl From<Color32> for Rgba

fn from(srgba: Color32) -> Self

Converts to this type from the input type.

impl From<Hsva> for Color32

fn from(hsva: Hsva) -> Self

Converts to this type from the input type.

impl From<HsvaGamma> for Color32

fn from(hsvag: HsvaGamma) -> Self

Converts to this type from the input type.

impl From<Rgba> for Color32

fn from(rgba: Rgba) -> Self

Converts to this type from the input type.

impl Hash for Color32

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<usize> for Color32

type Output = u8

The returned type after indexing.

fn index(&self, index: usize) -> &u8

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for Color32

fn index_mut(&mut self, index: usize) -> &mut u8

Performs the mutable indexing (container[index]) operation.

impl Mul for Color32

fn mul(self, other: Self) -> Self

Fast gamma-space multiplication.

type Output = Color32

The resulting type after applying the * operator.

impl PartialEq for Color32

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

fn zeroed() -> Self

Calls zeroed.

impl Copy for Color32

impl Eq for Color32

impl Pod for Color32

impl StructuralPartialEq for Color32