r.HDR.Aces.GamutCompression

r.HDR.Aces.GamutCompression

#Overview

name: r.HDR.Aces.GamutCompression

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HDR.Aces.GamutCompression is to control the HDR equivalent of BlueCorrection in the ACES (Academy Color Encoding System) tonemapping process. It specifically affects how bright blue colors are desaturated instead of shifting towards violet in HDR rendering.

This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically in the HDR 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 the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with a default value of 0.0f, which can be changed at runtime.

The variable interacts with other HDR-related variables, such as r.HDR.Display.MaxLuminance and r.HDR.Aces.SceneColorMultiplier. These variables are often used together to configure the HDR rendering pipeline.

Developers must be aware that this variable affects the color appearance of bright blue areas in HDR content. Adjusting this value can help achieve a more natural look for bright blue elements in a scene, preventing them from shifting towards an unrealistic violet hue.

Best practices when using this variable include:

  1. Experimenting with different values to find the optimal setting for your specific HDR content.
  2. Considering this variable in conjunction with other HDR and color management settings for a holistic approach to color grading.
  3. Testing the results on various HDR displays to ensure consistency across different viewing conditions.

Regarding the associated variable CVarHDRAcesGamutCompression:

This is the actual console variable object that stores and manages the r.HDR.Aces.GamutCompression value. It’s defined in the RenderCore module and is used to retrieve the current value of the setting in various parts of the engine, particularly in the ConfigureACESTonemapParams function.

The purpose of CVarHDRAcesGamutCompression is to provide a programmatic interface for accessing and modifying the r.HDR.Aces.GamutCompression value within the engine’s C++ code.

This variable is crucial for the HDR rendering pipeline, specifically in configuring the ACES tonemapping parameters. It’s accessed using the GetValueOnAnyThread() method, which allows retrieving its value from any thread in the engine.

Developers should be aware that changes to this variable will affect the HDR rendering in real-time, and it’s marked as ECVF_RenderThreadSafe, meaning it’s safe to modify from the render thread.

Best practices for using CVarHDRAcesGamutCompression include:

  1. Using it in conjunction with other ACES tonemapping parameters for a comprehensive HDR setup.
  2. Considering performance implications when frequently accessing or modifying this value, especially in performance-critical code paths.
  3. Properly synchronizing access to this variable if it’s modified from multiple threads, despite its thread-safe nature.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarHDRAcesGamutCompression(
	TEXT("r.HDR.Aces.GamutCompression"),
	0.0f,
	TEXT("HDR equivalent of BlueCorrection: Bright blue desaturates instead of going to violet"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarHDROutputEnabled(

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

Scope (from outer to inner):

file
function     void HDRSettingChangedSinkCallback

Source code excerpt:

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarHDRAcesGamutCompression(
	TEXT("r.HDR.Aces.GamutCompression"),
	0.0f,
	TEXT("HDR equivalent of BlueCorrection: Bright blue desaturates instead of going to violet"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void ConfigureACESTonemapParams

Source code excerpt:


	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)
{