r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold

r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold

#Overview

name: r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold

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

• type: Var
• help: Largest depth error between two reservoirs that will be allowed during reservoir resampling

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold is to control the maximum allowed depth error between two reservoirs during reservoir resampling in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gather process.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s specifically part of the ReSTIR gather process, which is a technique used to improve the quality and performance of real-time global illumination.

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.01f.

The associated variable GLumenReSTIRResamplingDepthErrorThreshold directly interacts with this console variable. They share the same value, with GLumenReSTIRResamplingDepthErrorThreshold being the C++ variable that’s used in the actual rendering code.

Developers must be aware that this variable affects the quality and performance trade-off in the Lumen ReSTIR gather process. A lower value will result in more accurate depth comparisons during resampling, potentially improving quality but at the cost of performance. A higher value will be more lenient in depth comparisons, potentially improving performance but possibly introducing artifacts.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your scene and performance targets.
2. Testing with different values to find the optimal balance between quality and performance.
3. Considering the scale of your scene, as the appropriate value might vary depending on the size and depth range of your environments.

Regarding the associated variable GLumenReSTIRResamplingDepthErrorThreshold:

The purpose of GLumenReSTIRResamplingDepthErrorThreshold is to store the actual value used in the rendering code for the depth error threshold in Lumen’s ReSTIR gather process.

This variable is used directly in the Lumen ReSTIR gather rendering code, specifically in the RenderLumenReSTIRGather function of the FDeferredShadingSceneRenderer class.

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

It interacts directly with the ReSTIRParameters structure, specifically setting the ResamplingDepthErrorThreshold field.

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.

The best practice is to use the console variable r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold to adjust this value, rather than modifying GLumenReSTIRResamplingDepthErrorThreshold directly in the 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:122

Scope: file

Source code excerpt:

float GLumenReSTIRResamplingDepthErrorThreshold = .01f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingDepthErrorThreshold(
	TEXT("r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold"),
	GLumenReSTIRResamplingDepthErrorThreshold,
	TEXT("Largest depth error between two reservoirs that will be allowed during reservoir resampling"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance = .2f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRResamplingDepthErrorThreshold = .01f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingDepthErrorThreshold(
	TEXT("r.Lumen.ReSTIRGather.ResamplingDepthErrorThreshold"),
	GLumenReSTIRResamplingDepthErrorThreshold,
	TEXT("Largest depth error between two reservoirs that will be allowed during reservoir resampling"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

	ReSTIRParameters.FixedJitterIndex = GLumenReSTIRGatherFixedJitterIndex;
	ReSTIRParameters.ResamplingNormalDotThreshold = FMath::Cos(GLumenReSTIRResamplingAngleThreshold * PI / 180.0f);
	ReSTIRParameters.ResamplingDepthErrorThreshold = GLumenReSTIRResamplingDepthErrorThreshold;

	ReSTIRParameters.Textures = AllocateReservoirTextures(GraphBuilder, ReservoirBufferSize);
	ReSTIRParameters.UAVs = CreateReservoirUAVs(GraphBuilder, ReSTIRParameters.Textures);
	
	FRDGTextureDesc DownsampledSceneDepthDesc(FRDGTextureDesc::Create2D(ReservoirBufferSize, PF_R32_FLOAT, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV));
	ReSTIRParameters.DownsampledSceneDepth = GraphBuilder.CreateTexture(DownsampledSceneDepthDesc, TEXT("Lumen.ReSTIRGather.DownsampledSceneDepth"));