r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale

r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale

#Overview

name: r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale

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.BilateralFilter.NormalAngleThresholdScale is to scale the normal angle threshold used in the bilateral filter of Lumen’s ReSTIR (Reservoir Spatiotemporal Importance Resampling) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Specifically, it’s utilized in the ReSTIR gather process, which is a part of Lumen’s real-time global illumination solution.

The value of this variable is set in the C++ code as a default of 0.2f, but it can be modified at runtime through the Unreal Engine console or configuration files due to its declaration as an FAutoConsoleVariableRef.

This variable interacts closely with other Lumen ReSTIR gather settings, particularly those related to the bilateral filter used in the process. It’s used in conjunction with other parameters like depth weight scale and strong blur variance threshold to fine-tune the bilateral filtering process.

Developers must be aware that this variable directly affects the quality and performance of Lumen’s global illumination. A higher value will increase the tolerance for normal angle differences in the bilateral filter, potentially leading to smoother results but possibly at the cost of accuracy.

Best practices when using this variable include:

  1. Adjust it in small increments to find the optimal balance between image quality and performance.
  2. Test the changes in various lighting scenarios to ensure consistent results.
  3. Consider the interaction with other Lumen settings, as they can influence each other’s effects.

Regarding the associated variable GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale:

This is the actual float variable that stores the value set by the console variable. It’s used directly in the rendering code, specifically in the FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather function.

The purpose of this variable is the same as the console variable - to scale the normal angle threshold in the bilateral filter used in Lumen’s ReSTIR gather process.

This variable is set by the console variable and is used in the rendering pipeline to actually apply the scaling factor to the bilateral filter’s normal angle threshold.

Developers should be aware that modifying this variable directly in code would be overwritten by any console commands or config file settings. It’s best to use the console variable (r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale) to modify this value.

Best practices for this variable are the same as for the console variable, with the addition that any code that needs to read this value should do so from GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale rather than trying to access the console variable directly.

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

Scope: file

Source code excerpt:

float GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale"),
	GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale,
	TEXT("Scales the Normal angle threshold of the bilateral filter"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherBilateralFilterStrongBlurVarianceThreshold = .5f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale = .2f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.NormalAngleThresholdScale"),
	GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale,
	TEXT("Scales the Normal angle threshold of the bilateral filter"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRGatherBilateralFilterStrongBlurVarianceThreshold = .5f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterStrongBlurVarianceThreshold(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		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);

		FBilateralFilterCS::FPermutationDomain PermutationVector;