r.Lumen.ReSTIRGather.SpatialResampling.NumSamples

r.Lumen.ReSTIRGather.SpatialResampling.NumSamples

#Overview

name: r.Lumen.ReSTIRGather.SpatialResampling.NumSamples

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.SpatialResampling.NumSamples is to control the number of spatial samples used in each resampling pass of the Lumen ReSTIR (Reservoir Spatiotemporal Importance Resampling) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the ReSTIR algorithm used for efficient light sampling.

This setting variable is primarily used by the Lumen subsystem within the rendering module of Unreal Engine 5. It’s specifically utilized in the ReSTIR gather process, which is a part of the global illumination calculations.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

The associated variable GLumenReSTIRNumSpatialSamples directly interacts with this setting. They share the same value, with GLumenReSTIRNumSpatialSamples being the actual integer variable used in the code.

Developers should be aware that this variable affects the quality and performance of the Lumen global illumination system. Increasing the number of samples will likely improve the quality of the lighting but at the cost of performance.

Best practices when using this variable include:

  1. Balancing quality and performance based on the target hardware.
  2. Adjusting it in conjunction with other Lumen settings for optimal results.
  3. Testing different values to find the sweet spot for your specific scene.

Regarding the associated variable GLumenReSTIRNumSpatialSamples:

The purpose of GLumenReSTIRNumSpatialSamples is to store the actual value of the number of spatial samples used in the Lumen ReSTIR gather process. It’s an internal variable that directly affects the rendering calculations.

This variable is used within the Lumen subsystem of the rendering module, specifically in the ReSTIR gather process.

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

It interacts directly with the console variable and is used in the actual rendering calculations, as seen in the FSpatialResamplingCS shader setup.

Developers should be aware that modifying this variable directly in code (rather than through the console variable system) could lead to inconsistencies.

Best practices include:

  1. Avoiding direct modification of GLumenReSTIRNumSpatialSamples in code.
  2. Using the console variable system to adjust this value for consistency and easier debugging.
  3. Considering the performance implications when adjusting this value, especially on lower-end hardware.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRNumSpatialSamples = 4;
FAutoConsoleVariableRef CVarLumenReSTIRNumSpatialSamples(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.NumSamples"),
	GLumenReSTIRNumSpatialSamples,
	TEXT("The number of spatial samples for each resampling pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRSpatialResamplingKernelRadius = .05f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRNumSpatialSamples = 4;
FAutoConsoleVariableRef CVarLumenReSTIRNumSpatialSamples(
	TEXT("r.Lumen.ReSTIRGather.SpatialResampling.NumSamples"),
	GLumenReSTIRNumSpatialSamples,
	TEXT("The number of spatial samples for each resampling pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRSpatialResamplingKernelRadius = .05f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingKernelRadius(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		PassParameters->SpatialResamplingKernelRadius = GLumenReSTIRSpatialResamplingKernelRadius;
		PassParameters->SpatialResamplingOcclusionScreenTraceDistance = GLumenReSTIRSpatialResamplingOcclusionScreenTraceDistance;
		PassParameters->NumSpatialSamples = GLumenReSTIRNumSpatialSamples;
		PassParameters->SpatialResamplingPassIndex = SpatialResamplingPassIndex;

		FSpatialResamplingCS::FPermutationDomain PermutationVector;
		auto ComputeShader = View.ShaderMap->GetShader<FSpatialResamplingCS>(PermutationVector);

		FComputeShaderUtils::AddPass(