r.Lumen.Reflections.Temporal.DistanceThreshold

r.Lumen.Reflections.Temporal.DistanceThreshold

#Overview

name: r.Lumen.Reflections.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.Reflections.Temporal.DistanceThreshold is to control the temporal stability of Lumen reflections in Unreal Engine 5’s rendering system. It sets a world space distance threshold for discarding the previous frame’s lighting results in reflections.

This setting variable is primarily used by the Lumen reflections subsystem within Unreal Engine’s rendering module. It’s specifically part of the temporal processing of reflections, which aims to improve the stability and quality of reflections over time.

The value of this variable is set through the engine’s console variable system. It’s initialized with a default value of 0.03 and can be modified at runtime or through configuration files.

The associated variable GLumenReflectionHistoryDistanceThreshold directly interacts with this setting. It’s the C++ variable that stores the actual value used in the rendering code.

Developers must be aware that this variable presents a trade-off between reducing ghosting artifacts and increasing flickering. Lower values will reduce ghosting from moving objects (like characters) near reflective surfaces but may introduce more flickering in the reflections.

Best practices when using this variable include:

  1. Fine-tuning the value based on the specific needs of your scene and the movement speed of objects.
  2. Testing with various values to find the right balance between reducing ghosting and minimizing flickering.
  3. Considering different values for different types of scenes or gameplay situations.

Regarding the associated variable GLumenReflectionHistoryDistanceThreshold:

This is the actual C++ variable that stores the value set by r.Lumen.Reflections.Temporal.DistanceThreshold. It’s used directly in the rendering code, specifically in the UpdateHistoryReflections function of the Lumen reflections system.

The purpose of this variable is to provide fast, runtime access to the distance threshold value within the C++ code of the rendering system. It’s set automatically when the console variable is modified, ensuring that changes to the setting are immediately reflected in the rendering pipeline.

Developers should be aware that modifying this variable directly in C++ code is not recommended. Instead, they should use the console variable system to ensure proper synchronization and to maintain the ability to adjust the value at runtime or through configuration files.

Best practices for this associated variable include:

  1. Always access it through the GLumenReflectionHistoryDistanceThreshold global variable in C++ code.
  2. Avoid caching its value, as it can be changed at runtime.
  3. Consider its performance impact when used in frequently called rendering functions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:134

Scope: file

Source code excerpt:

float GLumenReflectionHistoryDistanceThreshold = .03f;
FAutoConsoleVariableRef CVarLumenReflectionHistoryDistanceThreshold(
	TEXT("r.Lumen.Reflections.Temporal.DistanceThreshold"),
	GLumenReflectionHistoryDistanceThreshold,
	TEXT("World space 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 GLumenReflectionMaxRayIntensity = 100;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:132

Scope: file

Source code excerpt:

);

float GLumenReflectionHistoryDistanceThreshold = .03f;
FAutoConsoleVariableRef CVarLumenReflectionHistoryDistanceThreshold(
	TEXT("r.Lumen.Reflections.Temporal.DistanceThreshold"),
	GLumenReflectionHistoryDistanceThreshold,
	TEXT("World space 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 GLumenReflectionMaxRayIntensity = 100;
FAutoConsoleVariableRef GVarLumenReflectionMaxRayIntensity(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:927

Scope (from outer to inner):

file
function     void UpdateHistoryReflections

Source code excerpt:

			PassParameters->HistoryNumFramesAccumulated = GraphBuilder.RegisterExternalTexture(*NumFramesAccumulatedState);
			PassParameters->DepthHistory = OldDepthHistory;
			PassParameters->HistoryDistanceThreshold = GLumenReflectionHistoryDistanceThreshold;
			PassParameters->PrevInvPreExposure = 1.0f / View.PrevViewInfo.SceneColorPreExposure;
			PassParameters->HistoryScreenPositionScaleBias = *HistoryScreenPositionScaleBias;
			PassParameters->bIsSubstrateTileHistoryValid = bOverflowTileHistoryValid ? 1u : 0u;
			if (FrontLayerReflectionGBuffer)
			{
				PassParameters->FrontLayerTranslucencyGBufferParameters = *FrontLayerReflectionGBuffer;