Color

Files
file	color.hpp
	Defined the color type.
file	color_space.hpp
	Functions to create color conversion matrices.
file	quad_color.hpp
	Defined the quad_color type.
file	Rec2020.hpp
	color space conversion matrices between XYZ and Rec.2020
file	Rec2100.hpp
	color space conversion matrices between XYZ and Rec.2100
file	sRGB.hpp
	Color matrix and transfer functions for the sRGB color space.

Data Structures
class	hi::v1::color
	This is a RGBA floating point color. More...
class	hi::v1::quad_color
	A color for each corner of a quad. More...

Functions
constexpr matrix3	hi::v1::color_primaries_to_RGBtoXYZ (float wx, float wy, float rx, float ry, float gx, float gy, float bx, float by) noexcept
	Create a color space conversion matrix.
float	hi::v1::Rec2100_linear_to_gamma (float L) noexcept
	Rec.2100 linear to gamma transfer function.
float	hi::v1::Rec2100_gamma_to_linear (float N) noexcept
	Rec.2100 gamma to linear transfer function.
float	hi::v1::sRGB_linear_to_gamma (float u) noexcept
	sRGB linear to gamma transfer function.
float	hi::v1::sRGB_gamma_to_linear (float u) noexcept
	sRGB gamma to linear transfer function.
uint8_t	hi::v1::sRGB_linear16_to_gamma8 (half u) noexcept
	sRGB linear float-16 to gamma transfer function.
half	hi::v1::sRGB_gamma8_to_linear16 (uint8_t u) noexcept
	sRGB gamma to linear float-16 transfer function.
color	hi::v1::color_from_sRGB (float r, float g, float b, float a) noexcept
	Convert gama corrected sRGB color to the linear color.
color	hi::v1::color_from_sRGB (uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept
	Convert gama corrected sRGB color to the linear color.

Variables
constexpr matrix3	hi::v1::Rec2020_to_XYZ = color_primaries_to_RGBtoXYZ(0.3127f, 0.3290f, 0.708f, 0.292f, 0.170f, 0.797f, 0.131f, 0.046f)
	Rec.2020 to XYZ color space conversion matrix.
constexpr matrix3	hi::v1::XYZ_to_Rec2020 = ~Rec2020_to_XYZ
	XYZ to Rec.2020 color space conversion matrix.
constexpr matrix3	hi::v1::Rec2100_to_XYZ = Rec2020_to_XYZ
	Rec.2100 to XYZ color space conversion matrix.
constexpr matrix3	hi::v1::XYZ_to_Rec2100 = XYZ_to_Rec2020
	XYZ to Rec.2100 color space conversion matrix.
constexpr matrix3	hi::v1::sRGB_to_XYZ
	Matrix to convert sRGB to XYZ.
constexpr matrix3	hi::v1::XYZ_to_sRGB
	Matrix to convert XYZ to sRGB.

Detailed Description

Color, color-spaces and transfer functions.

Usage of color spaces

Usage	Space	depth	alpha
draw API	scRGB	half	straight
vertices	scRGB	half	straight
images	scRGB	half	pre-multiplied
fragment shaders	scRGB	float32	pre-multiplied
frame buffers	scRGB	half	pre-multiplied
swap chain	sRGB*	uint8*	pre-multiplied

PNG decoding

HikoGUI's PNG decoder will create an image of half RGBA values in the scRGB color space. The RGB values in the resulting image are pre-multiplied by the alpha.

The PNG decoder will use the color space and transfer function information from the PNG data to do the conversion of pixel values into the scRGB color space.

sRGB color space and transfer function is implied if color space information is not available in the PNG data.

Theme files

The colors in hikogui's theme file may be edited by users, there are three different ways of specifying colors.

Format	Color space
'#' 6 or 8 hex digits	sRGB
3 or 4 integers	sRGB
3 or 4 floating point numbers	scRGB

Swap chain

The swap chain images are the ones that are presented to the desktop compositor.

On windows 10 this will be 8-bit sRGB. On Windows 10 float-16 scRGB is possible but when a single application request a scRGB swap chain the whole desktop will switch to HDR/high gamut mode. This mode switch will also cause the graphics card and monitor to switch to this mode and likely they have different calibrations associated with it; very likely the user has never calibrated this and the experience will be extremely jarring. For this reason on Windows 10 HikoGUI will not by default request a float-16 scRGB swap chain.

On MacOS the swap chain will be in scRGB half. Since the desktop is always running HDR/high gamut mode, there is no switching effect like on Windows 10.

scRGB color space

scRGB is a HDR / high gamut color space. It is normally specified as 16 bit biased scaled integers with a range between -0.5 and 7.5 with a linear transfer function. But this color space is also often used with float 16; for GPU frame buffers and swap chains.

The scRGB color space has the same color primaries and white-point as the sRGB/BT.709 color spaces.

	x	y	Luminosity contribution
Red	0.6400	0.3300	0.2126
Green	0.3000	0.6000	0.7152
Blue	0.1500	0.0600	0.0722
White D65	0.3127	0.3290

The scRGB values have a linearly transfer function where scRGB(0.0, 0.0, 0.0) is black and scRGB(1.0, 1.0, 1.0) is white with a luminance of 80 cd/m2. When all scRGB component values are within 0.0 and 1.0 the scRGB color space is identical to linear sRGB.

Color component values above 1.0 will produce higher luminance values available on HDR monitors.

Negative color component values will allow colors outside of the sRGB gamut triangle, which may be rendered on high gamut monitors. However the luminosity of the color must be greater or equal to zero.

The color types

color

The color type is a float-16 3D RGB vector + alpha scalar.

The RGB values are linear and may comprise the complete floating point range, including values above 1.0 and value below zero.

The alpha value is a linear value between 0.0 (transparent) and 1.0 (opaque).

Depending on where the colors are used the RGB values are pre-multiplied by the alpha value, for example: inside fragment shaders, images and frame buffers.

matrix3

A color conversion matrix can be stored in the matrix3 type. A color value can be transformed by a matrix3.

The transformation ignores and preserves the alpha value.

Function Documentation

color_from_sRGB() [1/2]

color hi::v1::color_from_sRGB ( float r, float g, float b, float a )

inlinenodiscardnoexcept

Convert gama corrected sRGB color to the linear color.

Parameters

r	The sRGB gamma corrected color value, between 0.0 and 1.0.
g	The sRGB gamma corrected color value, between 0.0 and 1.0.
b	The sRGB gamma corrected color value, between 0.0 and 1.0.
a	Alpha value, between 0.0 and 1.0. not-premultiplied

Returns

A linear color.

color_from_sRGB() [2/2]

color hi::v1::color_from_sRGB ( uint8_t r, uint8_t g, uint8_t b, uint8_t a )

inlinenodiscardnoexcept

Convert gama corrected sRGB color to the linear color.

Parameters

r	The sRGB gamma corrected color value, between 0 and 255.
g	The sRGB gamma corrected color value, between 0 and 255.
b	The sRGB gamma corrected color value, between 0 and 255.
a	Alpha value, between 0 and 255. not-premultiplied

Returns

A linear color.

color_primaries_to_RGBtoXYZ()

matrix3 hi::v1::color_primaries_to_RGBtoXYZ ( float wx, float wy, float rx, float ry, float gx, float gy, float bx, float by )

nodiscardconstexprnoexcept

Create a color space conversion matrix.

Coordinates for color primaries and white-point are in the CIE xy chromaticity coordinate system.

Parameters

wx	x-coord for the white point.
wy	y-coord for the white point.
rx	x-coord for the red primary.
ry	y-coord for the red primary.
gx	x-coord for the green primary.
gy	y-coord for the green primary.
bx	x-coord for the blue primary.
by	y-coord for the blue primary.

Rec2100_gamma_to_linear()

float hi::v1::Rec2100_gamma_to_linear ( float N )

inlinenodiscardnoexcept

Rec.2100 gamma to linear transfer function.

Parameters

N	The Rec.2100 gamma corrected color value, between 0.0 and 1.0.

Returns

The color value converted to a linear color value between 0.0 and 1.0.

Rec2100_linear_to_gamma()

float hi::v1::Rec2100_linear_to_gamma ( float L )

inlinenodiscardnoexcept

Rec.2100 linear to gamma transfer function.

Parameters

L	The linear color value, between 0.0 and 1.0.

Returns

The color value converted to the Rec.2100 gamma corrected value between 0.0 and 1.0.

sRGB_gamma8_to_linear16()

half hi::v1::sRGB_gamma8_to_linear16 ( uint8_t u )

inlinenodiscardnoexcept

sRGB gamma to linear float-16 transfer function.

This function uses a lookup table for quick conversion.

Parameters

u	The sRGB gamma corrected color value, between 0.0 and 1.0.

Returns

The color value converted to a linear color value between 0.0 and 1.0.

sRGB_gamma_to_linear()

float hi::v1::sRGB_gamma_to_linear ( float u )

inlinenodiscardnoexcept

sRGB gamma to linear transfer function.

Parameters

u	The sRGB gamma corrected color value, between 0.0 and 1.0.

Returns

The color value converted to a linear color value between 0.0 and 1.0.

sRGB_linear16_to_gamma8()

uint8_t hi::v1::sRGB_linear16_to_gamma8 ( half u )

inlinenodiscardnoexcept

sRGB linear float-16 to gamma transfer function.

This function uses a lookup table for quick conversion.

Parameters

u	The linear color value, between 0.0 and 1.0.

Returns

The color value converted to the sRGB gamma corrected value between 0.0 and 1.0.

sRGB_linear_to_gamma()

float hi::v1::sRGB_linear_to_gamma ( float u )

inlinenodiscardnoexcept

sRGB linear to gamma transfer function.

Parameters

u	The linear color value, between 0.0 and 1.0.

Returns

The color value converted to the sRGB gamma corrected value between 0.0 and 1.0.

Variable Documentation

Rec2020_to_XYZ

matrix3 hi::v1::Rec2020_to_XYZ = color_primaries_to_RGBtoXYZ(0.3127f, 0.3290f, 0.708f, 0.292f, 0.170f, 0.797f, 0.131f, 0.046f)

constexpr

Rec.2020 to XYZ color space conversion matrix.

Rec2100_to_XYZ

matrix3 hi::v1::Rec2100_to_XYZ = Rec2020_to_XYZ

constexpr

Rec.2100 to XYZ color space conversion matrix.

sRGB_to_XYZ

matrix3 hi::v1::sRGB_to_XYZ

constexpr

Initial value:

                          =
matrix3{0.41239080f, 0.35758434f, 0.18048079f, 0.21263901f, 0.71516868f, 0.07219232f, 0.01933082f, 0.11919478f, 0.95053215f}

Matrix to convert sRGB to XYZ.

XYZ_to_Rec2020

matrix3 hi::v1::XYZ_to_Rec2020 = ~Rec2020_to_XYZ

constexpr

XYZ to Rec.2020 color space conversion matrix.

XYZ_to_Rec2100

matrix3 hi::v1::XYZ_to_Rec2100 = XYZ_to_Rec2020

constexpr

XYZ to Rec.2100 color space conversion matrix.

XYZ_to_sRGB

matrix3 hi::v1::XYZ_to_sRGB

constexpr

Initial value:

                          = matrix3{
3.24096994f,
-1.53738318f,
-0.49861076f,
-0.96924364f,
1.87596750f,
0.04155506f,
0.05563008f,
-0.20397696f,
1.05697151f}

Matrix to convert XYZ to sRGB.