bevyengine/bevy

bevy_color

Color types and color-space conversions. Shared across rendering, UI, gizmos, and any other crate that needs to talk about color.

Purpose

Color is harder than it looks. bevy_color exists so the engine has a single canonical set of types, with explicit color spaces, and conversions between them. The crate provides:

One struct per color space (Srgba, LinearRgba, Hsla, Hsva, Hwba, Laba, Lcha, Oklaba, Oklcha, Xyza).
A union enum Color that can hold any of the above and dispatches operations to the variant.
Conversions between any pair via well-defined matrices.
Color manipulation (mix, lighten, darken, with_alpha) on each space.
Reflection and serde support.

Directory layout

crates/bevy_color/src/
├── lib.rs              # Color enum, ColorToComponents, ColorToPacked
├── srgba.rs            # Srgba (default for most user-facing color)
├── linear_rgba.rs      # LinearRgba (renderer's preferred space)
├── hsla.rs, hsva.rs, hwba.rs
├── laba.rs, lcha.rs    # CIE Lab/Lch
├── oklaba.rs, oklcha.rs # Ok Lab/Lch (perceptually uniform)
├── xyza.rs             # CIE XYZ (interchange)
├── color_difference.rs # Delta-E etc
├── color_ops.rs        # Mix, Luminance, Lighter, Darker traits
├── palettes/           # CSS color names, Material design palette, Tailwind, etc
└── …

Key abstractions

Type	File	Description
`Color`	`crates/bevy_color/src/lib.rs`	Tagged union of all spaces.
`Srgba`	`crates/bevy_color/src/srgba.rs`	Standard sRGB with linear alpha — what user input usually is.
`LinearRgba`	`crates/bevy_color/src/linear_rgba.rs`	Linear RGB — what shaders work in.
`Hsla`, `Hsva`, `Hwba`	`crates/bevy_color/src/{hsla,hsva,hwba}.rs`	Hue-based spaces.
`Oklaba`, `Oklcha`	`crates/bevy_color/src/{oklaba,oklcha}.rs`	Perceptually uniform; recommended for gradients and blending.
`Mix` / `Luminance` / `Lighter` / `Darker` traits	`crates/bevy_color/src/color_ops.rs`	Operations dispatched per space.
Palette modules	`crates/bevy_color/src/palettes/`	`css`, `tailwind`, `basic` named-color sets.

Each color space is a struct with named fields. Conversion between any pair goes through LinearRgba (sometimes Xyza for the CIE/perceptual spaces). The conversion matrices and gamma curves are in the corresponding files.

Color is a thin enum that delegates everything. It exists so user-facing APIs (UI text color, sprite tint, light color) can accept any space without generic gymnastics.

use bevy::prelude::*;

let c = Color::srgba(0.8, 0.4, 0.2, 1.0);
let lighter = c.lighter(0.2);                   // dispatches via Lighter trait
let lin: LinearRgba = c.into();                 // explicit conversion
let mixed = Oklcha::from(c).with_chroma(0.1);   // jump to perceptual space

Integration points

Depends on: bevy_math, bevy_reflect (optional), serde (optional).
Depended on by: bevy_render, bevy_pbr, bevy_sprite, bevy_ui, bevy_gizmos, bevy_text, bevy_gltf, bevy_audio (waveform visualization), …

Entry points for modification

New color space: new file at crates/bevy_color/src/<space>.rs. Implement the manipulation traits (Mix, Luminance, etc.) and add the variant to the Color enum in lib.rs.
Custom palette: add a module under palettes/. The existing palettes are constant Srgba values exported by name.
Color difference metric: color_difference.rs.