r.AutoExposure.LuminanceMethod

r.AutoExposure.LuminanceMethod

#Overview

name: r.AutoExposure.LuminanceMethod

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AutoExposure.LuminanceMethod is to control the luminance calculation method used in the auto-exposure (eye adaptation) system of Unreal Engine’s rendering pipeline. This setting variable allows developers to choose between different color space weightings when calculating scene luminance.

This setting variable is primarily used by the rendering system, specifically in the post-processing stage for eye adaptation calculations.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the post-processing components dealing with eye adaptation and auto-exposure.

The value of this variable is set through the console variable system. It can be changed at runtime using console commands or through configuration files.

The associated variable CVarAutoExposureLuminanceMethod interacts directly with r.AutoExposure.LuminanceMethod. They share the same value and purpose.

Developers must be aware that this variable affects how the engine calculates the overall brightness of a scene, which in turn influences the auto-exposure effect. The chosen method can impact the visual appearance and perceived brightness of the rendered image.

Best practices when using this variable include:

  1. Testing different luminance methods to find the one that best suits your project’s visual style.
  2. Considering the color space and intended display output when choosing a method.
  3. Documenting the chosen method in the project settings for consistency across the development team.

Regarding the associated variable CVarAutoExposureLuminanceMethod:

The purpose of CVarAutoExposureLuminanceMethod is identical to r.AutoExposure.LuminanceMethod. It’s an internal representation of the console variable used within the C++ code.

This variable is used directly in the rendering code to determine which luminance calculation method to apply. It’s accessed in the GetEyeAdaptationParameters function, where the luminance weights are set based on the selected method.

The value of CVarAutoExposureLuminanceMethod is set automatically by the console variable system when r.AutoExposure.LuminanceMethod is modified.

Developers should be aware that changing this variable at runtime will immediately affect the rendering pipeline’s luminance calculations.

Best practices for using CVarAutoExposureLuminanceMethod include:

  1. Avoiding direct manipulation of this variable in code; instead, use the r.AutoExposure.LuminanceMethod console command or project settings.
  2. When reading this value in custom rendering code, always use GetValueOnRenderThread() to ensure thread-safety.
  3. Consider caching the value if used frequently in performance-critical sections of code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:79

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	TAutoConsoleVariable<int32> CVarAutoExposureLuminanceMethod(
		TEXT("r.AutoExposure.LuminanceMethod"),
		0,
		TEXT("0 - Uniform.\n")
		TEXT("1 - NSTC.\n")
		TEXT("2 - Rec709."),
		ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:78

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

		ECVF_Scalability | ECVF_RenderThreadSafe);

	TAutoConsoleVariable<int32> CVarAutoExposureLuminanceMethod(
		TEXT("r.AutoExposure.LuminanceMethod"),
		0,
		TEXT("0 - Uniform.\n")
		TEXT("1 - NSTC.\n")
		TEXT("2 - Rec709."),
		ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:542

Scope (from outer to inner):

file
function     FEyeAdaptationParameters GetEyeAdaptationParameters

Source code excerpt:

	Parameters.MeterMaskSampler = TStaticSamplerState<SF_Bilinear, AM_Clamp, AM_Clamp, AM_Clamp>::GetRHI();

	const int32 LuminanceMethod = CVarAutoExposureLuminanceMethod.GetValueOnRenderThread();
	if (LuminanceMethod == 1)
	{
		// NTSC / match weights in Common.ush
		Parameters.LuminanceWeights = FVector3f(0.3f, 0.59f, 0.11f);
	}
	else if (LuminanceMethod == 2)