r.Lumen.ReSTIRGather.Temporal.DistanceThreshold

r.Lumen.ReSTIRGather.Temporal.DistanceThreshold

#Overview

name: r.Lumen.ReSTIRGather.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.ReSTIRGather.Temporal.DistanceThreshold is to control the relative distance threshold for discarding last frame’s lighting results in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gather process.

This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically the ReSTIR gather component. It is primarily used in the rendering subsystem, particularly in the Lumen module.

The value of this variable is set through the FAutoConsoleVariableRef mechanism, which allows it to be modified at runtime via console commands. Its default value is 0.005f.

The associated variable GLumenReSTIRGatherHistoryDistanceThreshold directly interacts with r.Lumen.ReSTIRGather.Temporal.DistanceThreshold. They share the same value and are used interchangeably 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 walls but may increase flickering artifacts.

Best practices when using this variable include:

  1. Carefully adjusting the value to balance between ghosting reduction and flickering artifacts.
  2. Testing the effects of different values in various lighting scenarios and with moving objects.
  3. Considering the performance impact of very low values, as they may lead to more frequent recalculations of lighting.

Regarding the associated variable GLumenReSTIRGatherHistoryDistanceThreshold:

The purpose of GLumenReSTIRGatherHistoryDistanceThreshold is to store and provide access to the distance threshold value within the C++ code of the Lumen system.

This variable is used directly in the DispatchTemporalAccumulation function within the Lumen ReSTIR gather process. It’s part of the rendering subsystem, specifically the Lumen module.

The value of GLumenReSTIRGatherHistoryDistanceThreshold is set by the r.Lumen.ReSTIRGather.Temporal.DistanceThreshold console variable.

This variable interacts directly with the PassParameters->HistoryDistanceThreshold in the temporal accumulation process of Lumen ReSTIR gather.

Developers should be aware that modifying this variable directly in code might lead to inconsistencies with the console variable. It’s best to modify the console variable instead.

Best practices include using this variable for read-only purposes in the code and relying on the console variable for modifications to ensure consistency across the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:189

Scope: file

Source code excerpt:

float GLumenReSTIRGatherHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherHistoryDistanceThreshold(
	TEXT("r.Lumen.ReSTIRGather.Temporal.DistanceThreshold"),
	GLumenReSTIRGatherHistoryDistanceThreshold,
	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 GLumenReSTIRGatherTemporalMaxFramesAccumulated = 10.0f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:187

Scope: file

Source code excerpt:

);

float GLumenReSTIRGatherHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherHistoryDistanceThreshold(
	TEXT("r.Lumen.ReSTIRGather.Temporal.DistanceThreshold"),
	GLumenReSTIRGatherHistoryDistanceThreshold,
	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 GLumenReSTIRGatherTemporalMaxFramesAccumulated = 10.0f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherTemporalMaxFramesAccumulated(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReSTIRGather.cpp:807

Scope (from outer to inner):

file
function     void DispatchTemporalAccumulation
lambda-function

Source code excerpt:

						PassParameters->HistoryNumFramesAccumulated = OldHistoryNumFramesAccumulated;

						PassParameters->HistoryDistanceThreshold = GLumenReSTIRGatherHistoryDistanceThreshold;
						PassParameters->PrevSceneColorPreExposureCorrection = View.PreExposure / View.PrevViewInfo.SceneColorPreExposure;

						const float MaxFramesAccumulatedScale = 1.0f / FMath::Sqrt(FMath::Clamp(View.FinalPostProcessSettings.LumenFinalGatherLightingUpdateSpeed, .5f, 8.0f));
						const float EditingScale = View.Family->bCurrentlyBeingEdited ? .5f : 1.0f;
						PassParameters->MaxFramesAccumulated = FMath::RoundToInt(GLumenReSTIRGatherTemporalMaxFramesAccumulated * MaxFramesAccumulatedScale * EditingScale);
						PassParameters->HistoryScreenPositionScaleBias = *DiffuseIndirectHistoryScreenPositionScaleBias;