Crate srgb

The crate provides primitives for manipulating colours in sRGB colour space.

Specifically, it provides functions for converting between sRGB space, linear sRGB space and XYZ colour space; as well as exposes the definition of D65 reference white point as well as XYZ colour conversion matrices; and in addition provides functions for handling Rec.709 components encoding.

The crate intents to provide low-level primitives needed to work with sRGB colour space. Those primitives can be used by other libraries which need to convert between sRGB and other colour spaces (if the conversion requires going through XYZ colour space) or blend colours together (which requires performing gamma correction).

Functions provided in the main module implement conversions between sRGB and XYZ colour spaces while providing routines for intermediate conversions. Functions in gamma submodule provide functions for doing gamma compression and expansion; they operate on a single colour component. Lastly, xyz submodule provides functions for converting between linear sRGB and XYZ colour spaces as well as constants exposing the matrices used by those functions.

Features

The crate defines two optional features:

no-fma

When enabled, the code will not use f32::mul_add. This may affect performance and precision of the code, however not using it results in more reproducible and well-defined floating point arithmetic.

That is, while fused multiply-add improves precision of the calculation, it does that by not adhering to strict rules of floating point maths. According to them, an a * b + c expression should result in rounding after multiplication and then after addition. Because the two operations are fused the middle rounding doesn’t happen. Unless you care about such rules, you probably don’t want this feature enabled.

Note that even if this feature is not enabled, that does not mean fused multiply-add instruction will be used. Depending on processor the crate is built for, the code may choose a faster implementation of matrix multiplication which does not use fused multiply-add operation. To make that happen, enable prefer-fma.

prefer-fma

When enabled, the code will use a fused multiply-add operation whenever possible. This will disable some potential performance optimisations which use SIMD instructions in favour of using fused multiply-add operation. See notes about no-fma above for discussion of how FMA impacts precision of the calculations.

Note that no-fma and prefer-fma are mutually exclusive

Modules

gamma	Functions implementing sRGB gamma compression and expansion formulæ.
rec709	Functions for normalising component values given in Rec.709 coding.
xyz	Functions and constant handling and related to conversion between linear sRGB space and CIE XYZ colour space.

Functions

normalised_from_xyz	Converts a colour in an XYZ colour space into a normalised sRGB representation.
u8_from_xyz	Converts a colour in an XYZ colour space into 24-bit sRGB representation.
xyz_from_normalised	Converts a normalised representation of a sRGB colour into XYZ colour space.
xyz_from_u8	Converts a 24-bit sRGB colour into XYZ colour space.