|
aest 0.1.0
Collection of C++ utility libraries
|
How aest.colors is put together: the color type model, the conversion tree, the way operations pick a working space, and which parts run at compile time. Extending shows how to add to it.
Every color is four floats: three channels and alpha. The channels mean different things in each color space, so each space is its own type and the compiler keeps them apart: an SRGB value cannot be passed where an HSL one is expected, and the conversion between them is always explicit.
| Family | Spaces | Channels |
|---|---|---|
| Encoded | SRGB, DisplayP3, Rec709, Rec2020, Rec2100PQ, Rec2100HLG | RGB with a transfer function: what displays, files and CSS store |
| Linear | LinSRGB, LinDisplayP3, LinRec2020, ACEScg, Premultiplied<S> | Proportional to light: blending, lighting and compositing belong here |
| Derived | HSL, HSV, BasicHSL<S>, BasicHSV<S> | Cylindrical views of an encoded RGB space, for picking and adjusting colors |
| Absolute | XYZ | CIE 1931 tristimulus values, independent of any display: links the gamuts |
| Perceptual | OKLab, OKLCH, CIELab, CIELCH | Spaced as the eye sees: color differences, perceptual gradients and adjustments |
Each constructor brings its channels into the range of its space, so a value of a color type is always valid for that space.
| Space | Channels | Alpha |
|---|---|---|
| Encoded RGB | Clamped to [0, 1] | [0, 1] |
| Linear RGB | Clamped at 0, unbounded above: values over 1 are HDR light | [0, 1] |
| Premultiplied<S> | Clamped like S | [0, 1] |
| HSL, HSV | Hue wrapped to [0, 360); saturation, lightness/value clamped to [0, 1] | [0, 1] |
| XYZ | Unclamped: colors outside a gamut clip only when converted to it | [0, 1] |
| OKLab | Unclamped | [0, 1] |
| OKLCH | Lightness unclamped; chroma clamped at 0; hue wrapped to [0, 360) | [0, 1] |
| CIELab | Unclamped | [0, 1] |
| CIELCH | Lightness unclamped; chroma clamped at 0; hue wrapped to [0, 360) | [0, 1] |
Channels must be finite: NaN and infinities are a precondition violation, not a value the constructors repair.
An RGB space is fixed by two independent choices, each a tag type:
BasicRGB<Gamut, Transfer> combines them, and the aliases name the usual pairs. aest::colors::RGBName builds the TYPE from the tags, as the transfer prefix then the gamut name (Lin + SRGB), and is specialized where a space has its own name, as ACEScg does.
| Gamut | tf::SRGB | tf::Linear | tf::Rec709 | tf::PQ | tf::HLG |
|---|---|---|---|---|---|
| gamut::SRGB | SRGB | LinSRGB | Rec709 | ||
| gamut::DisplayP3 | DisplayP3 | LinDisplayP3 | |||
| gamut::Rec2020 | LinRec2020 | Rec2020 | Rec2100PQ | Rec2100HLG | |
| gamut::AP1 | ACEScg |
Linear 1.0 is the reference white everywhere: the brightest SDR white, and 203 cd/m² (aest::colors::REFERENCE_WHITE_NITS) for PQ, after ITU-R BT.2408. So an SDR color and an HDR one convert into each other without a scale factor, and SRGB white lands on the PQ and HLG reference white.
Alpha is straight in every space but aest::colors::Premultiplied: the color channels do not depend on it. Conversions keep it unchanged; between a linear space and its premultiplied form they multiply or divide the channels by it, and a premultiplied color with alpha 0 comes back as transparent black, since its light is lost. Operations that move a color, such as lighten(), keep it too, and so do the scalar operators, which scale only the light; those that combine colors, mix() and the linear-space operators between two colors, combine it like the other channels. aest::colors::over() composites in premultiplied linear light, where coverage and light add up correctly, and returns straight alpha in the background's type.
aest::colors::convert() reaches any color space from any other. The spaces form a tree, declared by aest::colors::ParentSpace, and each space provides aest::colors::Converter specializations to and from its parent:
Every BasicRGB<G, tf::Linear> is a child of XYZ, and every other BasicRGB<G, T> a child of BasicRGB<G, tf::Linear>: the links and their converters are partial specializations, so a new gamut or transfer function joins the tree without code of its own. Likewise BasicHSL<S> and BasicHSV<S> are children of the encoded space S, with the HSL ↔ HSV shortcut between the two over the same S.
A conversion takes one of two routes:
The route is chosen at compile time. aest::colors::ConvertibleTo tells whether one exists, and the operations are constrained on it, so a space outside the tree is rejected when the call is resolved.
Each step goes through a constructor, so it clamps to the range of the intermediate space. HDR light is lost wherever a path crosses SRGB: LinSRGB values above 1 clip to 1 there. Colors outside a gamut lose their negative channels where a path enters its linear space from XYZ, as P3 red does in LinSRGB. lighten() and darken() work in OKLCH, which is unclamped, so the step to it keeps HDR light and wide gamuts; the result clips only if it falls outside the input's own range when converted back. mix() and the arithmetic operators stay in linear light and keep HDR values. Every hop also costs some float precision: a direct shortcut is worth adding when a pair is converted often.
Operations are free functions, such as lighten(), mix() and euclidean(). Each is written once, generically, and works in a working space:
The working space is a template parameter with a default, picked either explicitly or with a trailing aest::colors::in tag: lighten<HSL>(color, 0.2f) is lighten(color, 0.2f, in<HSL>). A concept on the trait (LightnessSpace, SaturationSpace, HueSpace, InterpolationSpace, EuclideanSpace) rejects spaces where the operation has no meaning, such as Euclidean distance over a hue angle.
The defaults are part of the API: they never change silently, because the same call would start giving different colors. The operations that judge colors by eye default to the perceptual spaces: lighten() and darken() to OKLCH, euclidean() to OKLab. The aest::colors::Lightness trait passes the end a color moves toward, white or black, to set, so OKLCH and OKLab can shrink chroma on the way and reach that end exactly; HSL ignores it. mix() and over() default to void, which aest::colors::LinearSpaceOf resolves to linear light in the input's own gamut, so a default never clips a wide-gamut color to sRGB. A default template argument cannot name a later parameter, so void stands in for "the input's" while keeping the space the first template argument. Operations that combine two colors take them as one type; mix() deletes the overload for two types rather than pick one of them for the result, with or without a HueMode. The overload with a HueMode is constrained on aest::colors::HueInterpolationSpace, the spaces whose Interpolation takes the mode, so asking for a hue arc in a space without a hue fails at the call.
The library targets C++20, where <cmath> is not constexpr. Code paths that need it run only at run time; the rest is constexpr on GCC, Clang and MSVC.
| Compile time | Run time only |
|---|---|
| Construction, hex and byte packing, opacity(), == | tf::SRGB, tf::Rec709, tf::PQ and tf::HLG (std::pow, std::log) |
| Encoded RGB ↔ HSL ↔ HSV conversions | euclidean(), de_76(), de_94(), de_2000() (std::sqrt) |
| lighten(), darken(), saturate(), desaturate(), grayscale(), rotate_hue(), complement() and mix() when no step needs <cmath> | Anything through an encoding |
| Premultiplied conversions, over() of linear colors | contrast_ratio() (std::pow) |
| luminance() of linear colors | |
| OKLab → XYZ, CIELab → XYZ | OKLab, CIELab ← XYZ (std::cbrt), OKLab ↔ OKLCH, CIELab ↔ CIELCH (std::atan2, std::cos) |
| Linear RGB ↔ XYZ (matrices derived at compile time) | |
| Tonemapping operators | |
| invert() | |
| Packing and unpacking, to_half() and from_half() |
A function marked constexpr whose path reaches a run-time step simply cannot be used in a constant expression for those arguments: mix() of two LinSRGB colors is a constant expression, while mix() of two SRGB colors, which converts through LinSRGB, is not.