aest 0.1.0
Collection of C++ utility libraries
Loading...
Searching...
No Matches
Colors

aest.colors provides color types, conversions and color operations in the aest::colors namespace.

Color types

Every color has float channels and alpha, is built on aest::colors::ColorBase and is checked by the aest::colors::ColorType concept.

aest::colors::BasicRGB is an RGB space made of a gamut tag from aest::colors::gamut (primaries and white point) and a transfer function tag from aest::colors::tf. Encoded spaces clamp their channels to [0, 1]; linear ones (tf::Linear) clamp at 0 only, so they hold HDR values, and have the arithmetic operators. The aliases name the usual spaces:

Alias Gamut Transfer
aest::colors::SRGB gamut::SRGB tf::SRGB
aest::colors::LinSRGB gamut::SRGB tf::Linear
aest::colors::DisplayP3 gamut::DisplayP3 tf::SRGB
aest::colors::LinDisplayP3 gamut::DisplayP3 tf::Linear
aest::colors::LinRec2020 gamut::Rec2020 tf::Linear
aest::colors::ACEScg gamut::AP1 tf::Linear
aest::colors::Rec709 gamut::SRGB tf::Rec709
aest::colors::Rec2020 gamut::Rec2020 tf::Rec709
aest::colors::Rec2100PQ gamut::Rec2020 tf::PQ
aest::colors::Rec2100HLG gamut::Rec2020 tf::HLG

SRGB is the encoding of hex codes, bytes and CSS; convert to a linear space for color math. aest::colors::RGBSpace, aest::colors::LinearRGBSpace and aest::colors::BoundedRGBSpace tell the kinds apart.

Rec709 and Rec2020 are the SDR video encodings: Rec709 has the sRGB primaries, so it differs from SRGB only in its curve, the OETF of ITU-R BT.709, which ITU-R BT.2020 shares for SDR. Like HLG, the library applies the OETF and its inverse, so the linear values are scene light; a display decodes the signal with BT.1886 instead, about a 2.4 power. Channels are full range: the library has no limited "TV" range.

Rec2100PQ and Rec2100HLG are the HDR signals of ITU-R BT.2100. Linear 1.0 is the BT.2408 reference white, aest::colors::REFERENCE_WHITE_NITS, 203 cd/m²: PQ encodes it to 58% and reaches 10000 cd/m² at linear 49.26; HLG encodes it to 75% and reaches its peak at linear 3.77, without an OOTF. For a luminance in cd/m², divide by REFERENCE_WHITE_NITS first, as in tf::PQ::encode(1000.f / REFERENCE_WHITE_NITS).

  • aest::colors::BasicHSL, aest::colors::BasicHSV - hue, saturation and lightness or value, over an encoded RGB space: BasicHSL<DisplayP3> reaches the P3 colors that HSL over sRGB clips. aest::colors::HSL and aest::colors::HSV are the ones over SRGB, the HSL of CSS. A hue is relative to the primaries, so the same color has different hues over different gamuts. Linear spaces are rejected, since the formulas need channels in [0, 1].
  • aest::colors::XYZ - CIE 1931 XYZ relative to D65, independent of any display's primaries: the root of the conversion tree. Y is the relative luminance, and the channels are not clamped.
  • aest::colors::OKLab, aest::colors::OKLCH - the perceptual space by Björn Ottosson and its polar form: lightness L (1 for white), then a and b, or chroma and hue. Equal distances look about equally different, and changing OKLCH chroma or hue keeps the perceived lightness. The matrices are the ones of CSS Color 4, so D65 white has no chroma. Not clamped, so they hold HDR and out-of-gamut colors.
  • aest::colors::CIELab, aest::colors::CIELCH - CIE 1976 L*a*b* and its polar form, relative to D50 with the Bradford adaptation of CSS Color 4, so the values match CSS lab() and lch(): lightness L (100 for white), then a and b, or chroma and hue. They are the spaces of the CIE color difference formulas; OKLab is more even across hues for everything else. Not clamped.
  • aest::colors::Premultiplied - a linear color with premultiplied alpha, such as Premultiplied<LinSRGB>, for compositing.
  • from_hex(), from_rgba() and from_argb() build a color from a hex code, 8-bit channels or a packed 32-bit integer; to_rgba(), to_argb() and hex_string() pack it back, rounding each channel to the nearest byte. The values are always SRGB, the space hex codes and bytes are written in, and are converted from or to the color's own space: from_hex(0xFF7F50) is an SRGB color, from_rgba<HSL>(0, 120, 80) an HSL one, and to_rgba(color) clips a color outside the SRGB gamut. To store a color's own encoding instead, as for a GPU texture, use the pack_* functions.
  • aest::colors::ColorBase::opacity() - copies a color with a new alpha.
  • std::format("{}", color) prints the color space and its channels, as in SRGB(1.000, 0.000, 0.500, 1.000); a float spec such as {:.1f} applies to each channel.
  • Named CSS colors in aest::colors::css, such as aest::colors::css::teal.

Conversions

aest::colors::convert() converts between any two color spaces, keeping alpha. Each linear RGB space converts to XYZ with a matrix derived at compile time from the chromaticities of its gamut, so sRGB matches IEC 61966-2-1; ACEScg, whose white point is not D65, is adapted to it with the Bradford transform. A color outside the target gamut clips at 0, so P3 red loses its negative green and blue in LinSRGB. Pairs with an aest::colors::Converter specialization convert directly; the others go through the conversion tree declared by aest::colors::ParentSpace (see Architecture). Converting a color to its own type returns it unchanged. aest::colors::ConvertibleTo checks that a conversion exists.

Arithmetic

The linear spaces, LinSRGB and the other linear RGB spaces and XYZ, have +, - and * between two colors, and their compound forms, through aest::colors::ColorArithmetic. Every operator combines all four channels, alpha included, and clamps the result like the constructor does: the color channels at 0 only, so sums can exceed 1 and hold HDR light, and alpha to [0, 1]. The scalar operators color * s, s * color, color / s, *= and /= scale the three color channels and keep alpha, as exposure or a light's intensity would.

Premultiplied colors have + and scaling by a scalar too, but both apply to all four channels: that is how premultiplied light and coverage add up and fade.

Compositing

aest::colors::over() composites a color over another with Porter-Duff source-over: it converts both to premultiplied linear light, computes foreground + background * (1 - foreground alpha), and returns the result in the background's type. Its working space, an aest::colors::LinearSpace, is the first template argument; when omitted it is the aest::colors::LinearSpaceOf the background, linear light in the background's gamut, so P3 colors composite without clipping to sRGB.

Operations

Operations are free functions. Each works in a default color space, fixed so results never change silently; another space is picked as the first template argument, as in lighten<HSL>(color, 0.2f), or with a trailing aest::colors::in tag, as in lighten(color, 0.2f, in<HSL>), which is the same call. The result has the input's type. A space supports an operation by specializing the operation's trait.

Operation Does Default space Trait
aest::colors::lighten(), aest::colors::darken() Move a fraction of the way toward white or black, keeping hue and alpha OKLCH aest::colors::Lightness
aest::colors::mix() Blend two colors, alpha included: 0 gives the first, 1 the second Linear light in the input's gamut aest::colors::Interpolation
aest::colors::euclidean() Distance between two colors, ignoring alpha: ΔE_OK by default OKLab aest::colors::Euclidean
aest::colors::de_76(), aest::colors::de_94(), aest::colors::de_2000() The CIE color differences ΔE*ab, ΔE*94 and ΔE00, ignoring alpha CIELab, fixed None
aest::colors::saturate(), aest::colors::desaturate() Raise or lower saturation: in OKLCH scale the chroma by 1 + t or 1 - t; in HSL move a fraction of the way to full or gray OKLCH aest::colors::Saturation
aest::colors::grayscale() Remove the saturation, keeping the lightness: in OKLCH, the perceived one OKLCH aest::colors::Saturation
aest::colors::rotate_hue(), aest::colors::complement() Turn the hue by an angle, or by 180°, keeping lightness and chroma OKLCH aest::colors::Hue
aest::colors::invert() 1 - c on each encoded RGB channel, like CSS invert(), keeping alpha The color's own None

lighten() and darken() work in OKLCH, so equal amounts give equal perceived steps whatever the hue: in HSL, yellow and blue at the same lightness look far apart. Chroma shrinks by the same fraction as the distance to white or black, so the color moves in a straight line toward it, keeps its hue, and an amount of 1 gives exactly white or black. lighten<HSL>(color, amount) keeps the saturation instead. euclidean() measures ΔE_OK, the difference in OKLab, where equal distances look about equally different; about 0.02 is just noticeable. The CIE formulas measure in CIELab, where 100 separates black from white: de_76() is euclidean<CIELab>(), and overstates differences between saturated colors; de_94() scales the chroma and hue differences down as the chroma of its first color, the reference, grows, so it is not symmetric, and takes the weights for graphic arts or, with aest::colors::CIE94Application::textiles, textiles; de_2000(), the current CIE formula, is symmetric and corrects the blues and the near-grays too. A difference of about 2.3 in ΔE*ab, or 1 in ΔE00, is just noticeable. These defaults need std::cbrt, so they run at run time; the HSL and RGB ones stay constexpr. Results in OKLCH and OKLab can fall outside the input's gamut and clip when converted back. grayscale(), rotate_hue(), complement(), saturate() and desaturate() default to OKLCH for the same reason: the gray of pure yellow is light and the gray of pure blue dark, where HSL turns both into the same middle gray. OKLCH chroma has no maximum, so saturate() scales it, by 1 + amount with any amount of 0 or more, and desaturate() by 1 - amount. In a space with a maximum saturation, such as saturate<HSL>(color, amount), saturate() moves a fraction of the way to it instead and stays inside the gamut.

mix() blends in the aest::colors::LinearSpaceOf its color type: LinSRGB for SRGB and HSL, LinDisplayP3 for DisplayP3 and BasicHSL<DisplayP3>, XYZ for XYZ. Linear blending gives the same result in every linear gamut, so this only avoids clipping wide-gamut colors to sRGB. Both colors have one type: mix() of two different types is deleted, so convert one into the other's type first, into the wider gamut:

const DisplayP3 blend = mix(convert<DisplayP3>(srgbColor), p3Color, 0.5f);

Hue interpolation

In a space with a hue, HSL, HSV or OKLCH, mix() goes around the hue circle. An aest::colors::HueMode picks the arc, as in CSS Color 4:

Mode Arc
HueMode::shorter The shorter one, at most 180°: the default
HueMode::longer The longer one; equal hues make a full turn
HueMode::increasing Clockwise, toward greater hues
HueMode::decreasing Counterclockwise, toward smaller hues
// Red to blue through green instead of through magenta
const SRGB rainbow = mix<OKLCH>(red, blue, 0.5f, HueMode::longer);

The space is named explicitly, since the default, linear light, has no hue. A gray color, with saturation 0 in HSL and HSV or chroma below ACHROMATIC_CHROMA (1e-4) in OKLCH, has no hue either: it takes the hue of the other color, so a gradient from gray to red stays red. Without a mode, mix<OKLCH>(from, to, amount) takes the shorter arc.

Luminance and contrast

  • aest::colors::luminance() - the relative luminance of a color, the Y of its XYZ, ignoring alpha: for LinSRGB its channels weighted with the Rec. 709 coefficients, about 0.2126, 0.7152 and 0.0722. White gives 1, black 0, and HDR colors more than 1.
  • aest::colors::contrast_ratio() - the WCAG 2.x contrast ratio of two colors, from 1 to 21, in either order. Both are measured as a display shows them, through SRGB, so HDR values clip to white. Alpha is ignored: composite a translucent color onto its background with aest::colors::over() first.
const SRGB text = from_hex(0x777777);
const bool readable = contrast_ratio(text, css::white) >= 4.5f; // false: 4.48

Random colors

The caller passes the random generator, so the library keeps no hidden state: a seed reproduces the colors, and threads draw from their own generators.

  • aest::colors::random_color() - an opaque color with each channel drawn uniformly from [0, 1), in an encoded RGB space, SRGB by default. Uniform channels are not uniform to the eye: many draws come out dull or dark.
  • aest::colors::random_hue() - a copy of a color with a hue drawn uniformly from [0, 360), in OKLCH by default, so lightness, chroma and alpha stay. Drawing from one base color gives a palette whose colors look equally bright and vivid. The result can fall outside the gamut and clip when converted back, and a gray color stays gray. Another space is picked as the first template argument, as in random_hue<HSL>(color, generator).
std::mt19937 generator{seed};
const SRGB noise = random_color(generator);
const SRGB accent = random_hue(from_hex(0x3B82F6), generator);

Both take an aest::colors::RandomBitGenerator, a standard generator whose range is a power of two of at least 2^24, such as std::mt19937 or std::ranlux24; std::minstd_rand is rejected. Each channel is the low 24 bits of one output scaled to [0, 1), and not a std::uniform_real_distribution, whose algorithm each standard library picks: one seed gives the same colors with libstdc++, libc++ and the MSVC STL. random_color() takes three outputs, red first, and random_hue() one. Both are constexpr with a constexpr generator.

Tonemapping

The operators in aest::colors::tonemap compress HDR linear light into the [0, 1] range of a display. Each takes and returns a color of any linear RGB space and keeps alpha. Tonemapping lists their sources.

Operator Does
aest::colors::tonemap::reinhard() c / (1 + c) per channel: never clips, reaches white only at infinity
aest::colors::tonemap::reinhard_extended() c (1 + c / w²) / (1 + c) per channel: maps the white w to 1
aest::colors::tonemap::aces_fitted() Stephen Hill's fit of the ACES RRT and sRGB ODT, in LinSRGB: filmic contrast, desaturated highlights, clamped to [0, 1]
const LinSRGB hdr{4.f, 2.f, 0.5f};
const SRGB pixel = convert<SRGB>(tonemap::aces_fitted(hdr));

Packed formats

Functions to pack a color into the pixel formats of GPUs and back, with the bit layouts of Vulkan and Direct3D. Each pack_*() takes a color and returns the stored bits; each unpack_*<Color>() takes the bits and the color type to read them as. They are all constexpr.

Functions Vulkan format Layout Takes
aest::colors::pack_rgba8(), aest::colors::unpack_rgba8() R8G8B8A8_UNORM, R8G8B8A8_SRGB 4 bytes R, G, B, A, in memory order Any RGB space
aest::colors::pack_rgb10a2(), aest::colors::unpack_rgb10a2() A2B10G10R10_UNORM_PACK32 R bits 0-9, G 10-19, B 20-29, A 30-31 Any RGB space
aest::colors::pack_rgba16f(), aest::colors::unpack_rgba16f() R16G16B16A16_SFLOAT 4 halves R, G, B, A, in memory order Linear RGB
aest::colors::pack_r11g11b10f(), aest::colors::unpack_r11g11b10f() B10G11R11_UFLOAT_PACK32 R bits 0-10, G 11-21, B 22-31, no alpha Linear RGB
aest::colors::pack_rgb9e5(), aest::colors::unpack_rgb9e5() E5B9G9R9_UFLOAT_PACK32 R, G, B mantissas in bits 0-26, shared exponent 27-31, no alpha Linear RGB

The unorm formats clamp each channel to [0, 1] and store the color's own encoding: pack SRGB for an _SRGB format, a linear space for _UNORM data. The float formats clamp to their largest finite value, so a color never becomes infinite, and round to nearest even. Every format also takes the premultiplied form of a linear space, Premultiplied<LinSRGB>. aest::colors::PackableRGB and aest::colors::PackableLinearRGB name the accepted types.

aest::colors::to_half() and aest::colors::from_half() convert single floats to and from IEEE 754 halves, with IEEE rounding, infinities and NaN.

Design

  • Architecture - the type model, the conversion tree, how operations pick a working space, and what runs at compile time.
  • Extending - adding a color space or an operation.
  • Rendering - using the library in a rendering pipeline: linear light, HDR values and compositing.
  • References - the standards the library implements.