r.HDR.Display.MaxLuminance

r.HDR.Display.MaxLuminance

#Overview

name: r.HDR.Display.MaxLuminance

This variable is created as a Console Variable (cvar).

• type: Var
• help: The configured display output nit level, assuming HDR output is enabled.

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.Display.MaxLuminance is to specify the maximum luminance (brightness) level in nits for HDR (High Dynamic Range) displays. This setting is crucial for the rendering system, particularly for HDR output configuration.

This setting variable is primarily used in the RenderCore module of Unreal Engine, as evident from the callsites in the RenderCore.cpp file. It’s also referenced in the Engine module (UnrealEngine.cpp), indicating its importance in the core rendering pipeline.

The value of this variable is set through the HDRConfigureCVars function, which is part of the HDR configuration process. It’s set based on whether HDR is enabled and the specified display nits value.

This variable interacts closely with other HDR-related variables, such as r.HDR.Display.MinLuminanceLog10 and r.HDR.Display.MidLuminance, which together define the luminance range for HDR rendering.

Developers should be aware that this variable is critical for proper HDR rendering. Its value should accurately reflect the capabilities of the target display device to ensure correct HDR output.

Best practices when using this variable include:

1. Ensuring it’s set to an appropriate value based on the target display’s capabilities.
2. Coordinating its value with other HDR-related settings for a consistent HDR experience.
3. Testing HDR output on various display devices to ensure the setting works as expected across different hardware.

The associated variable CVarHDRDisplayMaxLuminance is an internal representation of r.HDR.Display.MaxLuminance. It’s used throughout the engine code to access the max luminance value. This variable is defined as a TAutoConsoleVariable, allowing it to be changed at runtime.

CVarHDRDisplayMaxLuminance is used in several key functions:

1. HDRGetDefaultMetaData: To set the maximum luminance in the HDR metadata.
2. HDRAddCustomMetaData: To add custom HDR metadata to windows.
3. HDRGetMetaData: To retrieve HDR metadata, including the maximum luminance.
4. HDRGetDisplayMaximumLuminance: A dedicated function to return the maximum luminance value.

Developers should note that CVarHDRDisplayMaxLuminance is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread. When working with this variable, ensure thread-safety by using the appropriate access methods, such as GetValueOnAnyThread().

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:393

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarHDRDisplayMaxLuminance(
	TEXT("r.HDR.Display.MaxLuminance"),
	0,
	TEXT("The configured display output nit level, assuming HDR output is enabled."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarHDRAcesColorMultiplier(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:949

Scope (from outer to inner):

file
function     void HDRSettingChangedSinkCallback

Source code excerpt:

	static const auto CVarHDRMinLuminanceLog10 = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MinLuminanceLog10"));
	static const auto CVarHDRMidLuminance = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Display.MidLuminance"));
	static const auto CVarHDRMaxLuminance = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.HDR.Display.MaxLuminance"));
	static const auto CVarHDRSceneColorMultiplier = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.SceneColorMultiplier"));
	static const auto CVarHDRGamutCompression = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.HDR.Aces.GamutCompression"));

	if (GRHIVendorId == 0)
	{
		return;

#Associated Variable and Callsites

This variable is associated with another variable named CVarHDRDisplayMaxLuminance. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:392

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHDRDisplayMaxLuminance(
	TEXT("r.HDR.Display.MaxLuminance"),
	0,
	TEXT("The configured display output nit level, assuming HDR output is enabled."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:467

Scope (from outer to inner):

file
function     inline FHDRMetaData HDRGetDefaultMetaData

Source code excerpt:

	HDRMetaData.DisplayColorGamut = HDRGetDefaultDisplayColorGamut();
	HDRMetaData.bHDRSupported = IsHDREnabled() && GRHISupportsHDROutput;
	HDRMetaData.MaximumLuminanceInNits = CVarHDRDisplayMaxLuminance.GetValueOnAnyThread();
	return HDRMetaData;
}

inline int32 WindowDisplayIntersectionArea(FIntRect WindowRect, FIntRect DisplayRect)
{
	return FMath::Max<int32>(0, FMath::Min<int32>(WindowRect.Max.X, DisplayRect.Max.X) - FMath::Max<int32>(WindowRect.Min.X, DisplayRect.Min.X)) *

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:491

Scope (from outer to inner):

file
function     void HDRAddCustomMetaData

Source code excerpt:

	HDRMetaData.DisplayColorGamut = DisplayColorGamut;
	HDRMetaData.bHDRSupported = bHDREnabled;
	HDRMetaData.MaximumLuminanceInNits = CVarHDRDisplayMaxLuminance.GetValueOnAnyThread();

	FScopeLock Lock(&GWindowsWithDefaultParamsCS);
	GWindowsWithDefaultParams.Add(OSWindow, HDRMetaData);
}

RENDERCORE_API void HDRRemoveCustomMetaData(void* OSWindow)

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:590

Scope (from outer to inner):

file
function     void HDRGetMetaData

Source code excerpt:

	if (OutbHDRSupported)
	{
		HDRGetDeviceAndColorGamut(GRHIVendorId, CVarHDRDisplayMaxLuminance.GetValueOnAnyThread(), OutDisplayOutputFormat, OutDisplayColorGamut);
	}

}

RENDERCORE_API float HDRGetDisplayMaximumLuminance()
{
	return CVarHDRDisplayMaxLuminance.GetValueOnAnyThread();
}

static FACESTonemapParams GACESTonemapParams;

RENDERCORE_API FACESTonemapParams HDRGetACESTonemapParams()
{

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderCore.cpp:627

Scope (from outer to inner):

file
function     RENDERCORE_API void HDRConfigureCVars

Source code excerpt:

	}

	//CVarHDRDisplayMaxLuminance is ECVF_SetByCode as it's only a mean of communicating the information from UGameUserSettings to the rest of the engine
	if (bIsHDREnabled)
	{
		CVarHDRDisplayMaxLuminance->Set((int32)DisplayNits, ECVF_SetByCode);
	}
	else
	{
		CVarHDRDisplayMaxLuminance->Set(0, ECVF_SetByCode);
	}

	CVarDisplayOutputDevice->Set((int32)OutputDevice, ECVF_SetByDeviceProfile);
	CVarDisplayColorGamut->Set((int32)ColorGamut, ECVF_SetByDeviceProfile);

	float HDRDisplayMinLuminance = FMath::Pow(10, CVarHDRDisplayMinLuminanceLog10.GetValueOnAnyThread());
	ConfigureACESTonemapParams(GACESTonemapParams, HDRDisplayMinLuminance, CVarHDRDisplayMidLuminance.GetValueOnAnyThread(), CVarHDRDisplayMaxLuminance.GetValueOnAnyThread());
}

RENDERCORE_API FMatrix44f GamutToXYZMatrix(EDisplayColorGamut ColorGamut)
{
	static const FMatrix44f sRGB_2_XYZ_MAT(
		FVector3f(0.4124564, 0.3575761, 0.1804375),