|
aest 0.1.0
Collection of C++ utility libraries
|
Partition aest.colors:operations: free functions that adjust colors. More...
#include <algorithm>#include <cmath>#include <concepts>#include <cstdint>import aest.colors:transfer;Go to the source code of this file.
Classes | |
| struct | aest::colors::Lightness< BasicHSL< RGB > > |
| Lightness of HSL, stored in the 0-1 range. More... | |
| struct | aest::colors::Lightness< OKLab > |
| Lightness of OKLab, the perceived lightness, 1 being D65 white. More... | |
| struct | aest::colors::Lightness< OKLCH > |
| Lightness of OKLCH, the perceived lightness, 1 being D65 white. More... | |
| struct | aest::colors::Interpolation< BasicRGB< Gamut, Transfer > > |
| Interpolation of an RGB space, channel by channel: linear spaces blend the light, encoded ones the encoded values. More... | |
| struct | aest::colors::Interpolation< XYZ > |
| Interpolation of XYZ, channel by channel: XYZ is linear in light. More... | |
| struct | aest::colors::Interpolation< OKLab > |
| Interpolation of OKLab, channel by channel: gradients with even perceived steps, like CSS color-mix(in oklab, …). More... | |
| struct | aest::colors::Interpolation< BasicHSL< RGB > > |
| Interpolation of HSL: the hue along an arc of the hue circle, saturation, lightness and alpha linearly. More... | |
| struct | aest::colors::Interpolation< BasicHSV< RGB > > |
| Interpolation of HSV: the hue along an arc of the hue circle, saturation, value and alpha linearly. More... | |
| struct | aest::colors::Interpolation< OKLCH > |
| Interpolation of OKLCH: the hue along an arc of the hue circle, lightness, chroma and alpha linearly, like CSS color-mix(in oklch, …). More... | |
| struct | aest::colors::Saturation< BasicHSL< RGB > > |
| Saturation of HSL, in the 0-1 range. More... | |
| struct | aest::colors::Saturation< BasicHSV< RGB > > |
| Saturation of HSV, in the 0-1 range. More... | |
| struct | aest::colors::Saturation< OKLCH > |
| Saturation of OKLCH: its chroma, which has no maximum, so saturate() scales it. More... | |
| struct | aest::colors::Hue< BasicHSL< RGB > > |
| Hue of HSL, in degrees. More... | |
| struct | aest::colors::Hue< BasicHSV< RGB > > |
| Hue of HSV, in degrees. More... | |
| struct | aest::colors::Hue< OKLCH > |
| Hue of OKLCH, in degrees. More... | |
Concepts | |
| concept | aest::colors::LightnessSpace |
| A color space whose lightness can be read and replaced through Lightness. | |
| concept | aest::colors::InterpolationSpace |
| A color space whose colors can be interpolated through Interpolation. | |
| concept | aest::colors::HueInterpolationSpace |
| A color space with a hue, whose Interpolation takes a HueMode. | |
| concept | aest::colors::SaturationSpace |
| A color space whose saturation can be read and replaced through Saturation. | |
| concept | aest::colors::BoundedSaturationSpace |
| A SaturationSpace whose saturation has a maximum, Saturation::MAX. | |
| concept | aest::colors::HueSpace |
| A color space whose hue can be read and replaced through Hue. | |
Enumerations | |
| enum class | aest::colors::HueMode : std::uint8_t { shorter , longer , increasing , decreasing } |
| How mix() goes around the hue circle between two hues, as in CSS Color 4. More... | |
Functions | |
| template<ColorType Space> | |
| constexpr Space | aest::colors::lerp_channels (const Space &from, const Space &to, const float amount) |
| Interpolates every channel of two colors, alpha included. | |
| constexpr float | aest::colors::chroma_scale (const float from, const float to, const float end) |
How much of a color's chroma is left when its lightness moves from from to to on a straight line toward end. | |
| template<LightnessSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::lighten (const Color &color, const float amount, In< Space > space={}) |
| Moves the lightness of a color a fraction of the way toward white. | |
| template<LightnessSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::darken (const Color &color, const float amount, In< Space > space={}) |
| Moves the lightness of a color a fraction of the way toward black. | |
| template<typename Space = void, ColorType Color> requires InterpolationSpace<WorkingSpace<Space, Color>> && ConvertibleTo<WorkingSpace<Space, Color>, Color> && ConvertibleTo <Color, WorkingSpace<Space, Color>> | |
| constexpr Color | aest::colors::mix (const Color &from, const Color &to, const float amount, In< Space > space={}) |
| Blends two colors. | |
| template<typename Space = void, ColorType From, ColorType To> requires (!std::same_as<From, To>) | |
| From | aest::colors::mix (const From &from, const To &to, float amount, In< Space > space={})=delete |
| Rejects blending colors of two different types. | |
| template<typename Space = void, ColorType Color> requires HueInterpolationSpace<WorkingSpace<Space, Color>> && ConvertibleTo<WorkingSpace<Space, Color>, Color> && ConvertibleTo <Color, WorkingSpace<Space, Color>> | |
| constexpr Color | aest::colors::mix (const Color &from, const Color &to, const float amount, const HueMode mode, In< Space > space={}) |
Blends two colors in a space with a hue, going around the hue circle the way mode picks. | |
| template<typename Space = void, ColorType From, ColorType To> requires (!std::same_as<From, To>) | |
| From | aest::colors::mix (const From &from, const To &to, float amount, HueMode mode, In< Space > space={})=delete |
| Rejects blending colors of two different types along a hue arc. | |
| template<ColorType Color> requires ConvertibleTo<XYZ, Color> | |
| constexpr float | aest::colors::luminance (const Color &color) |
| Relative luminance of a color: the light it emits, weighted by how bright each primary looks. | |
| template<ColorType Color1, ColorType Color2> requires ConvertibleTo<SRGB, Color1> && ConvertibleTo<SRGB, Color2> | |
| float | aest::colors::contrast_ratio (const Color1 &color1, const Color2 &color2) |
| WCAG 2.x contrast ratio between two colors, such as text and its background. | |
| template<SaturationSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::saturate (const Color &color, const float amount, In< Space > space={}) |
| Raises the saturation of a color. | |
| template<SaturationSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::desaturate (const Color &color, const float amount, In< Space > space={}) |
| Moves the saturation of a color a fraction of the way toward gray. | |
| template<SaturationSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::grayscale (const Color &color, In< Space > space={}) |
| Turns a color gray, keeping its lightness and alpha. | |
| template<HueSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::rotate_hue (const Color &color, const float degrees, In< Space > space={}) |
| Turns the hue of a color around the hue circle. | |
| template<HueSpace Space = OKLCH, ColorType Color> requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space> | |
| constexpr Color | aest::colors::complement (const Color &color, In< Space > space={}) |
| The complementary color: the hue turned by 180 degrees. | |
| template<BoundedRGBSpace Color> | |
| constexpr Color | aest::colors::invert (const Color &color) |
| Inverts each channel of an encoded RGB color, 1 - c, like CSS invert(); alpha is kept. | |
| constexpr float | aest::colors::lerp_hue (float from, float to, const float amount, const HueMode mode) |
Interpolates between two hues along the arc mode picks, as in CSS Color 4. | |
| constexpr float | aest::colors::lerp_hues (const float from, const bool fromGray, const float to, const bool toGray, const float amount, const HueMode mode) |
| Interpolates the hues of two colors, either of which may be gray. | |
Variables | |
| constexpr float | aest::colors::CONTRAST_FLARE = 0.05f |
| Viewing flare WCAG adds to both luminances of a contrast ratio. | |
| constexpr float | aest::colors::ACHROMATIC_CHROMA = 1e-4f |
| Chroma below which an OKLCH color counts as gray, with no hue. | |
Partition aest.colors:operations: free functions that adjust colors.
Definition in file Operations.cppm.
|
exportstrong |
How mix() goes around the hue circle between two hues, as in CSS Color 4.
Definition at line 147 of file Operations.cppm.
|
constexpr |
How much of a color's chroma is left when its lightness moves from from to to on a straight line toward end.
| [in] | from | The current lightness |
| [in] | to | The new lightness |
| [in] | end | The lightness of white or black, where chroma reaches 0 |
from is end. Definition at line 52 of file Operations.cppm.
|
constexprexport |
The complementary color: the hue turned by 180 degrees.
| Space | The color space the hue is turned in |
| Color | The color type of the input and the result |
| [in] | color | The color to complement |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
color. Definition at line 534 of file Operations.cppm.
|
export |
WCAG 2.x contrast ratio between two colors, such as text and its background.
Both colors are first converted to SRGB, as a display shows them, so HDR values clip to 1. The ratio is (L1 + 0.05) / (L2 + 0.05), with L1 the luminance() of the lighter color. Alpha is ignored: composite a translucent color onto its background with over() first.
| Color1 | Color type of color1 |
| Color2 | Color type of color2 |
| [in] | color1 | One of the colors; the order does not matter |
| [in] | color2 | The other color |
Definition at line 348 of file Operations.cppm.
|
constexprexport |
Moves the lightness of a color a fraction of the way toward black.
The color is converted to Space, its lightness l becomes l * (1 - amount) and it is converted back, keeping hue and alpha. By default Space is OKLCH, where chroma shrinks by the same fraction, so 1 gives exactly black; in HSL saturation is kept instead.
| Space | The color space the lightness is adjusted in |
| Color | The color type of the input and the result |
| [in] | color | The color to darken |
| [in] | amount | Fraction of the distance to black, clamped to the 0-1 range: 0 keeps the color, 1 gives black |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 133 of file Operations.cppm.
|
constexprexport |
Moves the saturation of a color a fraction of the way toward gray.
The color is converted to Space, its saturation s becomes s * (1 - amount) and it is converted back, keeping hue, lightness and alpha. In the default, OKLCH, the chroma shrinks and the perceived lightness is kept; desaturate<HSL>(color, amount) works in HSL.
| Space | The color space the saturation is adjusted in |
| Color | The color type of the input and the result |
| [in] | color | The color to desaturate |
| [in] | amount | Fraction of the distance to gray, clamped to the 0-1 range: 0 keeps the color, 1 gives gray |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 448 of file Operations.cppm.
|
constexprexport |
Turns a color gray, keeping its lightness and alpha.
The saturation becomes 0 in Space. In the default, OKLCH, the gray has the perceived lightness of the color: pure yellow gives a light gray and pure blue a dark one, where HSL gives both the same middle gray.
| Space | The color space the saturation is removed in |
| Color | The color type of the input and the result |
| [in] | color | The color to turn gray |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 472 of file Operations.cppm.
|
constexprexport |
Inverts each channel of an encoded RGB color, 1 - c, like CSS invert(); alpha is kept.
It works on the encoded values, as a photo negative of the pixels does, so a mid gray of SRGB 0.5 stays the same.
| Color | An encoded RGB space, such as SRGB |
| [in] | color | The color to invert |
Definition at line 552 of file Operations.cppm.
|
constexpr |
Interpolates every channel of two colors, alpha included.
| Space | A color space whose channels interpolate linearly, built from (ch1, ch2, ch3, alpha) |
| [in] | from | The color at amount 0 |
| [in] | to | The color at amount 1 |
| [in] | amount | Position between the two colors, in the 0-1 range |
Definition at line 37 of file Operations.cppm.
|
constexpr |
Interpolates between two hues along the arc mode picks, as in CSS Color 4.
| [in] | from | The hue at amount 0, in degrees in the [0, 360) range |
| [in] | to | The hue at amount 1, in degrees in the [0, 360) range |
| [in] | amount | Position between the two hues, in the 0-1 range |
| [in] | mode | The arc to follow |
Definition at line 577 of file Operations.cppm.
|
constexpr |
Interpolates the hues of two colors, either of which may be gray.
A gray color has no hue, so it takes the hue of the other: a gradient from gray to red stays red instead of sweeping through other hues. Two grays give hue 0.
| [in] | from | The hue of the color at amount 0 |
| [in] | fromGray | Whether that color is gray |
| [in] | to | The hue of the color at amount 1 |
| [in] | toGray | Whether that color is gray |
| [in] | amount | Position between the two colors, in the 0-1 range |
| [in] | mode | The arc to follow |
Definition at line 622 of file Operations.cppm.
|
constexprexport |
Moves the lightness of a color a fraction of the way toward white.
The color is converted to Space, its lightness l becomes l + (1 - l) * amount and it is converted back, keeping hue and alpha. By default Space is OKLCH, so equal amounts make equal perceived steps for every hue: chroma shrinks by the same fraction, so the color moves on a straight line toward white and 1 gives exactly white. In HSL, lighten<HSL>(color, amount), saturation is kept instead.
| Space | The color space the lightness is adjusted in |
| Color | The color type of the input and the result |
| [in] | color | The color to lighten |
| [in] | amount | Fraction of the distance to white, clamped to the 0-1 range: 0 keeps the color, 1 gives white |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 105 of file Operations.cppm.
|
constexprexport |
Relative luminance of a color: the light it emits, weighted by how bright each primary looks.
The Y of the color converted to XYZ, ignoring alpha: for LinSRGB, its channels weighted with the Rec. 709 / sRGB coefficients, about 0.2126, 0.7152 and 0.0722, and likewise for every gamut with its own matrix. White gives 1 and black 0; HDR colors give more than 1.
| Color | The color type of color |
| [in] | color | The color to measure |
Definition at line 324 of file Operations.cppm.
|
constexprexport |
Blends two colors in a space with a hue, going around the hue circle the way mode picks.
Like mix(), but the working space must have a hue, so it is named explicitly: mix<OKLCH>(from, to, amount, HueMode::longer) blends through the hues on the long way around, as CSS color-mix(in oklch longer hue, …) does. Gray colors take the hue of the other color. The default space, linear light, has no hue, so the call fails its constraint without one.
| Space | The color space with a hue the colors are blended in, such as OKLCH or HSL |
| Color | The color type of the inputs and the result |
| [in] | from | The color at amount 0 |
| [in] | to | The color at amount 1 |
| [in] | amount | Fraction of the way from from to to, clamped to the 0-1 range: 0 gives from, 1 gives to |
| [in] | mode | The arc of the hue circle to follow |
| [in] | space | The working space, e.g. in<OKLCH> |
Definition at line 277 of file Operations.cppm.
|
constexprexport |
Blends two colors.
Both colors are converted to the working space, interpolated there channel by channel, alpha included, and converted back. By default it is the LinearSpaceOf Color, linear light in the color's own gamut: LinSRGB for SRGB and HSL, LinDisplayP3 for DisplayP3. That blends the light physically without clipping wide-gamut colors to sRGB, and linear blending gives the same result in every linear gamut otherwise. mix<SRGB>(from, to, amount) blends the encoded values instead, like CSS color-mix(in srgb, …), which gives darker midpoints.
Both colors have the same type. To blend colors of two spaces, convert one into the other's first, into the wider gamut so nothing clips: mix(convert<DisplayP3>(srgbColor), p3Color, amount).
| Space | The color space the colors are blended in; void, the default, follows Color |
| Color | The color type of the inputs and the result |
| [in] | from | The color at amount 0 |
| [in] | to | The color at amount 1 |
| [in] | amount | Fraction of the way from from to to, clamped to the 0-1 range: 0 gives from, 1 gives to |
| [in] | space | The working space, e.g. in<SRGB>; the LinearSpaceOf Color when omitted |
Definition at line 208 of file Operations.cppm.
|
exportdelete |
Rejects blending colors of two different types along a hue arc.
As for the overload without a HueMode, convert one color into the other's type first, into the wider gamut so nothing clips.
| Space | The color space the colors would be blended in |
| From | Color type of from |
| To | Color type of to, other than From |
| [in] | from | The color at amount 0 |
| [in] | to | The color at amount 1 |
| [in] | amount | Fraction of the way from from to to |
| [in] | mode | The arc of the hue circle to follow |
| [in] | space | The working space |
|
exportdelete |
Rejects blending colors of two different types.
No result type fits every pair: gamuts are not nested, so neither is always the wider one, and taking the type of from would make mix() depend on the order of its arguments. Convert one color into the other's type first, into the wider gamut so nothing clips: mix(convert<DisplayP3>(srgbColor), p3Color, amount).
| Space | The color space the colors would be blended in |
| From | Color type of from |
| To | Color type of to, other than From |
| [in] | from | The color at amount 0 |
| [in] | to | The color at amount 1 |
| [in] | amount | Fraction of the way from from to to |
| [in] | space | The working space |
|
constexprexport |
Turns the hue of a color around the hue circle.
The color is converted to Space, its hue moves by degrees and it is converted back, keeping the rest. In the default, OKLCH, the perceived lightness and chroma are kept, so the rotated color looks as bright as the original; it may fall outside the gamut and clip when converted back. Gray colors have no hue and stay as they are.
| Space | The color space the hue is turned in |
| Color | The color type of the input and the result |
| [in] | color | The color to rotate |
| [in] | degrees | The angle to add to the hue, any finite value |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 516 of file Operations.cppm.
|
constexprexport |
Raises the saturation of a color.
The color is converted to Space, its saturation raised and converted back, keeping hue, lightness and alpha. How depends on the space:
amount clamped to the 0-1 range, so 1 gives full saturation.amount 0 or greater, so 1 doubles it.In the default, OKLCH, equal amounts look equal across hues and the perceived lightness is kept; a raised chroma can leave the gamut and clip when converted back.
| Space | The color space the saturation is adjusted in |
| Color | The color type of the input and the result |
| [in] | color | The color to saturate |
| [in] | amount | How much to raise the saturation, as above; negative values keep the color |
| [in] | space | The working space, e.g. in<HSL>; OKLCH when omitted |
Definition at line 416 of file Operations.cppm.
|
constexpr |
Chroma below which an OKLCH color counts as gray, with no hue.
Converting an sRGB gray leaves float noise of about 1e-7 in its chroma; a just noticeable difference is about 0.02.
Definition at line 566 of file Operations.cppm.
|
constexpr |
Viewing flare WCAG adds to both luminances of a contrast ratio.
Definition at line 25 of file Operations.cppm.