Enum Color 

#[non_exhaustive]
pub enum Color {
    Default,
    Ansi(AnsiColor),
    Indexed(u8),
    Rgb {
        r: u8,
        g: u8,
        b: u8,
    },
}

Represents a color in the terminal grid.

Examples

use retroglyph_core::color::Color;

let named = Color::GREEN;
let rgb = Color::rgb(255, 0, 0);
let indexed = Color::Indexed(42);
assert_ne!(named, rgb);
assert_ne!(rgb, indexed);

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Default

Backend’s default foreground/background color.

This tells the rendering backend to use the terminal’s configured default colors (e.g., the user’s background color preference).

Ansi(AnsiColor)

One of the 16 standard ANSI colors.

Use these to respect the user’s terminal theme.

Indexed(u8)

256-color palette index.

Rgb

24-bit RGB color.

Use this for exact color matching regardless of terminal settings.

Fields

r: u8

Red channel.

g: u8

Green channel.

b: u8

Blue channel.

Implementations

impl Color

pub const BLACK: Color

Standard Black (ANSI).

pub const RED: Color

Standard Red (ANSI).

pub const GREEN: Color

Standard Green (ANSI).

pub const YELLOW: Color

Standard Yellow (ANSI).

pub const BLUE: Color

Standard Blue (ANSI).

pub const MAGENTA: Color

Standard Magenta (ANSI).

pub const CYAN: Color

Standard Cyan (ANSI).

pub const WHITE: Color

Standard White (ANSI).

pub const BRIGHT_BLACK: Color

Bright Black / dark grey (ANSI).

pub const BRIGHT_RED: Color

Bright Red (ANSI).

pub const BRIGHT_GREEN: Color

Bright Green (ANSI).

pub const BRIGHT_YELLOW: Color

Bright Yellow (ANSI).

pub const BRIGHT_BLUE: Color

Bright Blue (ANSI).

pub const BRIGHT_MAGENTA: Color

Bright Magenta (ANSI).

pub const BRIGHT_CYAN: Color

Bright Cyan (ANSI).

pub const BRIGHT_WHITE: Color

Bright White (ANSI).

pub const fn rgb(r: u8, g: u8, b: u8) -> Color

Constructs an Rgb variant from its three channels.

pub const fn hex(rgb: u32) -> Color

Constructs an Rgb variant from a packed 0xRRGGBB value. The high byte is ignored.

Round-trips the #rrggbb form Display writes, so a color logged out of a running app can be pasted straight back into source. Unlike from_hex, there is no CSS short-form expansion: Color::hex(0xF80) is #000f80, not #ff8800.

pub const fn resolve_rgb(self, default: (u8, u8, u8)) -> (u8, u8, u8)

Resolves this color to a concrete 24-bit (r, g, b) triple, substituting default for Color::Default.

This is the canonical color-to-RGB resolution every graphical backend shares, so that a glyph drawn through the CPU rasterizer (retroglyph-software) and the GPU atlas (retroglyph-gl) comes out the same pixel color:

• Rgb passes through unchanged.
• Ansi resolves through AnsiColor::to_rgb (the one canonical ANSI palette).
• Indexed resolves through the 256-color palette (16 ANSI + 6×6×6 cube
  • grayscale ramp).
• Default (and any future non-exhaustive variant this crate can’t yet resolve) returns default, which the caller picks per channel (foreground vs background).

Terminal backends do not use this: they emit ANSI/indexed colors as-is and let the terminal apply the user’s theme. It exists specifically for pixel/GPU backends that must produce real RGB.

pub fn to_srgb(self) -> Option<Srgb>

Converts an Rgb variant to gem::space::Srgb.

Returns None for non-RGB variants (Default, Ansi, Indexed).

pub fn from_srgb(srgb: Srgb) -> Color

Constructs an Rgb variant from a gem::space::Srgb color.

Channels are clamped to [0.0, 1.0] and rounded to the nearest u8 (ties away from zero), via gem::rgb::Rgb888’s own Srgb conversion, the same round-to-nearest rule every other integer channel operation in this crate follows (see tests/rounding_conformance.rs).

pub fn lerp(a: Color, b: Color, t: f32) -> Color

Linearly interpolates between two colors, always returning a concrete Rgb result.

Both inputs are resolved to (r, g, b) via Color::resolve_rgb before blending, so non-Rgb variants (Ansi, Indexed) contribute their real color rather than being skipped. Color::Default has no intrinsic RGB value, so it falls back to (0, 0, 0) when it appears as a and (255, 255, 255) when it appears as b.

pub fn lighten(self, amount: f32) -> Color

Lightens a color by amount (0.0 = no change, 1.0 = white).

Non-Rgb variants are resolved to (r, g, b) via Color::resolve_rgb before the transform is applied, rather than being returned unchanged. Color::Default has no intrinsic RGB value, so it resolves to (0, 0, 0).

pub fn darken(self, amount: f32) -> Color

Darkens a color by amount (0.0 = no change, 1.0 = black).

Non-Rgb variants are resolved to (r, g, b) via Color::resolve_rgb before the transform is applied, rather than being returned unchanged. Color::Default has no intrinsic RGB value, so it resolves to (0, 0, 0).

pub fn saturate(self, amount: f32) -> Color

Increases saturation of a color by amount (0.0–1.0).

Non-Rgb variants are resolved to (r, g, b) via Color::resolve_rgb before the transform is applied, rather than being returned unchanged. Color::Default has no intrinsic RGB value, so it resolves to (0, 0, 0).

pub fn desaturate(self, amount: f32) -> Color

Decreases saturation of a color by amount (0.0–1.0).

Non-Rgb variants are resolved to (r, g, b) via Color::resolve_rgb before the transform is applied, rather than being returned unchanged. Color::Default has no intrinsic RGB value, so it resolves to (0, 0, 0).

pub fn complement(self) -> Color

Returns the complementary color (hue shifted by 180 degrees).

Non-Rgb variants are resolved to (r, g, b) via Color::resolve_rgb before the transform is applied, rather than being returned unchanged. Color::Default has no intrinsic RGB value, so it resolves to (0, 0, 0).

pub fn to_indexed(self) -> Color

Quantizes an RGB color to the nearest entry in the standard 256-color palette, by perceptual (Oklab) distance.

Equivalent to to_indexed_with(Quantize::Perceptual); see there for the full contract and for the euclidean alternative.

Examples

use retroglyph_core::color::Color;

let black = Color::rgb(0, 0, 0);
assert_eq!(black.to_indexed(), Color::Indexed(0));

// Non-RGB colors pass through unchanged.
assert_eq!(Color::Default.to_indexed(), Color::Default);

Backends that render to terminals without full RGB support can call this method to downgrade colors before emitting them; retroglyph-core never downgrades colors on its own. See Color::to_ansi to quantize to the smaller 16-color ANSI palette.

pub fn to_indexed_with(self, metric: Quantize) -> Color

Quantizes an RGB color to the nearest entry in the standard 256-color palette, under metric.

• Color::Rgb inputs are converted to the nearest 256-color palette index (0–255), searching the 16 ANSI colors (0–15), the 6×6×6 color cube (16–231), and the grayscale ramp (232–255).
• Color::Default, Color::Ansi, and Color::Indexed are returned unchanged: this method only downgrades Rgb colors.
• Ties (multiple equidistant palette entries) are resolved by preferring the lower index.

Examples

use retroglyph_core::color::{Color, Quantize};

let salmon = Color::rgb(250, 128, 114);
assert_eq!(salmon.to_indexed_with(Quantize::Perceptual), Color::Indexed(210));
assert_eq!(salmon.to_indexed_with(Quantize::Euclidean), Color::Indexed(209));

pub fn to_ansi(self) -> Color

Quantizes an RGB color to the nearest of the 16 standard ANSI palette colors, by perceptual (Oklab) distance.

Equivalent to to_ansi_with(Quantize::Perceptual); see there for the full contract and for the euclidean alternative.

Examples

use retroglyph_core::color::{AnsiColor, Color};

let pure_red = Color::rgb(255, 0, 0);
assert_eq!(pure_red.to_ansi(), Color::Ansi(AnsiColor::BrightRed));

// Non-RGB colors pass through unchanged.
assert_eq!(Color::Default.to_ansi(), Color::Default);

Use this method when rendering to terminals limited to 16 colors, or when a caller otherwise needs to reduce color depth. See Color::to_indexed to quantize to the larger 256-color palette instead.

pub fn to_ansi_with(self, metric: Quantize) -> Color

Quantizes an RGB color to the nearest of the 16 standard ANSI palette colors, under metric.

• Color::Rgb inputs are converted to the nearest of the 16 standard ANSI colors.
• Color::Default, Color::Ansi, and Color::Indexed are returned unchanged: this method only downgrades Rgb colors.
• Ties (multiple equidistant palette entries) are resolved by preferring the lower ANSI index.

Examples

use retroglyph_core::color::{AnsiColor, Color, Quantize};

// Euclidean RGB distance over-weights green, so this reddish brown lands on yellow.
let chocolate = Color::rgb(210, 105, 30);
assert_eq!(chocolate.to_ansi_with(Quantize::Perceptual), Color::Ansi(AnsiColor::BrightRed));
assert_eq!(chocolate.to_ansi_with(Quantize::Euclidean), Color::Ansi(AnsiColor::Yellow));

impl Color

pub fn from_named(name: &str) -> Option<Color>

Looks up a CSS named color by name (case-insensitive).

Supports all 147 CSS Color Module Level 4 named colors. Returns None for unrecognized names.

Examples

use retroglyph_core::color::Color;

let gold = Color::from_named("gold");
assert_eq!(gold, Some(Color::rgb(255, 215, 0)));

assert_eq!(Color::from_named("not-a-color"), None);

pub fn from_hex(hex: &str) -> Option<Color>

Parses a CSS hex color string into an Rgb variant.

Accepts #rgb and #rrggbb formats (case-insensitive). Returns None for invalid input.

Examples

use retroglyph_core::color::Color;

let c = Color::from_hex("#ff8000")?;
assert_eq!(c, Color::rgb(255, 128, 0));

assert_eq!(Color::from_hex("not-color"), None);

Trait Implementations

impl Clone for Color

fn clone(&self) -> Color

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Color

impl Debug for Color

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

Formats the value using the given formatter.

impl Default for Color

fn default() -> Color

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Color

Available on crate feature serde only.

fn deserialize<D>( deserializer: D, ) -> Result<Color, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserializes through FromStr, so every string Display can produce, plus every alias FromStr additionally accepts (e.g. "BrightRed", "#f80"), round-trips.

impl Display for Color

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

Writes the string form FromStr parses back and, with the serde feature, Serialize writes: "default", an ANSI name like "bright-red", a palette index like "42", or #rrggbb hex.

Examples

use retroglyph_core::color::{AnsiColor, Color};

assert_eq!(Color::Default.to_string(), "default");
assert_eq!(Color::Ansi(AnsiColor::BrightRed).to_string(), "bright-red");
assert_eq!(Color::Indexed(42).to_string(), "42");
assert_eq!(Color::rgb(255, 128, 0).to_string(), "#ff8000");

impl Eq for Color

impl FromStr for Color

fn from_str(s: &str) -> Result<Color, <Color as FromStr>::Err>

Parses the string form written by Display.

Hyphens, underscores, and spaces are ignored and matching is case-insensitive, so "BrightRed", "bright red", and "bright-red" all parse the same as the canonical "bright-red" that Display writes. "reset" is accepted as a synonym for "default". Accepts #rgb in addition to the #rrggbb Display writes.

Examples

use retroglyph_core::color::{AnsiColor, Color};

assert_eq!("default".parse(), Ok(Color::Default));
assert_eq!("reset".parse(), Ok(Color::Default));
assert_eq!("bright-red".parse(), Ok(Color::Ansi(AnsiColor::BrightRed)));
assert_eq!("Bright Red".parse(), Ok(Color::Ansi(AnsiColor::BrightRed)));
assert_eq!("42".parse(), Ok(Color::Indexed(42)));
assert_eq!("#ff8000".parse(), Ok(Color::rgb(255, 128, 0)));
assert_eq!("#f80".parse(), Ok(Color::rgb(255, 136, 0)));
assert!("not-a-color".parse::<Color>().is_err());

type Err = ParseColorError

The associated error which can be returned from parsing.

impl Hash for Color

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

where __H: Hasher,

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 PartialEq for Color

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

Available on crate feature serde only.

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serializes through the Display round trip, e.g. "bright-red" or "#ff8000", rather than deriving a structural form: a hand-edited TOML/JSON theme file stays legible and isn’t coupled to this (#[non_exhaustive]) enum’s variant shape.

impl StructuralPartialEq for Color