r.EyeAdaptation.LensAttenuation

r.EyeAdaptation.LensAttenuation

#Overview

name: r.EyeAdaptation.LensAttenuation

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.EyeAdaptation.LensAttenuation is to control the camera lens attenuation in the eye adaptation system, which is part of the rendering system in Unreal Engine 5. This variable affects how the engine calculates and applies exposure adjustments to simulate the human eye’s adaptation to different lighting conditions.

This setting variable is primarily used in the Renderer module, specifically within the post-processing system for eye adaptation. It’s referenced in the PostProcessEyeAdaptation.cpp file, which suggests it’s an integral part of the eye adaptation calculations.

The value of this variable is set through a console variable (CVarEyeAdaptationLensAttenuation) with a default value of 0.78. This value can be changed at runtime using console commands or through code.

The variable interacts with other parts of the eye adaptation system, particularly in the LuminanceMaxFromLensAttenuation() function, where it’s used to calculate the maximum luminance based on the lens attenuation value.

Developers should be aware that changing this value affects how the engine interprets and processes lighting information. As mentioned in the comments, setting it to 0.78 makes lighting unitless (1.0cd/m^2 becomes 1.0 at EV100), while setting it to 0.65 matches previous versions of the engine (1.0cd/m^2 becomes 1.2 at EV100).

Best practices when using this variable include:

  1. Understanding the impact on lighting calculations before modifying it.
  2. Testing thoroughly in various lighting conditions after changes.
  3. Documenting any non-default values used in the project for consistency.

Regarding the associated variable CVarEyeAdaptationLensAttenuation:

This is the actual console variable that controls the r.EyeAdaptation.LensAttenuation setting. It’s defined using TAutoConsoleVariable, which allows it to be changed at runtime.

The purpose of CVarEyeAdaptationLensAttenuation is to provide a way to access and modify the lens attenuation value dynamically. It’s used in the rendering thread, as indicated by the ECVF_RenderThreadSafe flag.

This variable is primarily used in the Renderer module, specifically in the eye adaptation post-processing system.

The value is set when the variable is initialized (default 0.78) and can be changed through console commands or programmatically.

It directly interacts with the LuminanceMaxFromLensAttenuation() function, where its value is retrieved using GetValueOnRenderThread().

Developers should be aware that this variable is thread-safe for the render thread, meaning it can be safely accessed and modified in render thread operations.

Best practices for using this variable include:

  1. Using GetValueOnRenderThread() when accessing it in render thread operations.
  2. Considering the performance implications of frequently changing this value.
  3. Ensuring that any code modifying this value is properly synchronized with the render thread.

#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:58

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	TAutoConsoleVariable<float> CVarEyeAdaptationLensAttenuation(
		TEXT("r.EyeAdaptation.LensAttenuation"),
		0.78,
		TEXT("The camera lens attenuation (q). Set this number to 0.78 for lighting to be unitless (1.0cd/m^2 becomes 1.0 at EV100) or 0.65 to match previous versions (1.0cd/m^2 becomes 1.2 at EV100)."),
		ECVF_RenderThreadSafe);

	TAutoConsoleVariable<float> CVarEyeAdaptationBlackHistogramBucketInfluence(
		TEXT("r.EyeAdaptation.BlackHistogramBucketInfluence"),

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

		ECVF_RenderThreadSafe);

	TAutoConsoleVariable<float> CVarEyeAdaptationLensAttenuation(
		TEXT("r.EyeAdaptation.LensAttenuation"),
		0.78,
		TEXT("The camera lens attenuation (q). Set this number to 0.78 for lighting to be unitless (1.0cd/m^2 becomes 1.0 at EV100) or 0.65 to match previous versions (1.0cd/m^2 becomes 1.2 at EV100)."),
		ECVF_RenderThreadSafe);

	TAutoConsoleVariable<float> CVarEyeAdaptationBlackHistogramBucketInfluence(

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

Scope (from outer to inner):

file
function     float LuminanceMaxFromLensAttenuation

Source code excerpt:

	const bool bExtendedLuminanceRange = IsExtendLuminanceRangeEnabled();

	float LensAttenuation = CVarEyeAdaptationLensAttenuation.GetValueOnRenderThread();

	// 78 is defined in the ISO 12232:2006 standard.
	const float kISOSaturationSpeedConstant = 0.78f;

	const float LuminanceMax = kISOSaturationSpeedConstant / FMath::Max<float>(LensAttenuation, .01f);