r.Lumen.ReSTIRGather.TemporalResampling.DistanceThreshold

r.Lumen.ReSTIRGather.TemporalResampling.DistanceThreshold

#Overview

name: r.Lumen.ReSTIRGather.TemporalResampling.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.TemporalResampling.DistanceThreshold is to set a distance threshold for temporal resampling in the Lumen ReSTIR (Reservoir Spatiotemporal Importance Resampling) gathering process. This variable is part of Unreal Engine 5’s advanced rendering system, specifically the Lumen global illumination feature.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized within the LumenReSTIRGather.cpp file, which is responsible for the ReSTIR gathering process in Lumen.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 0.005f and can be modified at runtime using the console command system.

The associated variable GLumenReSTIRTemporalResamplingHistoryDistanceThreshold directly interacts with this console variable. They share the same value, with the console variable acting as an interface to modify the global variable used in the rendering code.

Developers should be aware that this variable affects the temporal stability of the ReSTIR gathering process. A lower threshold might result in more stable results across frames but could potentially miss some lighting changes, while a higher threshold might be more responsive to changes but could introduce more temporal artifacts.

Best practices when using this variable include:

  1. Fine-tuning the value based on the specific needs of your scene and desired visual quality.
  2. Testing different values to find the right balance between temporal stability and responsiveness to lighting changes.
  3. Considering the performance impact of adjusting this value, as it may affect the number of samples being processed.

Regarding the associated variable GLumenReSTIRTemporalResamplingHistoryDistanceThreshold:

The purpose of this variable is to store the actual distance threshold value used in the rendering code. It’s a float variable that directly influences the temporal resampling process in the Lumen ReSTIR gathering.

This variable is used within the Lumen subsystem of the rendering module, specifically in the temporal resampling pass of the ReSTIR gathering process.

Its value is set by the console variable r.Lumen.ReSTIRGather.TemporalResampling.DistanceThreshold, allowing for runtime modification.

In the provided code, we can see that this variable is used to set the HistoryDistanceThreshold parameter in the temporal resampling compute shader pass.

Developers should be aware that modifying this variable will directly affect the temporal resampling behavior in the Lumen ReSTIR gathering process. It’s crucial to understand its impact on both visual quality and performance.

Best practices for using this variable include:

  1. Modifying it through the console variable system rather than changing the code directly.
  2. Monitoring its effects on both visual quality and performance when adjusting its value.
  3. Documenting any custom values used for specific scenes or rendering scenarios.

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

Scope: file

Source code excerpt:

float GLumenReSTIRTemporalResamplingHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarReSTIRTemporalResamplingHistoryDistanceThreshold(
	TEXT("r.Lumen.ReSTIRGather.TemporalResampling.DistanceThreshold"),
	GLumenReSTIRTemporalResamplingHistoryDistanceThreshold,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRTemporalResamplingResetHistory = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRTemporalResamplingHistoryDistanceThreshold = .005f;
FAutoConsoleVariableRef CVarReSTIRTemporalResamplingHistoryDistanceThreshold(
	TEXT("r.Lumen.ReSTIRGather.TemporalResampling.DistanceThreshold"),
	GLumenReSTIRTemporalResamplingHistoryDistanceThreshold,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRTemporalResamplingResetHistory = 0;
FAutoConsoleVariableRef CVarLumenReSTIRTemporalResamplingResetHistory(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

			PassParameters->DownsampledDepthHistory = TemporalResamplingState.DownsampledDepthHistoryRT ? GraphBuilder.RegisterExternalTexture(TemporalResamplingState.DownsampledDepthHistoryRT) : PassParameters->ReSTIRParameters.DownsampledSceneDepth;
			PassParameters->DownsampledNormalHistory = TemporalResamplingState.DownsampledNormalHistoryRT ? GraphBuilder.RegisterExternalTexture(TemporalResamplingState.DownsampledNormalHistoryRT) : PassParameters->ReSTIRParameters.DownsampledWorldNormal;
			PassParameters->HistoryDistanceThreshold = GLumenReSTIRTemporalResamplingHistoryDistanceThreshold;

			FTemporalResamplingCS::FPermutationDomain PermutationVector;
			auto ComputeShader = View.ShaderMap->GetShader<FTemporalResamplingCS>(PermutationVector);

			FComputeShaderUtils::AddPass(
				GraphBuilder,