r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold

r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold

#Overview

name: r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold

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.DistanceThreshold is to control the relative distance threshold for discarding the previous frame’s lighting results in Lumen’s screen probe gathering process. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the temporal aspect of screen probe gathering.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s referenced in the LumenScreenProbeGather.cpp file, which is part of the Renderer source code.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 0.005f.

The associated variable GLumenScreenProbeHistoryDistanceThreshold directly interacts with this setting. They share the same value, with GLumenScreenProbeHistoryDistanceThreshold being the C++ variable that stores the actual value used in the code.

Developers must be aware that this variable affects the trade-off between ghosting artifacts and flickering in the Lumen lighting system. Lower values will reduce ghosting from characters when near a wall but may increase flickering artifacts.

Best practices when using this variable include:

  1. Fine-tuning the value based on the specific needs of the scene and the desired balance between ghosting and flickering.
  2. Testing the impact of different values in various scenarios, especially with moving characters near walls.
  3. Considering the performance impact of very low values, as they may lead to more frequent lighting updates.

Regarding the associated variable GLumenScreenProbeHistoryDistanceThreshold:

The purpose of GLumenScreenProbeHistoryDistanceThreshold is to store the actual value used in the Lumen screen probe gathering process for the distance threshold.

This variable is used directly in the UpdateHistoryScreenProbeGather function within the Lumen screen probe gathering system. It’s passed as a parameter to shader code that processes the screen probe history.

The value of this variable is set by the r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold console variable.

It interacts closely with other Lumen-related variables, such as GLumenScreenProbeFractionOfLightingMovingForFastUpdateMode and GLumenScreenProbeTemporalMaxFastUpdateModeAmount, which are used in the same context for controlling the temporal aspects of Lumen’s screen probe gathering.

Developers should be aware that modifying this variable directly in C++ code might not have the intended effect, as its value is controlled by the console variable. Always use the console variable for adjustments.

Best practices include using this variable in conjunction with other Lumen settings to achieve the desired balance between lighting quality and performance, and thoroughly testing any changes across a variety of scenes and lighting conditions.

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

Scope: file

Source code excerpt:

float GLumenScreenProbeHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarLumenScreenProbeHistoryDistanceThreshold(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold"),
	GLumenScreenProbeHistoryDistanceThreshold,
	TEXT("Relative distance threshold needed to discard last frame's lighting results.  Lower values reduce ghosting from characters when near a wall but increase flickering artifacts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenScreenProbeFractionOfLightingMovingForFastUpdateMode = .1f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

float GLumenScreenProbeHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarLumenScreenProbeHistoryDistanceThreshold(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.DistanceThreshold"),
	GLumenScreenProbeHistoryDistanceThreshold,
	TEXT("Relative distance threshold needed to discard last frame's lighting results.  Lower values reduce ghosting from characters when near a wall but increase flickering artifacts."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GLumenScreenProbeFractionOfLightingMovingForFastUpdateMode = .1f;
FAutoConsoleVariableRef CVarLumenScreenProbeFractionOfLightingMovingForFastUpdateMode(

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

Scope (from outer to inner):

file
function     void UpdateHistoryScreenProbeGather
lambda-function

Source code excerpt:

						PassParameters->DiffuseIndirectNormalHistory = OldNormalHistory;

						PassParameters->HistoryDistanceThreshold = GLumenScreenProbeHistoryDistanceThreshold;
						PassParameters->PrevSceneColorPreExposureCorrection = View.PreExposure / View.PrevViewInfo.SceneColorPreExposure;
						PassParameters->InvFractionOfLightingMovingForFastUpdateMode = 1.0f / FMath::Max(GLumenScreenProbeFractionOfLightingMovingForFastUpdateMode, .001f);
						PassParameters->MaxFastUpdateModeAmount = GLumenScreenProbeTemporalMaxFastUpdateModeAmount;
						PassParameters->bIsSubstrateTileHistoryValid = bOverflowTileHistoryValid ? 1u : 0u;

						const float MaxFramesAccumulatedScale = 1.0f / FMath::Sqrt(FMath::Clamp(View.FinalPostProcessSettings.LumenFinalGatherLightingUpdateSpeed, .5f, 8.0f));