r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames

r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames

#Overview

name: r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames

This variable is created as a Console Variable (cvar).

• type: Var
• help: Validate temporal reservoirs by re-tracing their rays and comparing hit positions and radiance every N frames. Used to reduce lag in lighting changes, but introduces noise.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames is to control the validation frequency of temporal reservoirs in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gathering process. This setting is part of Unreal Engine 5’s rendering system, specifically the Lumen global illumination system.

This setting variable is primarily used by the Lumen subsystem within the Renderer module of Unreal Engine 5. It’s particularly relevant to the ReSTIR gathering process, which is a technique used to improve the efficiency and quality of real-time ray tracing.

The value of this variable is set through the Unreal Engine console or configuration files. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime.

The associated variable GLumenReSTIRValidateTemporalReservoirsEveryNFrames directly interacts with this setting. They share the same value and purpose.

Developers must be aware that:

1. This variable affects the trade-off between lighting responsiveness and noise in the rendered image.
2. Validating temporal reservoirs more frequently (lower N value) will reduce lag in lighting changes but introduce more noise.
3. The validation process involves re-tracing rays and comparing hit positions and radiance, which can have performance implications.

Best practices when using this variable include:

1. Adjust the value based on the specific needs of your scene and performance targets.
2. Monitor the performance impact when changing this value, especially in performance-critical scenarios.
3. Consider using different values for different quality settings in your game.

Regarding the associated variable GLumenReSTIRValidateTemporalReservoirsEveryNFrames:

• Its purpose is identical to the console variable - to control the frequency of temporal reservoir validation.
• It’s used directly in the rendering code to determine when to perform the validation.
• The value is checked in the RenderLumenReSTIRGather function to decide whether to validate temporal reservoirs for the current frame.
• Developers should be aware that this variable is used in conjunction with the ViewState’s frame index to determine validation timing.
• Best practice is to treat this variable as read-only in most cases, allowing it to be controlled via the console variable for easier runtime adjustments and debugging.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRValidateTemporalReservoirsEveryNFrames = 0;
FAutoConsoleVariableRef CVarLumenReSTIRTemporalResamplingValidate(
	TEXT("r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames"),
	GLumenReSTIRValidateTemporalReservoirsEveryNFrames,
	TEXT("Validate temporal reservoirs by re-tracing their rays and comparing hit positions and radiance every N frames.  Used to reduce lag in lighting changes, but introduces noise."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRTemporalResamplingHistoryDistanceThreshold = .005f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

int32 GLumenReSTIRValidateTemporalReservoirsEveryNFrames = 0;
FAutoConsoleVariableRef CVarLumenReSTIRTemporalResamplingValidate(
	TEXT("r.Lumen.ReSTIRGather.TemporalResampling.ValidateEveryNFrames"),
	GLumenReSTIRValidateTemporalReservoirsEveryNFrames,
	TEXT("Validate temporal reservoirs by re-tracing their rays and comparing hit positions and radiance every N frames.  Used to reduce lag in lighting changes, but introduces noise."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRTemporalResamplingHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarReSTIRTemporalResamplingHistoryDistanceThreshold(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

	const bool bValidateTemporalReservoirs = View.ViewState 
		&& GLumenReSTIRValidateTemporalReservoirsEveryNFrames > 0
		&& (View.ViewState->GetFrameIndex() % GLumenReSTIRValidateTemporalReservoirsEveryNFrames) == 0;

	if (bValidateTemporalReservoirs)
	{
		FReSTIRTemporalResamplingState& TemporalResamplingState = View.ViewState->Lumen.ReSTIRGatherState.TemporalResamplingState;

		if (TemporalResamplingState.TemporalReservoirRayDirectionRT