|
aest 0.1.0
Collection of C++ utility libraries
|
aest.colors provides color types, conversions and color operations in the aest::colors namespace.
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::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.
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.
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 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:
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 |
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.
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.
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.
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] |
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.