r.HDR.Display.ColorGamut

r.HDR.Display.ColorGamut

#Overview

name: r.HDR.Display.ColorGamut

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.Display.ColorGamut is to define the color gamut of the output display in Unreal Engine’s rendering system. This setting is crucial for ensuring accurate color reproduction in High Dynamic Range (HDR) rendering scenarios.

This setting variable is primarily used in the rendering subsystem of Unreal Engine, specifically in the RenderCore and D3D12RHI modules. It’s particularly important for HDR rendering and display output configuration.

The value of this variable is set through a console variable (CVarDisplayColorGamut) in the RenderCore.cpp file. It can be changed at runtime and is not set via ini files.

The variable interacts closely with other HDR-related settings, particularly r.HDR.Display.OutputDevice. Together, they determine the format and color space of the rendered output.

Developers must be aware that:

  1. The setting affects the entire rendering pipeline’s color output.
  2. It’s crucial for maintaining color accuracy, especially in HDR workflows.
  3. The setting should match the capabilities of the target display device.

Best practices when using this variable include:

  1. Ensuring it’s set to match the intended target display’s color gamut.
  2. Coordinating its value with other HDR settings for optimal results.
  3. Testing the visual output across different supported color gamuts to ensure consistency.

Regarding the associated variable CVarDisplayColorGamut:

The purpose of CVarDisplayColorGamut is to provide a runtime-configurable way to set and access the r.HDR.Display.ColorGamut value.

It’s used in the RenderCore module to retrieve and set the current color gamut setting. The HDRGetDefaultDisplayColorGamut function, for example, uses this variable to determine the current color gamut.

The value is typically set programmatically, often in response to device profiles or runtime configuration changes.

This variable interacts directly with the r.HDR.Display.ColorGamut setting, effectively serving as its internal representation.

Developers should be aware that:

  1. Changes to this variable will affect the entire rendering pipeline.
  2. It’s clamped to valid values within the EDisplayColorGamut enum range.

Best practices include:

  1. Using the provided functions like HDRGetDefaultDisplayColorGamut to access the value, rather than reading the CVarDisplayColorGamut directly.
  2. Coordinating changes to this variable with other HDR and display settings for consistent results.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

// Please update all paths if changing
TAutoConsoleVariable<int32> CVarDisplayColorGamut(
	TEXT("r.HDR.Display.ColorGamut"),
	0,
	TEXT("Color gamut of the output display:\n")
	TEXT("0: Rec709 / sRGB, D65 (default)\n")
	TEXT("1: DCI-P3, D65\n")
	TEXT("2: Rec2020 / BT2020, D65\n")
	TEXT("3: ACES, D60\n")

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/Windows/WindowsD3D12Device.cpp:1720

Scope (from outer to inner):

file
function     void FD3D12DynamicRHI::Init

Source code excerpt:

		// Possible values are:
		//	1) PF_FloatRGBA - FP16 format that allows for linear gamma. This is the current engine default.
		//					r.HDR.Display.ColorGamut = 0 (sRGB which is the same gamut as ScRGB)
		//					r.HDR.Display.OutputDevice = 5 or 6 (ScRGB)
		//	2) PF_A2B10G10R10 - Save memory vs FP16 as well as allow for possible performance improvements 
		//						in fullscreen by avoiding format conversions.
		//					r.HDR.Display.ColorGamut = 2 (Rec2020 / BT2020)
		//					r.HDR.Display.OutputDevice = 3 or 4 (ST-2084)
#if WITH_EDITOR
		GRHIHDRDisplayOutputFormat = PF_FloatRGBA;
#else
		GRHIHDRDisplayOutputFormat = PF_A2B10G10R10;
#endif

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// Note: These values are directly referenced in code. They are set in code at runtime and therefore cannot be set via ini files
// Please update all paths if changing
TAutoConsoleVariable<int32> CVarDisplayColorGamut(
	TEXT("r.HDR.Display.ColorGamut"),
	0,
	TEXT("Color gamut of the output display:\n")
	TEXT("0: Rec709 / sRGB, D65 (default)\n")
	TEXT("1: DCI-P3, D65\n")
	TEXT("2: Rec2020 / BT2020, D65\n")

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

Scope (from outer to inner):

file
function     EDisplayColorGamut HDRGetDefaultDisplayColorGamut

Source code excerpt:

RENDERCORE_API EDisplayColorGamut HDRGetDefaultDisplayColorGamut()
{
	return static_cast<EDisplayColorGamut>(FMath::Clamp(CVarDisplayColorGamut.GetValueOnAnyThread(), 0, static_cast<int32>(EDisplayColorGamut::MAX) - 1));
}

struct FHDRMetaData
{
	EDisplayOutputFormat DisplayOutputFormat;
	EDisplayColorGamut DisplayColorGamut;

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

Scope (from outer to inner):

file
function     void HDRConfigureCVars

Source code excerpt:


	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)