Table of Contents

Class TransferFunction

Namespace
Egami.Colors
Assembly
Egami.dll

How a color space encodes light: the curve from stored values to linear light and back. Single values use exact double arithmetic; rows of floats use a vectorized form within 1e-5 of it (PQ rows use the double form), the same on every CPU with or without SIMD.

public sealed class TransferFunction : IEquatable<TransferFunction>
Inheritance
TransferFunction
Implements
Inherited Members

Examples

// A transfer function decodes stored values to linear light and back; HDR curves put reference white at 1.0.
double linear = TransferFunction.Srgb.ToLinear(0.5);           // 0.214
double nits = TransferFunction.Pq.ToLinear(0.75) * 203;         // a 75% PQ signal is about 983 cd/m²
float[] row = [0f, 0.25f, 0.5f, 1f];
TransferFunction.Srgb.ToLinear(row, row);                        // a whole row at once, in place

Remarks

Linear 1.0 is the encoding's reference white. For PQ and HLG that is 203 cd/m² (ITU-R BT.2408), so HDR highlights are values above 1. PQ covers 0 to 10,000 cd/m², about 0 to 49.3. HLG decodes for a 1,000 cd/m² display with system gamma 1.2, which puts its reference white (a 75% signal) at 1.0; single values and rows apply its OOTF to each value as for a gray color, and the full OOTF, which depends on the color's luminance, is applied by color conversion.

The SDR curves are extended to negative values by mirroring (f(−x) = −f(x)), as CSS Color 4 does, and to values above 1 by their own formula. PQ and HLG treat negative values as 0.

Properties

Hlg

Gets the hybrid log-gamma curve of ITU-R BT.2100, for a 1,000 cd/m² display, scaled so reference white is 1.0.

public static TransferFunction Hlg { get; }

Property Value

TransferFunction

IsHdr

Gets a value indicating whether this is an HDR curve (PQ or HLG), whose linear values go above 1.

public bool IsHdr { get; }

Property Value

bool

IsLinear

Gets a value indicating whether the curve is the identity.

public bool IsLinear { get; }

Property Value

bool

Linear

Gets the identity: values are linear light already.

public static TransferFunction Linear { get; }

Property Value

TransferFunction

Pq

Gets the SMPTE ST 2084 perceptual quantizer of ITU-R BT.2100, scaled so 203 cd/m² is 1.0.

public static TransferFunction Pq { get; }

Property Value

TransferFunction

Rec709

Gets the ITU-R BT.709 and BT.2020 curve (the inverse of their camera OETF).

public static TransferFunction Rec709 { get; }

Property Value

TransferFunction

Srgb

Gets the sRGB curve of IEC 61966-2-1: a linear segment below 0.04045, then a 2.4 power.

public static TransferFunction Srgb { get; }

Property Value

TransferFunction

Methods

Equals(TransferFunction?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(TransferFunction? other)

Parameters

other TransferFunction

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

FromLinear(double)

Encodes one linear value.

public double FromLinear(double linear)

Parameters

linear double

The linear value.

Returns

double

The stored value.

FromLinear(ReadOnlySpan<float>, Span<float>)

Encodes a row of linear values; destination may be source.

public void FromLinear(ReadOnlySpan<float> source, Span<float> destination)

Parameters

source ReadOnlySpan<float>

The linear values.

destination Span<float>

Where to write the stored values. It must be at least as long as source.

Exceptions

ArgumentException

destination is shorter than source.

Gamma(double)

Returns a pure power curve: linear = encoded^gamma (2.2 for a typical display).

public static TransferFunction Gamma(double gamma)

Parameters

gamma double

The decoding exponent, above 0.

Returns

TransferFunction

The curve.

Exceptions

ArgumentOutOfRangeException

gamma is not a positive finite number.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

IsCloseTo(TransferFunction, double)

Returns whether two curves give the same linear values, within tolerance, at 256 points from 0 to 1: a parametric curve written for sRGB is close to Srgb, for example.

public bool IsCloseTo(TransferFunction other, double tolerance = 0.0001)

Parameters

other TransferFunction

The other curve.

tolerance double

The largest difference allowed.

Returns

bool

true if the curves agree.

Parametric(double, double, double, double, double, double, double)

Returns the ICC parametric curve: linear = (a·x + b)^g + e for x ≥ d, and c·x + f below d. Every ICC para curve and the sRGB, BT.709 and gamma curves are special cases.

public static TransferFunction Parametric(double g, double a, double b, double c, double d, double e, double f)

Parameters

g double

The exponent, above 0.

a double

The scale inside the power.

b double

The offset inside the power.

c double

The slope of the linear segment.

d double

Where the power segment starts.

e double

The offset added to the power segment.

f double

The offset of the linear segment.

Returns

TransferFunction

The curve.

Exceptions

ArgumentOutOfRangeException

A value is not finite, or g is not above 0.

Table(ReadOnlySpan<float>)

Returns a sampled curve: linear[i] is the linear value of encoded value i / (count − 1), and values in between are interpolated, as an ICC curv table is.

public static TransferFunction Table(ReadOnlySpan<float> linear)

Parameters

linear ReadOnlySpan<float>

At least two samples, not decreasing.

Returns

TransferFunction

The curve.

Exceptions

ArgumentException

Fewer than two samples, a sample that is not finite, or samples that go down.

ToLinear(double)

Decodes one value to linear light.

public double ToLinear(double encoded)

Parameters

encoded double

The stored value, nominally 0 to 1.

Returns

double

The linear value.

ToLinear(ReadOnlySpan<float>, Span<float>)

Decodes a row of values to linear light; destination may be source.

public void ToLinear(ReadOnlySpan<float> source, Span<float> destination)

Parameters

source ReadOnlySpan<float>

The stored values.

destination Span<float>

Where to write the linear values. It must be at least as long as source.

Exceptions

ArgumentException

destination is shorter than source.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

Edit this page