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	semantic_color.hpp
	defines the semantic_color type.

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...

Enumerations
enum class	hi::v1::semantic_color : unsigned char { blue , green , indigo , orange , pink , purple , red , teal , yellow , gray , gray2 , gray3 , gray4 , gray5 , gray6 , foreground , border , fill , accent , text_select , primary_cursor , secondary_cursor }
	Semantic colors. 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.

std::string_view	hi::v1::to_string (semantic_color rhs) noexcept
	Convert a semantic color to a string.

semantic_color	hi::v1::semantic_color_from_string (std::string_view str)
	Convert a string to a semantic color.

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.

Enumeration Type Documentation

◆ semantic_color

enum class hi::v1::semantic_color : unsigned char

strong

Semantic colors.

Function Documentation

◆ color_from_sRGB() [1/2]

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

inlinenoexcept

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 )

inlinenoexcept

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()

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

constexprnoexcept

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 )

inlinenoexcept

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 )

inlinenoexcept

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.

◆ semantic_color_from_string()

semantic_color hi::v1::semantic_color_from_string ( std::string_view str )

inline

Convert a string to a semantic color.

◆ sRGB_gamma8_to_linear16()

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

inlinenoexcept

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 )

inlinenoexcept

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 )

inlinenoexcept

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 )

inlinenoexcept

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.

◆ to_string()

std::string_view hi::v1::to_string ( semantic_color rhs )

inlinenoexcept

Convert a semantic color to a string.

Variable Documentation

◆ Rec2020_to_XYZ

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)

constexpr

Rec.2020 to XYZ color space conversion matrix.

◆ Rec2100_to_XYZ

constexpr matrix3 hi::v1::Rec2100_to_XYZ = Rec2020_to_XYZ

constexpr

Rec.2100 to XYZ color space conversion matrix.

◆ sRGB_to_XYZ

constexpr 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

constexpr matrix3 hi::v1::XYZ_to_Rec2020 = ~Rec2020_to_XYZ

constexpr

XYZ to Rec.2020 color space conversion matrix.

◆ XYZ_to_Rec2100

constexpr matrix3 hi::v1::XYZ_to_Rec2100 = XYZ_to_Rec2020

constexpr

XYZ to Rec.2100 color space conversion matrix.

◆ XYZ_to_sRGB

constexpr 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.

Files

Data Structures

Enumerations

Functions

Variables

Detailed Description

Usage of color spaces

PNG decoding

Theme files

Swap chain

scRGB color space

The color types

color

matrix3

Enumeration Type Documentation

◆ semantic_color

Function Documentation

◆ color_from_sRGB() [1/2]

◆ color_from_sRGB() [2/2]

◆ color_primaries_to_RGBtoXYZ()

◆ Rec2100_gamma_to_linear()

◆ Rec2100_linear_to_gamma()

◆ semantic_color_from_string()

◆ sRGB_gamma8_to_linear16()

◆ sRGB_gamma_to_linear()

◆ sRGB_linear16_to_gamma8()

◆ sRGB_linear_to_gamma()

◆ to_string()

Variable Documentation

◆ Rec2020_to_XYZ

◆ Rec2100_to_XYZ

◆ sRGB_to_XYZ

◆ XYZ_to_Rec2020

◆ XYZ_to_Rec2100

◆ XYZ_to_sRGB