r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance

r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance

#Overview

name: r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance

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

• type: Var
• help: Length of occlusion screen traces used to validate the neighbor\'s reservoir hit position before reuse, to reduce leaking. As a fraction of the screen size.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance is to control the length of occlusion screen traces used in Lumen’s ReSTIR (Reservoir Spatio-Temporal Importance Resampling) gather process. This setting is specifically used to validate the neighbor’s reservoir hit position before reuse, with the aim of reducing light leaking artifacts.

This setting variable is primarily used in the Lumen subsystem, which is part of Unreal Engine’s rendering system. It’s specifically utilized in the ReSTIR gather process, which is an advanced global illumination technique.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as a float with a default value of 0.2, representing 20% of the screen size.

The associated variable GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance directly interacts with this console variable. They share the same value, with the console variable controlling the value of the C++ variable.

Developers must be aware that this variable affects the quality and performance trade-off in the Lumen ReSTIR gather process. A larger value may reduce light leaking but could potentially increase the computational cost.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of the scene, as different environments may require different settings for optimal results.
2. Balancing it with other Lumen ReSTIR settings for the best quality-performance ratio.
3. Testing thoroughly after changes, as it can impact both visual quality and performance.

Regarding the associated variable GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance:

The purpose of this variable is to store the actual value used in the rendering code for the occlusion screen trace distance in Lumen’s ReSTIR spatial resampling process.

This variable is used directly in the Lumen ReSTIR gather rendering pass, specifically in the FDeferredShadingSceneRenderer::RenderLumenReSTIRGather function.

Its value is set by the console variable r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance.

This variable interacts closely with other ReSTIR gather parameters such as SpatialResamplingKernelRadius and NumSpatialSamples.

Developers should be aware that modifying this variable directly in code is not recommended, as its value is intended to be controlled via the console variable system.

Best practices include using the console variable for runtime adjustments and debugging, and relying on the C++ variable for actual rendering calculations in the engine code.

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

Scope: file

Source code excerpt:

float GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance"),
	GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance,
	TEXT("Length of occlusion screen traces used to validate the neighbor's reservoir hit position before reuse, to reduce leaking.  As a fraction of the screen size."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRMaxRayIntensity = 100;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.OcclusionScreenTraceDistance"),
	GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance,
	TEXT("Length of occlusion screen traces used to validate the neighbor's reservoir hit position before reuse, to reduce leaking.  As a fraction of the screen size."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRMaxRayIntensity = 100;
FAutoConsoleVariableRef CVarLumenReSTIRMaxRayIntensity(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		PassParameters->SceneTextures = GetSceneTextureParameters(GraphBuilder, SceneTextures.UniformBuffer);
		PassParameters->SpatialResamplingKernelRadius = GLumenReSTIRSpatialResamplingKernelRadius;
		PassParameters->SpatialResamplingOcclusionScreenTraceDistance = GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance;
		PassParameters->NumSpatialSamples = GLumenReSTIRNumSpatialSamples;
		PassParameters->SpatialResamplingPassIndex = SpatialResamplingPassIndex;

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