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

Partition aest.colors:packed: GPU pixel formats, packed and unpacked with the bit layouts of Vulkan and Direct3D. More...

#include <algorithm>
#include <array>
#include <bit>
#include <concepts>
#include <cstdint>
#include <limits>
import aest.colors:gamut;

Go to the source code of this file.

Concepts

concept  aest::colors::PackableRGB
 A color whose channels are red, green and blue: any RGB space, or the premultiplied form of a linear one.
concept  aest::colors::PackableLinearRGB
 A color whose channels are linear red, green and blue: a linear RGB space, or its premultiplied form.

Functions

constexpr float aest::colors::power_of_two (const std::int32_t exponent)
 A float with value 2 raised to exponent.
template<std::int32_t Mantissa>
constexpr std::uint32_t aest::colors::encode_float5 (const float value)
 Encodes a non-negative float into an unsigned float with a 5-bit exponent (bias 15) and Mantissa bits, rounding to nearest even.
template<std::int32_t Mantissa>
constexpr float aest::colors::decode_float5 (const std::uint32_t bits)
 Decodes an unsigned float with a 5-bit exponent (bias 15) and Mantissa bits.
template<std::int32_t Mantissa>
constexpr float aest::colors::clamp_float5 (const float value)
 Clamps a channel to the finite range of an unsigned float format.
constexpr std::uint32_t aest::colors::to_unorm (const float value, const std::uint32_t max)
 Quantizes a value in the 0-1 range to an unsigned normalized integer.
constexpr float aest::colors::from_unorm (const std::uint32_t value, const std::uint32_t max)
 Converts an unsigned normalized integer back to the 0-1 range.
constexpr std::uint16_t aest::colors::to_half (const float value)
 Converts a float to an IEEE 754 half, rounding to nearest even.
constexpr float aest::colors::from_half (const std::uint16_t half)
 Converts an IEEE 754 half to a float, exactly.
template<PackableRGB Color>
constexpr std::array< std::uint8_t, 4 > aest::colors::pack_rgba8 (const Color &color)
 Packs a color into RGBA8 unorm bytes, in memory order, as R8G8B8A8_UNORM and R8G8B8A8_SRGB store them.
template<PackableRGB Color>
constexpr Color aest::colors::unpack_rgba8 (const std::array< std::uint8_t, 4 > &bytes)
 Unpacks RGBA8 unorm bytes, in memory order, into a color.
template<PackableRGB Color>
constexpr std::uint32_t aest::colors::pack_rgb10a2 (const Color &color)
 Packs a color into A2B10G10R10_UNORM_PACK32: red in bits 0-9, green in 10-19, blue in 20-29 and alpha in 30-31.
template<PackableRGB Color>
constexpr Color aest::colors::unpack_rgb10a2 (const std::uint32_t bits)
 Unpacks an A2B10G10R10_UNORM_PACK32 word into a color.
template<PackableLinearRGB Color>
constexpr std::array< std::uint16_t, 4 > aest::colors::pack_rgba16f (const Color &color)
 Packs a linear color into RGBA16F halves, in memory order, as R16G16B16A16_SFLOAT stores them.
template<PackableLinearRGB Color>
constexpr Color aest::colors::unpack_rgba16f (const std::array< std::uint16_t, 4 > &halves)
 Unpacks RGBA16F halves, in memory order, into a linear color.
template<PackableLinearRGB Color>
constexpr std::uint32_t aest::colors::pack_r11g11b10f (const Color &color)
 Packs a linear color into B10G11R11_UFLOAT_PACK32: red in bits 0-10 and green in 11-21 as 11-bit floats, blue in 22-31 as a 10-bit float, alpha dropped.
template<PackableLinearRGB Color>
constexpr Color aest::colors::unpack_r11g11b10f (const std::uint32_t bits)
 Unpacks a B10G11R11_UFLOAT_PACK32 word into a linear color.
template<PackableLinearRGB Color>
constexpr std::uint32_t aest::colors::pack_rgb9e5 (const Color &color)
 Packs a linear color into E5B9G9R9_UFLOAT_PACK32: 9-bit mantissas of red, green and blue in bits 0-8, 9-17 and 18-26, sharing the 5-bit exponent in bits 27-31; alpha dropped.
template<PackableLinearRGB Color>
constexpr Color aest::colors::unpack_rgb9e5 (const std::uint32_t bits)
 Unpacks an E5B9G9R9_UFLOAT_PACK32 word into a linear color.

Variables

constexpr std::int32_t aest::colors::FLOAT5_BIAS = 15
 Exponent bias of the 5-bit exponent shared by half, 11-bit and 10-bit floats.
constexpr std::int32_t aest::colors::FLOAT5_MAX_EXPONENT = 30
 Largest biased exponent of a finite 5-bit-exponent float.
constexpr std::int32_t aest::colors::FLOAT32_BIAS = 127
 Exponent bias of a 32-bit float.
constexpr std::int32_t aest::colors::FLOAT32_MANTISSA = 23
 Width of the mantissa of a 32-bit float.
template<std::int32_t Mantissa>
constexpr float aest::colors::FLOAT5_MAX
 Largest finite value of an unsigned float with a 5-bit exponent and Mantissa bits.
template<typename T>
constexpr bool aest::colors::IS_PREMULTIPLIED_RGB = false
 Whether a type is the premultiplied form of a linear RGB space.
template<LinearRGBSpace Space>
constexpr bool aest::colors::IS_PREMULTIPLIED_RGB< Premultiplied< Space > > = true
 The premultiplied form of a linear RGB space.
constexpr std::int32_t aest::colors::HALF_MANTISSA = 10
 Mantissa width of a half float.
constexpr std::int32_t aest::colors::FLOAT11_MANTISSA = 6
 Mantissa width of the red and green channels of B10G11R11.
constexpr std::int32_t aest::colors::FLOAT10_MANTISSA = 5
 Mantissa width of the blue channel of B10G11R11.
constexpr std::int32_t aest::colors::RGB9E5_MANTISSA = 9
 Mantissa width of each channel of E5B9G9R9.
constexpr float aest::colors::RGB9E5_MAX = 65408.f
 Largest value of a channel of E5B9G9R9: 511 / 512 * 2^16.

Detailed Description

Partition aest.colors:packed: GPU pixel formats, packed and unpacked with the bit layouts of Vulkan and Direct3D.

Author
Davide Pierotti
See also
Vulkan specification

Definition in file Packed.cppm.

Function Documentation

◆ clamp_float5()

template<std::int32_t Mantissa>
float aest::colors::clamp_float5 ( const float value)
constexpr

Clamps a channel to the finite range of an unsigned float format.

Template Parameters
MantissaThe mantissa width of the format
Parameters
[in]valueThe channel value
Returns
value clamped to [0, largest finite value].

Definition at line 128 of file Packed.cppm.

◆ decode_float5()

template<std::int32_t Mantissa>
float aest::colors::decode_float5 ( const std::uint32_t bits)
constexpr

Decodes an unsigned float with a 5-bit exponent (bias 15) and Mantissa bits.

Template Parameters
MantissaThe mantissa width: 10 for half, 6 or 5 for the packed formats
Parameters
[in]bitsThe bits, exponent above the mantissa
Returns
The value, exactly: subnormals, infinity and NaN included.

Definition at line 96 of file Packed.cppm.

◆ encode_float5()

template<std::int32_t Mantissa>
std::uint32_t aest::colors::encode_float5 ( const float value)
constexpr

Encodes a non-negative float into an unsigned float with a 5-bit exponent (bias 15) and Mantissa bits, rounding to nearest even.

Values too large for the format round to infinity; values too small become subnormals or 0.

Template Parameters
MantissaThe mantissa width: 10 for half, 6 or 5 for the packed formats
Parameters
[in]valueThe value, finite and 0 or greater
Returns
The bits, exponent above the mantissa.

Definition at line 59 of file Packed.cppm.

◆ from_half()

float aest::colors::from_half ( const std::uint16_t half)
constexprexport

Converts an IEEE 754 half to a float, exactly.

Parameters
[in]halfThe bits of the half
Returns
The value: subnormals, signed zeros, infinities and NaN included.
See also
IEEE 754-2019

Definition at line 234 of file Packed.cppm.

◆ from_unorm()

float aest::colors::from_unorm ( const std::uint32_t value,
const std::uint32_t max )
constexpr

Converts an unsigned normalized integer back to the 0-1 range.

Parameters
[in]valueThe integer
[in]maxThe largest integer, 2^bits - 1
Returns
value / max.

Definition at line 150 of file Packed.cppm.

◆ pack_r11g11b10f()

template<PackableLinearRGB Color>
std::uint32_t aest::colors::pack_r11g11b10f ( const Color & color)
constexprexport

Packs a linear color into B10G11R11_UFLOAT_PACK32: red in bits 0-10 and green in 11-21 as 11-bit floats, blue in 22-31 as a 10-bit float, alpha dropped.

The floats are unsigned with a 5-bit exponent, like half without the sign and with 6 or 5 mantissa bits: about 2 and 1.5 significant digits. Each channel is clamped to the largest finite value, 65024 for red and green, 64512 for blue, and rounded to nearest even.

Template Parameters
ColorA linear RGB space, or its premultiplied form
Parameters
[in]colorThe color to pack
Returns
The packed 32-bit word.
See also
Khronos Data Format Specification

Definition at line 357 of file Packed.cppm.

◆ pack_rgb10a2()

template<PackableRGB Color>
std::uint32_t aest::colors::pack_rgb10a2 ( const Color & color)
constexprexport

Packs a color into A2B10G10R10_UNORM_PACK32: red in bits 0-9, green in 10-19, blue in 20-29 and alpha in 30-31.

Each channel is clamped to [0, 1] and rounded to the nearest of 1024 levels, alpha to the nearest of 4. As with pack_rgba8(), the color's own encoding is stored.

Template Parameters
ColorAn RGB space, or premultiplied linear RGB
Parameters
[in]colorThe color to pack
Returns
The packed 32-bit word.

Definition at line 287 of file Packed.cppm.

◆ pack_rgb9e5()

template<PackableLinearRGB Color>
std::uint32_t aest::colors::pack_rgb9e5 ( const Color & color)
constexprexport

Packs a linear color into E5B9G9R9_UFLOAT_PACK32: 9-bit mantissas of red, green and blue in bits 0-8, 9-17 and 18-26, sharing the 5-bit exponent in bits 27-31; alpha dropped.

Follows the conversion of the Vulkan specification: channels are clamped to [0, 65408], the exponent is chosen for the largest channel, and each mantissa is rounded to nearest. The largest channel keeps 9 significant bits; a channel far dimmer than it keeps fewer, down to none.

Template Parameters
ColorA linear RGB space, or its premultiplied form
Parameters
[in]colorThe color to pack
Returns
The packed 32-bit word.
See also
Khronos Data Format Specification

Definition at line 395 of file Packed.cppm.

◆ pack_rgba16f()

template<PackableLinearRGB Color>
std::array< std::uint16_t, 4 > aest::colors::pack_rgba16f ( const Color & color)
constexprexport

Packs a linear color into RGBA16F halves, in memory order, as R16G16B16A16_SFLOAT stores them.

Channels are clamped to 65504, the largest finite half, so the result is never infinite, then rounded to nearest even.

Template Parameters
ColorA linear RGB space, or its premultiplied form
Parameters
[in]colorThe color to pack
Returns
The halves red, green, blue, alpha.
See also
IEEE 754-2019

Definition at line 319 of file Packed.cppm.

◆ pack_rgba8()

template<PackableRGB Color>
std::array< std::uint8_t, 4 > aest::colors::pack_rgba8 ( const Color & color)
constexprexport

Packs a color into RGBA8 unorm bytes, in memory order, as R8G8B8A8_UNORM and R8G8B8A8_SRGB store them.

Each channel is clamped to [0, 1] and rounded to the nearest of 256 levels. The color's own encoding is stored: pack SRGB for an _SRGB format, a linear space for _UNORM data such as masks.

Template Parameters
ColorAn RGB space, or premultiplied linear RGB
Parameters
[in]colorThe color to pack
Returns
The bytes red, green, blue, alpha.

Definition at line 253 of file Packed.cppm.

◆ power_of_two()

float aest::colors::power_of_two ( const std::int32_t exponent)
constexpr

A float with value 2 raised to exponent.

Parameters
[in]exponentThe power of 2, in the range of normal floats (-126 to 127)
Returns
2^exponent, exactly.

Definition at line 41 of file Packed.cppm.

◆ to_half()

std::uint16_t aest::colors::to_half ( const float value)
constexprexport

Converts a float to an IEEE 754 half, rounding to nearest even.

Values beyond 65504 round to infinity, infinities stay infinite with their sign, and NaN becomes the quiet NaN 0x7E00 with its sign.

Parameters
[in]valueThe float to convert
Returns
The bits of the half.
See also
IEEE 754-2019

Definition at line 213 of file Packed.cppm.

◆ to_unorm()

std::uint32_t aest::colors::to_unorm ( const float value,
const std::uint32_t max )
constexpr

Quantizes a value in the 0-1 range to an unsigned normalized integer.

Parameters
[in]valueThe value, clamped to the 0-1 range
[in]maxThe largest integer, 2^bits - 1
Returns
The nearest integer to value * max.

Definition at line 139 of file Packed.cppm.

◆ unpack_r11g11b10f()

template<PackableLinearRGB Color>
Color aest::colors::unpack_r11g11b10f ( const std::uint32_t bits)
constexprexport

Unpacks a B10G11R11_UFLOAT_PACK32 word into a linear color.

Template Parameters
ColorThe color type the word is in
Parameters
[in]bitsThe packed word
Returns
The color, opaque.
See also
Khronos Data Format Specification

Definition at line 372 of file Packed.cppm.

◆ unpack_rgb10a2()

template<PackableRGB Color>
Color aest::colors::unpack_rgb10a2 ( const std::uint32_t bits)
constexprexport

Unpacks an A2B10G10R10_UNORM_PACK32 word into a color.

Template Parameters
ColorThe color type the word is in
Parameters
[in]bitsThe packed word
Returns
The color, each channel value / 1023 and alpha value / 3.

Definition at line 300 of file Packed.cppm.

◆ unpack_rgb9e5()

template<PackableLinearRGB Color>
Color aest::colors::unpack_rgb9e5 ( const std::uint32_t bits)
constexprexport

Unpacks an E5B9G9R9_UFLOAT_PACK32 word into a linear color.

Template Parameters
ColorThe color type the word is in
Parameters
[in]bitsThe packed word
Returns
The color, opaque.
See also
Khronos Data Format Specification

Definition at line 428 of file Packed.cppm.

◆ unpack_rgba16f()

template<PackableLinearRGB Color>
Color aest::colors::unpack_rgba16f ( const std::array< std::uint16_t, 4 > & halves)
constexprexport

Unpacks RGBA16F halves, in memory order, into a linear color.

Template Parameters
ColorThe color type the halves are in
Parameters
[in]halvesThe halves red, green, blue, alpha
Returns
The color.
See also
IEEE 754-2019

Definition at line 335 of file Packed.cppm.

◆ unpack_rgba8()

template<PackableRGB Color>
Color aest::colors::unpack_rgba8 ( const std::array< std::uint8_t, 4 > & bytes)
constexprexport

Unpacks RGBA8 unorm bytes, in memory order, into a color.

Template Parameters
ColorThe color type the bytes are in
Parameters
[in]bytesThe bytes red, green, blue, alpha
Returns
The color, each channel byte / 255.

Definition at line 268 of file Packed.cppm.

Variable Documentation

◆ FLOAT10_MANTISSA

std::int32_t aest::colors::FLOAT10_MANTISSA = 5
constexpr

Mantissa width of the blue channel of B10G11R11.

Definition at line 176 of file Packed.cppm.

◆ FLOAT11_MANTISSA

std::int32_t aest::colors::FLOAT11_MANTISSA = 6
constexpr

Mantissa width of the red and green channels of B10G11R11.

Definition at line 173 of file Packed.cppm.

◆ FLOAT32_BIAS

std::int32_t aest::colors::FLOAT32_BIAS = 127
constexpr

Exponent bias of a 32-bit float.

Definition at line 31 of file Packed.cppm.

◆ FLOAT32_MANTISSA

std::int32_t aest::colors::FLOAT32_MANTISSA = 23
constexpr

Width of the mantissa of a 32-bit float.

Definition at line 34 of file Packed.cppm.

◆ FLOAT5_BIAS

std::int32_t aest::colors::FLOAT5_BIAS = 15
constexpr

Exponent bias of the 5-bit exponent shared by half, 11-bit and 10-bit floats.

Definition at line 25 of file Packed.cppm.

◆ FLOAT5_MAX

template<std::int32_t Mantissa>
float aest::colors::FLOAT5_MAX
constexpr
Initial value:
static_cast<std::uint32_t>(FLOAT5_MAX_EXPONENT) << Mantissa | ((1u << Mantissa) - 1))
constexpr std::int32_t FLOAT5_MAX_EXPONENT
Largest biased exponent of a finite 5-bit-exponent float.
Definition Packed.cppm:28
constexpr float decode_float5(const std::uint32_t bits)
Decodes an unsigned float with a 5-bit exponent (bias 15) and Mantissa bits.
Definition Packed.cppm:96

Largest finite value of an unsigned float with a 5-bit exponent and Mantissa bits.

Template Parameters
MantissaThe mantissa width

Definition at line 118 of file Packed.cppm.

◆ FLOAT5_MAX_EXPONENT

std::int32_t aest::colors::FLOAT5_MAX_EXPONENT = 30
constexpr

Largest biased exponent of a finite 5-bit-exponent float.

Definition at line 28 of file Packed.cppm.

◆ HALF_MANTISSA

std::int32_t aest::colors::HALF_MANTISSA = 10
constexpr

Mantissa width of a half float.

Definition at line 170 of file Packed.cppm.

◆ IS_PREMULTIPLIED_RGB

template<typename T>
bool aest::colors::IS_PREMULTIPLIED_RGB = false
constexpr

Whether a type is the premultiplied form of a linear RGB space.

Template Parameters
TThe type to check

Definition at line 160 of file Packed.cppm.

◆ IS_PREMULTIPLIED_RGB< Premultiplied< Space > >

template<LinearRGBSpace Space>
bool aest::colors::IS_PREMULTIPLIED_RGB< Premultiplied< Space > > = true
constexpr

The premultiplied form of a linear RGB space.

Template Parameters
SpaceThe linear RGB space

Definition at line 167 of file Packed.cppm.

◆ RGB9E5_MANTISSA

std::int32_t aest::colors::RGB9E5_MANTISSA = 9
constexpr

Mantissa width of each channel of E5B9G9R9.

Definition at line 179 of file Packed.cppm.

◆ RGB9E5_MAX

float aest::colors::RGB9E5_MAX = 65408.f
constexpr

Largest value of a channel of E5B9G9R9: 511 / 512 * 2^16.

Definition at line 182 of file Packed.cppm.