r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius

r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius

#Overview

name: r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius

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

• type: Var
• help: Spatial kernel radius, as a fraction of the viewport size

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius is to control the spatial kernel radius for the bilateral filter used in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine’s rendering module. Specifically, it’s utilized in the ReSTIR gather process, which is a technique used to improve the quality and efficiency of real-time global illumination.

The value of this variable is set initially to 0.002f, which represents 0.2% of the viewport size. It can be modified at runtime through the console variable system, as indicated by the FAutoConsoleVariableRef declaration.

The associated variable GLumenReSTIRGatherBilateralFilterSpatialKernelRadius directly interacts with this console variable. They share the same value, with the console variable providing a way to modify the value at runtime.

Developers must be aware that this variable affects the quality and performance of the Lumen global illumination system. A larger radius will result in a smoother, more blurred result but may introduce more artifacts and increase computational cost. Conversely, a smaller radius will preserve more detail but may result in a noisier image.

Best practices when using this variable include:

1. Adjusting it in small increments to find the optimal balance between image quality and performance.
2. Testing the impact across various scene types and lighting conditions.
3. Considering the target hardware when setting this value, as higher-end systems may be able to handle larger radii.

Regarding the associated variable GLumenReSTIRGatherBilateralFilterSpatialKernelRadius:

• Its purpose is to store the actual value used in the rendering calculations.
• It’s used directly in the RenderLumenReSTIRGather function to set up the pass parameters for the ReSTIR gather process.
• The value is set by the console variable system and can be modified at runtime.
• Developers should be aware that changes to this variable will immediately affect the rendering process.
• Best practices include monitoring this variable’s value when debugging or optimizing the Lumen system, as it directly reflects the current spatial kernel radius being used in calculations.

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

Scope: file

Source code excerpt:

float GLumenReSTIRGatherBilateralFilterSpatialKernelRadius = .002f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterSpatialKernelRadius(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius"),
	GLumenReSTIRGatherBilateralFilterSpatialKernelRadius,
	TEXT("Spatial kernel radius, as a fraction of the viewport size"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherBilateralFilterNumSamples = 8;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRGatherBilateralFilterSpatialKernelRadius = .002f;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterSpatialKernelRadius(
	TEXT("r.Lumen.ReSTIRGather.BilateralFilter.SpatialKernelRadius"),
	GLumenReSTIRGatherBilateralFilterSpatialKernelRadius,
	TEXT("Spatial kernel radius, as a fraction of the viewport size"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherBilateralFilterNumSamples = 8;
FAutoConsoleVariableRef CVarLumenReSTIRGatherBilateralFilterNumSamples(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		PassParameters->RoughSpecularIndirect = RoughSpecularIndirect;
		PassParameters->ResolveVariance = ResolveVariance;
		PassParameters->BilateralFilterSpatialKernelRadius = GLumenReSTIRGatherBilateralFilterSpatialKernelRadius;
		PassParameters->BilateralFilterNumSamples = GLumenReSTIRGatherBilateralFilterNumSamples;
		PassParameters->BilateralFilterDepthWeightScale = GLumenReSTIRGatherBilateralFilterDepthWeightScale;
		PassParameters->BilateralFilterNormalAngleThresholdScale = GLumenReSTIRGatherBilateralFilterNormalAngleThresholdScale;
		PassParameters->BilateralFilterStrongBlurVarianceThreshold = GLumenReSTIRGatherBilateralFilterStrongBlurVarianceThreshold;
		PassParameters->View = View.ViewUniformBuffer;
		PassParameters->SceneTexturesStruct = SceneTextures.UniformBuffer;