A mask lets each color through only one of its subpixels, so to keep the average brightness the lit subpixel has to carry two to four times the light. In standard dynamic range that clips at 1, which is why a strong mask looks dim there. On an HDR display the light above paper white is shown, so the mask can run at full strength. When the display's headroom is smaller than the lit subpixel needs, the picture is scaled down just enough to keep the brightest subpixel of paper white at the display's peak.

All methods are pure and safe with invalid input, so they can be tested without a display.

HDR mask mode is only active when the settings ask for it, the mask is not None, the render path can carry light above paper white, and the display's headroom reaches MIN_HDR_MASK_HEADROOM. See IsActive(bool, bool, CRTMaskType, bool, float).

Methods

Apply(TextModeCRTSettings, bool, bool, float)

Decides whether HDR mask mode takes over for a picture and, if it does, sets the mask of the resolved settings to full strength. The authored strength stays in the preset, where it is the fallback for standard displays.

Declaration

public static bool Apply(TextModeCRTSettings resolved, bool allowed, bool pathSupportsHDR, float headroom)

Parameters

Type	Name	Description
TextModeCRTSettings	resolved	The resolved settings, after the readability clamp.
bool	allowed	Whether the project and the user allow HDR mask mode.
bool	pathSupportsHDR	Whether light above paper white can reach the display on this path.
float	headroom	The display's headroom.

Returns

Type	Description
bool	True if HDR mask mode is active for this picture.

Headroom(in CRTHDRDisplay, float)

Returns the display's headroom, its peak luminance over paper white. A display that peaks at 1000 nits with a paper white of 200 nits has a headroom of 5.

Declaration

public static float Headroom(in CRTHDRDisplay display, float headroomOverride)

Parameters

Type	Name	Description
CRTHDRDisplay	display	What the display reports.
float	headroomOverride	A manual headroom that replaces the reported one, for HDR displays that report it wrongly, or 0 to use the display's. It never turns a standard display into an HDR one.

Returns

Type	Description
float	The headroom, clamped to MAX_HDR_HEADROOM, or 1 when the display shows no HDR.

IsActive(bool, bool, CRTMaskType, bool, float)

Returns whether HDR mask mode takes over for a picture.

Declaration

public static bool IsActive(bool requested, bool allowed, CRTMaskType maskType, bool pathSupportsHDR, float headroom)

Parameters

Type	Name	Description
bool	requested	Whether the settings ask for it, from HDRMask.
bool	allowed	Whether the project and the user allow it.
CRTMaskType	maskType	The mask pattern; without a mask there is nothing to do.
bool	pathSupportsHDR	Whether light above paper white can reach the display on this path.
float	headroom	The display's headroom, from Headroom(in CRTHDRDisplay, float).

Returns

Type	Description
bool	True if the mask runs at full strength with its brightness recovered.

MaskPeakGain(CRTMaskType, int, float, int)

Returns how much light the lit subpixel of paper white carries with the mask at full strength, relative to paper white.

Declaration

public static float MaskPeakGain(CRTMaskType maskType, int period, float slotGap, int slotHeight)

Parameters

Type	Name	Description
CRTMaskType	maskType	The mask pattern.
int	period	The mask period in output pixels.
float	slotGap	Darkening of the row between slots, slot mask only.
int	slotHeight	Rows per slot, slot mask only.

Returns

Type	Description
float	The peak gain, 1 without a mask.

MaskScale(float, float, float)

Returns the factor the whole tube is scaled by in HDR mask mode: 1 when the headroom covers the mask's peak, less when it does not, times the user's brightness calibration. Invalid input is replaced: NaN headroom and peak gain count as 1, and the brightness is clamped to its configured range, or set to its default when NaN.

Declaration

public static float MaskScale(float headroom, float peakGain, float brightness)

Parameters

Type	Name	Description
float	headroom	The display's headroom, from Headroom(in CRTHDRDisplay, float).
float	peakGain	The mask's peak gain, from MaskPeakGain(CRTMaskType, int, float, int).
float	brightness	The user's brightness calibration, 1 to leave the result as it is.

Returns

Type	Description
float	The scale, always greater than 0.