r.HDR.Aces.SceneColorMultiplier

r.HDR.Aces.SceneColorMultiplier

#Overview

name: r.HDR.Aces.SceneColorMultiplier

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

• type: Var
• help: Multiplier applied to scene color. Helps to

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.Aces.SceneColorMultiplier is to apply a multiplier to the scene color in HDR rendering when using the ACES (Academy Color Encoding System) tonemapping.

This setting variable is primarily used in the rendering system of Unreal Engine, specifically in the HDR (High Dynamic Range) and color management subsystems. Based on the callsites, it’s utilized in the RenderCore module and the Engine module.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1.5f in the RenderCore.cpp file.

The variable interacts closely with other HDR-related settings, such as r.HDR.Display.MidLuminance, r.HDR.Display.MaxLuminance, and r.HDR.Aces.GamutCompression. These variables are often used together to fine-tune the HDR rendering output.

Developers must be aware that this variable directly affects the intensity of the scene color in HDR rendering. Changing this value can significantly impact the overall brightness and contrast of the rendered image. It’s a render thread safe variable, meaning it can be changed at runtime without causing threading issues.

Best practices when using this variable include:

1. Fine-tuning it in conjunction with other HDR settings for optimal visual results.
2. Testing changes across various lighting conditions and scene types to ensure consistent quality.
3. Being cautious with extreme values as they may lead to over-saturation or loss of detail in bright areas.

Regarding the associated variable CVarHDRAcesColorMultiplier:

The purpose of CVarHDRAcesColorMultiplier is to provide a programmatic interface to the r.HDR.Aces.SceneColorMultiplier setting. It’s the actual TAutoConsoleVariable object that manages the console variable.

This associated variable is used internally by the engine to access and modify the scene color multiplier value. It’s defined in the RenderCore module and is accessed in the ConfigureACESTonemapParams function to set up the ACES tonemapping parameters.

The value of CVarHDRAcesColorMultiplier is set when the r.HDR.Aces.SceneColorMultiplier console command is used, and it can be retrieved using the GetValueOnAnyThread() method.

Developers should be aware that modifying CVarHDRAcesColorMultiplier directly in code will have the same effect as changing the r.HDR.Aces.SceneColorMultiplier console variable. It’s thread-safe and can be accessed from any thread.

Best practices for using CVarHDRAcesColorMultiplier include:

1. Using it to programmatically adjust the scene color multiplier based on game logic or user settings.
2. Caching the variable for frequent access rather than looking it up repeatedly.
3. Considering performance implications when frequently changing or accessing this value, especially in performance-critical code paths.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarHDRAcesColorMultiplier(
	TEXT("r.HDR.Aces.SceneColorMultiplier"),
	1.5f,
	TEXT("Multiplier applied to scene color. Helps to"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarHDRAcesGamutCompression(

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

Scope (from outer to inner):

file
function     void HDRSettingChangedSinkCallback

Source code excerpt:

	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 CVarHDRAcesColorMultiplier. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarHDRAcesColorMultiplier(
	TEXT("r.HDR.Aces.SceneColorMultiplier"),
	1.5f,
	TEXT("Multiplier applied to scene color. Helps to"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void ConfigureACESTonemapParams

Source code excerpt:

	OutACESTonemapParams.ACESCoefsHigh_4 = PARAMS.coefsHigh[4];

	OutACESTonemapParams.ACESSceneColorMultiplier = CVarHDRAcesColorMultiplier.GetValueOnAnyThread();
	OutACESTonemapParams.ACESGamutCompression = CVarHDRAcesGamutCompression.GetValueOnAnyThread();

}

// Converts PQ signal to linear values, see https://www.itu.int/rec/R-REC-BT.2124-0-201901-I/en, conversion 3 
static inline float ST2084ToLinear(float pq)