r.Lumen.ScreenProbeGather.Temporal.NormalThreshold

r.Lumen.ScreenProbeGather.Temporal.NormalThreshold

#Overview

name: r.Lumen.ScreenProbeGather.Temporal.NormalThreshold

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.Lumen.ScreenProbeGather.Temporal.NormalThreshold is to control the maximum angle between the history texel’s normal and the current pixel’s normal for accepting history lighting in Lumen’s screen probe gather process.

This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically within the screen probe gathering subsystem. It is used in the rendering module, as evidenced by its location in the Renderer directory.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 45.0 degrees and can be modified at runtime.

The variable interacts directly with GLumenScreenProbeTemporalHistoryNormalThreshold, which is the C++ variable that stores the actual value. They share the same value, with the console variable serving as an interface for adjusting the C++ variable.

Developers should be aware that this variable is measured in degrees and affects the temporal stability of Lumen’s screen probe lighting. A higher value will allow for more temporal stability but may introduce more artifacts, while a lower value will reduce artifacts but may result in more temporal instability.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of the scene and the desired balance between temporal stability and artifact reduction.
  2. Testing different values to find the optimal setting for your specific use case.
  3. Being mindful of performance implications, as very low values might increase the frequency of recomputation.

Regarding the associated variable GLumenScreenProbeTemporalHistoryNormalThreshold:

The purpose of GLumenScreenProbeTemporalHistoryNormalThreshold is to store the actual value used in the rendering calculations for the normal threshold in Lumen’s screen probe temporal gathering.

This C++ variable is used directly in the Lumen screen probe gather system within the rendering module. Its value is set by the r.Lumen.ScreenProbeGather.Temporal.NormalThreshold console variable.

The value of this variable is used in calculations to determine whether to accept history lighting for a pixel. It’s converted from degrees to radians and then to a cosine value for efficient comparisons in the shader code.

This variable interacts with other parameters in the UpdateHistoryScreenProbeGather function, contributing to the overall temporal stability calculation of the Lumen screen probe system.

Developers should be aware that this variable’s value is used directly in performance-critical rendering code, so frequent changes might have a noticeable impact on rendering performance.

Best practices for this variable include:

  1. Avoiding direct modification of this variable in C++ code, instead using the console variable for adjustments.
  2. Considering the impact on both visual quality and performance when adjusting its value.
  3. Using it in conjunction with other Lumen settings to achieve the desired balance of quality and performance in global illumination.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:224

Scope: file

Source code excerpt:

float GLumenScreenProbeTemporalHistoryNormalThreshold = 45.0f;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalHistoryNormalThreshold(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.NormalThreshold"),
	GLumenScreenProbeTemporalHistoryNormalThreshold,
	TEXT("Maximum angle that the history texel's normal can be from the current pixel to accept it's history lighting, in degrees."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenScreenProbeScreenTracesThicknessScaleWhenNoFallback = 2;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:222

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

float GLumenScreenProbeTemporalHistoryNormalThreshold = 45.0f;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalHistoryNormalThreshold(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.NormalThreshold"),
	GLumenScreenProbeTemporalHistoryNormalThreshold,
	TEXT("Maximum angle that the history texel's normal can be from the current pixel to accept it's history lighting, in degrees."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenScreenProbeScreenTracesThicknessScaleWhenNoFallback = 2;
FAutoConsoleVariableRef CVarLumenScreenProbeScreenTracesThicknessScaleWhenNoFallback(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:1483

Scope (from outer to inner):

file
function     void UpdateHistoryScreenProbeGather
lambda-function

Source code excerpt:

						const float EditingScale = View.Family->bCurrentlyBeingEdited ? .5f : 1.0f;
						PassParameters->MaxFramesAccumulated = FMath::RoundToInt(GLumenScreenProbeTemporalMaxFramesAccumulated * MaxFramesAccumulatedScale * EditingScale);
						PassParameters->HistoryNormalCosThreshold = FMath::Cos(GLumenScreenProbeTemporalHistoryNormalThreshold * (float)PI / 180.0f);
						PassParameters->HistoryScreenPositionScaleBias = *DiffuseIndirectHistoryScreenPositionScaleBias;

						const FVector2f HistoryUVToScreenPositionScale(1.0f / PassParameters->HistoryScreenPositionScaleBias.X, 1.0f / PassParameters->HistoryScreenPositionScaleBias.Y);
						const FVector2f HistoryUVToScreenPositionBias = -FVector2f(PassParameters->HistoryScreenPositionScaleBias.W, PassParameters->HistoryScreenPositionScaleBias.Z) * HistoryUVToScreenPositionScale;
						PassParameters->HistoryUVToScreenPositionScaleBias = FVector4f(HistoryUVToScreenPositionScale, HistoryUVToScreenPositionBias);