r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale

r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale

#Overview

name: r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale

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

• type: Var
• help: Scales the depth weight of the bilateral filter

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale is to scale the depth weight of the bilateral filter in Lumen’s ReSTIR (Reservoir Spatio-Temporal Importance Resampling) gather process. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically for the ReSTIR gathering stage.

The Lumen ReSTIR gather subsystem within the rendering module relies on this setting variable. It is used in the LumenReSTIRGather.cpp file, which is part of the Renderer module.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files. The default value is set to 10000.0f.

This variable interacts directly with GLumenReSTIRGatherBilateralFilterDepthWeightScale, which is the associated C++ variable that stores the actual value. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the weight of depth differences in the bilateral filtering process. A higher value will make the filter more sensitive to depth differences, potentially preserving depth edges more strongly but possibly introducing more noise.

Best practices when using this variable include:

1. Experimenting with different values to find the right balance between noise reduction and preservation of depth details.
2. Being cautious when modifying it, as extreme values might lead to undesired visual artifacts.
3. Considering the interaction with other ReSTIR gather settings for optimal results.

Regarding the associated variable GLumenReSTIRGatherBilateralFilterDepthWeightScale:

The purpose of GLumenReSTIRGatherBilateralFilterDepthWeightScale is to store the actual value of the depth weight scale used in the bilateral filter of Lumen’s ReSTIR gather process.

This variable is used in the Lumen ReSTIR gather subsystem within the rendering module. It’s defined and used in the LumenReSTIRGather.cpp file.

The value of this variable is set directly in the code (default 10000.0f) and can be modified through the r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale console variable.

It interacts with the PassParameters of the ReSTIR gather pass, specifically being assigned to PassParameters->BilateralFilterDepthWeightScale.

Developers should be aware that this variable directly affects the rendering process and changes to it will immediately impact the visual output of the Lumen global illumination system.

Best practices for using this variable include:

1. Modifying it through the console variable rather than changing the code directly for easier experimentation and runtime adjustments.
2. Monitoring performance impacts when adjusting this value, as it may affect shader complexity.
3. Considering its effects in conjunction with other bilateral filter parameters for a holistic approach to tuning the ReSTIR gather process.

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

Scope: file

Source code excerpt:

float GLumenReSTIRGatherBilateralFilterDepthWeightScale = 10000.0f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterDepthWeightScale(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale"),
	GLumenReSTIRGatherBilateralFilterDepthWeightScale,
	TEXT("Scales the depth weight of the bilateral filter"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale = .2f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRGatherBilateralFilterDepthWeightScale = 10000.0f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterDepthWeightScale(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.DepthWeightScale"),
	GLumenReSTIRGatherBilateralFilterDepthWeightScale,
	TEXT("Scales the depth weight of the bilateral filter"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		PassParameters->BilateralFilterSpatialKernelRadius = GLumenReSTIRGatherBilateralFilterSpatialKernelRadius;
		PassParameters->BilateralFilterNumSamples = GLumenReSTIRGatherBilateralFilterNumSamples;
		PassParameters->BilateralFilterDepthWeightScale = GLumenReSTIRGatherBilateralFilterDepthWeightScale;
		PassParameters->BilateralFilterNormalAngleThresholdScale = GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale;
		PassParameters->BilateralFilterStrongBlurVarianceThreshold = GLumenReSTIRGatherBilateralFilterStrongBlurVarianceThreshold;
		PassParameters->View = View.ViewUniformBuffer;
		PassParameters->SceneTexturesStruct = SceneTextures.UniformBuffer;
		PassParameters->Substrate = Substrate::BindSubstrateGlobalUniformParameters(View);