r.Lumen.ReSTIRGather.SpatialResampling.NumPasses

r.Lumen.ReSTIRGather.SpatialResampling.NumPasses

#Overview

name: r.Lumen.ReSTIRGather.SpatialResampling.NumPasses

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

• type: Var
• help: The number of spatial resampling passes to do

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.SpatialResampling.NumPasses is to control the number of spatial resampling passes in the Lumen ReSTIR (Reservoir Spatio-Temporal Importance Resampling) gather process, which is part of Unreal Engine 5’s global illumination system.

This setting variable is primarily used by the rendering system, specifically within the Lumen subsystem. Based on the callsites, it’s clear that this variable is utilized in the LumenReSTIRGather module of the Renderer.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 2 and can be modified at runtime or through configuration files.

The associated variable GLumenReSTIRNumSpatialResamplingPasses directly interacts with r.Lumen.ReSTIRGather.SpatialResampling.NumPasses. They share the same value, with GLumenReSTIRNumSpatialResamplingPasses being the C++ variable that’s actually used in the code.

Developers should be aware that this variable affects the quality and performance of the global illumination. Increasing the number of passes can potentially improve the quality of the lighting but at the cost of increased computational overhead.

Best practices when using this variable include:

1. Balancing quality and performance based on the target hardware.
2. Testing different values to find the optimal setting for your specific scene.
3. Considering scalability options, as the variable is marked with ECVF_Scalability.

Regarding the associated variable GLumenReSTIRNumSpatialResamplingPasses:

The purpose of GLumenReSTIRNumSpatialResamplingPasses is to store and provide access to the number of spatial resampling passes within the C++ code of the Lumen ReSTIR gather process.

This variable is used directly in the rendering code, specifically in the FDeferredShadingSceneRenderer::RenderLumenReSTIRGather function. It determines how many iterations of spatial resampling will be performed.

The value of GLumenReSTIRNumSpatialResamplingPasses is set by the console variable system, mirroring the value of r.Lumen.ReSTIRGather.SpatialResampling.NumPasses.

It interacts with GLumenReSTIRSpatialResampling to determine whether spatial resampling should be performed at all. If GLumenReSTIRSpatialResampling is 0, no spatial resampling passes will occur regardless of the value of GLumenReSTIRNumSpatialResamplingPasses.

Developers should be aware that this variable is clamped between 0 and 16 in the actual rendering code, so values outside this range will be adjusted.

Best practices include:

1. Ensuring GLumenReSTIRSpatialResampling is properly set when adjusting this variable.
2. Monitoring performance impact when modifying this value, especially on lower-end hardware.
3. Considering the interaction with other Lumen settings for optimal results.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRNumSpatialResamplingPasses = 2;
FAutoConsoleVariableRef CVarLumenNumSpatialResamplingPasses(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.NumPasses"),
	GLumenReSTIRNumSpatialResamplingPasses,
	TEXT("The number of spatial resampling passes to do"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRNumSpatialSamples = 4;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRNumSpatialResamplingPasses = 2;
FAutoConsoleVariableRef CVarLumenNumSpatialResamplingPasses(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.NumPasses"),
	GLumenReSTIRNumSpatialResamplingPasses,
	TEXT("The number of spatial resampling passes to do"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRNumSpatialSamples = 4;
FAutoConsoleVariableRef CVarLumenReSTIRNumSpatialSamples(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

	}

	const int32 NumSpatialResamplingPasses = FMath::Clamp<int32>(GLumenReSTIRSpatialResampling > 0 ? GLumenReSTIRNumSpatialResamplingPasses : 0, 0, 16);

	for (int32 SpatialResamplingPassIndex = 0; SpatialResamplingPassIndex < NumSpatialResamplingPasses; SpatialResamplingPassIndex++)
	{
		FReservoirTextures SpatialReservoirTextures = AllocateReservoirTextures(GraphBuilder, ReservoirBufferSize);
		ReSTIRParameters.UAVs = CreateReservoirUAVs(GraphBuilder, SpatialReservoirTextures);