r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame

r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame

#Overview

name: r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame

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.ClearHistoryEveryFrame is to control the clearing of temporal history in the Lumen ReSTIR (Resampled Importance Sampling for Real-Time) gather process. It is primarily used for debugging purposes in the rendering system, specifically in the Lumen global illumination subsystem of Unreal Engine 5.

This setting variable is relied upon by the Lumen subsystem within the Renderer module of Unreal Engine 5. It is particularly used in the ReSTIR gather process, which is a part of the advanced global illumination techniques employed by Lumen.

The value of this variable is set through the Unreal Engine console variable system. It is defined as an integer (int32) and initialized to 0 by default.

The associated variable GLumenReSTIRGatherClearHistoryEveryFrame directly interacts with this console variable. They share the same value, with the console variable acting as the interface for developers to modify the setting.

Developers must be aware that enabling this variable (setting it to 1) will clear the temporal history every frame. This can significantly impact performance and visual quality, as it prevents the accumulation of lighting information over time, which is a key aspect of the Lumen lighting system. Therefore, it should only be used for debugging purposes and not in production builds.

Best practices when using this variable include:

  1. Keep it disabled (set to 0) for normal operation and final builds.
  2. Use it temporarily when debugging temporal artifacts or investigating issues related to the ReSTIR gather process.
  3. Be aware of the performance implications when enabled, as it will likely increase the computational load per frame.
  4. When enabled, expect a potential decrease in image quality due to the lack of temporal accumulation.

Regarding the associated variable GLumenReSTIRGatherClearHistoryEveryFrame:

The purpose of GLumenReSTIRGatherClearHistoryEveryFrame is to serve as the internal representation of the r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame console variable within the engine’s C++ code.

This variable is used directly in the Lumen ReSTIR gather process, specifically in the DispatchTemporalAccumulation function within the LumenReSTIRGather.cpp file. It’s part of the condition that determines whether to perform temporal accumulation.

The value of this variable is set by the associated console variable r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame.

It interacts closely with other conditions in the temporal accumulation process, such as camera cuts, previous transform resets, and scene texture extent matching.

Developers should be aware that this variable directly affects the frame-to-frame coherence of the Lumen lighting system. When set to true (non-zero), it will prevent the use of previous frame information in the current frame’s lighting calculations.

Best practices for this variable are essentially the same as for the console variable it’s associated with. It should generally be left at its default value (0) unless specifically needed for debugging purposes.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRGatherClearHistoryEveryFrame = 0;
FAutoConsoleVariableRef CVarLumenReSTIRGatherClearHistoryEveryFrame(
	TEXT("r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame"),
	GLumenReSTIRGatherClearHistoryEveryFrame,
	TEXT("Whether to clear the history every frame for debugging"),
	ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherHistoryDistanceThreshold = .005f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRGatherClearHistoryEveryFrame = 0;
FAutoConsoleVariableRef CVarLumenReSTIRGatherClearHistoryEveryFrame(
	TEXT("r.Lumen.ReSTIRGather.Temporal.ClearHistoryEveryFrame"),
	GLumenReSTIRGatherClearHistoryEveryFrame,
	TEXT("Whether to clear the history every frame for debugging"),
	ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherHistoryDistanceThreshold(

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

Scope (from outer to inner):

file
function     void DispatchTemporalAccumulation

Source code excerpt:

			&& !View.bCameraCut 
			&& !View.bPrevTransformsReset
			&& !GLumenReSTIRGatherClearHistoryEveryFrame
			&& bSceneTextureExtentMatchHistory
			&& (!bUseBilaterialFilter || TemporalAccumulationState.ResolveVarianceHistoryRT)
			&& !bPropagateGlobalLightingChange)
		{
			FRDGTextureDesc DiffuseIndirectDesc = FRDGTextureDesc::Create2DArray(EffectiveResolution, PF_FloatRGBA, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV, ClosureCount);
			FRDGTextureDesc RoughSpecularIndirectDesc = FRDGTextureDesc::Create2DArray(EffectiveResolution, PF_FloatRGB, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV, ClosureCount);