aest 0.1.0
Collection of C++ utility libraries
Loading...
Searching...
No Matches
Operations.cppm File Reference

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.

Detailed Description

Partition aest.colors:operations: free functions that adjust colors.

Author
Davide Pierotti

Definition in file Operations.cppm.

Enumeration Type Documentation

◆ HueMode

enum class aest::colors::HueMode : std::uint8_t
exportstrong

How mix() goes around the hue circle between two hues, as in CSS Color 4.

See also
CSS Color 4
Enumerator
shorter 

The shorter arc, at most 180 degrees: the default.

longer 

The longer arc, at least 180 degrees; equal hues make a full turn.

increasing 

Clockwise, toward greater hues, wrapping past 360.

decreasing 

Counterclockwise, toward smaller hues, wrapping past 0.

Definition at line 147 of file Operations.cppm.

Function Documentation

◆ chroma_scale()

float aest::colors::chroma_scale ( const float from,
const float to,
const float end )
constexpr

How much of a color's chroma is left when its lightness moves from from to to on a straight line toward end.

Parameters
[in]fromThe current lightness
[in]toThe new lightness
[in]endThe lightness of white or black, where chroma reaches 0
Returns
(to - end) / (from - end), or 1 when from is end.

Definition at line 52 of file Operations.cppm.

◆ complement()

template<HueSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::complement ( const Color & color,
In< Space > space = {} )
constexprexport

The complementary color: the hue turned by 180 degrees.

Template Parameters
SpaceThe color space the hue is turned in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to complement
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The complementary color, with the lightness and alpha of color.

Definition at line 534 of file Operations.cppm.

◆ contrast_ratio()

template<ColorType Color1, ColorType Color2>
requires ConvertibleTo<SRGB, Color1> && ConvertibleTo<SRGB, Color2>
float aest::colors::contrast_ratio ( const Color1 & color1,
const Color2 & color2 )
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.

Template Parameters
Color1Color type of color1
Color2Color type of color2
Parameters
[in]color1One of the colors; the order does not matter
[in]color2The other color
Returns
The contrast ratio, in the 1-21 range: 1 for equal luminances, 21 for black on white.
See also
WCAG 2.2

Definition at line 348 of file Operations.cppm.

◆ darken()

template<LightnessSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::darken ( const Color & color,
const float amount,
In< Space > space = {} )
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.

Template Parameters
SpaceThe color space the lightness is adjusted in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to darken
[in]amountFraction of the distance to black, clamped to the 0-1 range: 0 keeps the color, 1 gives black
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The darkened color.

Definition at line 133 of file Operations.cppm.

◆ desaturate()

template<SaturationSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::desaturate ( const Color & color,
const float amount,
In< Space > space = {} )
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.

Template Parameters
SpaceThe color space the saturation is adjusted in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to desaturate
[in]amountFraction of the distance to gray, clamped to the 0-1 range: 0 keeps the color, 1 gives gray
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The desaturated color.

Definition at line 448 of file Operations.cppm.

◆ grayscale()

template<SaturationSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::grayscale ( const Color & color,
In< Space > space = {} )
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.

Template Parameters
SpaceThe color space the saturation is removed in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to turn gray
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The gray color.

Definition at line 472 of file Operations.cppm.

◆ invert()

template<BoundedRGBSpace Color>
Color aest::colors::invert ( const Color & color)
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.

Template Parameters
ColorAn encoded RGB space, such as SRGB
Parameters
[in]colorThe color to invert
Returns
The inverted color.
See also
CSS Color 4

Definition at line 552 of file Operations.cppm.

◆ lerp_channels()

template<ColorType Space>
Space aest::colors::lerp_channels ( const Space & from,
const Space & to,
const float amount )
constexpr

Interpolates every channel of two colors, alpha included.

Template Parameters
SpaceA color space whose channels interpolate linearly, built from (ch1, ch2, ch3, alpha)
Parameters
[in]fromThe color at amount 0
[in]toThe color at amount 1
[in]amountPosition between the two colors, in the 0-1 range
Returns
The interpolated color.

Definition at line 37 of file Operations.cppm.

◆ lerp_hue()

float aest::colors::lerp_hue ( float from,
float to,
const float amount,
const HueMode mode )
constexpr

Interpolates between two hues along the arc mode picks, as in CSS Color 4.

Parameters
[in]fromThe hue at amount 0, in degrees in the [0, 360) range
[in]toThe hue at amount 1, in degrees in the [0, 360) range
[in]amountPosition between the two hues, in the 0-1 range
[in]modeThe arc to follow
Returns
The interpolated hue, wrapped to the [0, 360) range.

Definition at line 577 of file Operations.cppm.

◆ lerp_hues()

float aest::colors::lerp_hues ( const float from,
const bool fromGray,
const float to,
const bool toGray,
const float amount,
const HueMode mode )
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.

Parameters
[in]fromThe hue of the color at amount 0
[in]fromGrayWhether that color is gray
[in]toThe hue of the color at amount 1
[in]toGrayWhether that color is gray
[in]amountPosition between the two colors, in the 0-1 range
[in]modeThe arc to follow
Returns
The interpolated hue, wrapped to the [0, 360) range.

Definition at line 622 of file Operations.cppm.

◆ lighten()

template<LightnessSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::lighten ( const Color & color,
const float amount,
In< Space > space = {} )
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.

Template Parameters
SpaceThe color space the lightness is adjusted in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to lighten
[in]amountFraction of the distance to white, clamped to the 0-1 range: 0 keeps the color, 1 gives white
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The lightened color.

Definition at line 105 of file Operations.cppm.

◆ luminance()

template<ColorType Color>
requires ConvertibleTo<XYZ, Color>
float aest::colors::luminance ( const Color & color)
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.

Template Parameters
ColorThe color type of color
Parameters
[in]colorThe color to measure
Returns
The relative luminance, 0 or greater.
See also
WCAG 2.2

Definition at line 324 of file Operations.cppm.

◆ mix() [1/4]

template<typename Space = void, ColorType Color>
requires HueInterpolationSpace<WorkingSpace<Space, Color>> && ConvertibleTo<WorkingSpace<Space, Color>, Color> && ConvertibleTo
<Color, WorkingSpace<Space, Color>>
Color aest::colors::mix ( const Color & from,
const Color & to,
const float amount,
const HueMode mode,
In< Space > space = {} )
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.

Template Parameters
SpaceThe color space with a hue the colors are blended in, such as OKLCH or HSL
ColorThe color type of the inputs and the result
Parameters
[in]fromThe color at amount 0
[in]toThe color at amount 1
[in]amountFraction of the way from from to to, clamped to the 0-1 range: 0 gives from, 1 gives to
[in]modeThe arc of the hue circle to follow
[in]spaceThe working space, e.g. in<OKLCH>
Returns
The blended color.
See also
CSS Color 4

Definition at line 277 of file Operations.cppm.

◆ mix() [2/4]

template<typename Space = void, ColorType Color>
requires InterpolationSpace<WorkingSpace<Space, Color>> && ConvertibleTo<WorkingSpace<Space, Color>, Color> && ConvertibleTo
<Color, WorkingSpace<Space, Color>>
Color aest::colors::mix ( const Color & from,
const Color & to,
const float amount,
In< Space > space = {} )
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).

Template Parameters
SpaceThe color space the colors are blended in; void, the default, follows Color
ColorThe color type of the inputs and the result
Parameters
[in]fromThe color at amount 0
[in]toThe color at amount 1
[in]amountFraction of the way from from to to, clamped to the 0-1 range: 0 gives from, 1 gives to
[in]spaceThe working space, e.g. in<SRGB>; the LinearSpaceOf Color when omitted
Returns
The blended color.

Definition at line 208 of file Operations.cppm.

◆ mix() [3/4]

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 = {} )
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.

Template Parameters
SpaceThe color space the colors would be blended in
FromColor type of from
ToColor type of to, other than From
Parameters
[in]fromThe color at amount 0
[in]toThe color at amount 1
[in]amountFraction of the way from from to to
[in]modeThe arc of the hue circle to follow
[in]spaceThe working space
Returns
Nothing: the function is deleted.

◆ mix() [4/4]

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 = {} )
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).

Template Parameters
SpaceThe color space the colors would be blended in
FromColor type of from
ToColor type of to, other than From
Parameters
[in]fromThe color at amount 0
[in]toThe color at amount 1
[in]amountFraction of the way from from to to
[in]spaceThe working space
Returns
Nothing: the function is deleted.

◆ rotate_hue()

template<HueSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::rotate_hue ( const Color & color,
const float degrees,
In< Space > 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.

Template Parameters
SpaceThe color space the hue is turned in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to rotate
[in]degreesThe angle to add to the hue, any finite value
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The rotated color.

Definition at line 516 of file Operations.cppm.

◆ saturate()

template<SaturationSpace Space = OKLCH, ColorType Color>
requires ConvertibleTo<Space, Color> && ConvertibleTo<Color, Space>
Color aest::colors::saturate ( const Color & color,
const float amount,
In< Space > space = {} )
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:

  • With a maximum, a BoundedSaturationSpace such as HSL, the saturation s moves a fraction of the way toward it: s + (MAX - s) * amount, with amount clamped to the 0-1 range, so 1 gives full saturation.
  • Without one, such as the chroma of OKLCH, it is scaled: s * (1 + amount), with 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.

Template Parameters
SpaceThe color space the saturation is adjusted in
ColorThe color type of the input and the result
Parameters
[in]colorThe color to saturate
[in]amountHow much to raise the saturation, as above; negative values keep the color
[in]spaceThe working space, e.g. in<HSL>; OKLCH when omitted
Returns
The saturated color.

Definition at line 416 of file Operations.cppm.

Variable Documentation

◆ ACHROMATIC_CHROMA

float aest::colors::ACHROMATIC_CHROMA = 1e-4f
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.

◆ CONTRAST_FLARE

float aest::colors::CONTRAST_FLARE = 0.05f
constexpr

Viewing flare WCAG adds to both luminances of a contrast ratio.

Definition at line 25 of file Operations.cppm.