r.Lumen.ReSTIRGather.Upsample.NumSamples

r.Lumen.ReSTIRGather.Upsample.NumSamples

#Overview

name: r.Lumen.ReSTIRGather.Upsample.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.Upsample.NumSamples is to control the number of reservoir samples taken during the upsampling process in Lumen’s ReSTIR (Resampled Importance Sampling for Real-Time Ray Tracing) gather step. This setting is specifically used for the rendering system, particularly in the Lumen global illumination solution.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenReSTIRGather.cpp file, which is part of the Renderer’s private implementation.

The value of this variable is set through the Unreal Engine’s console variable system. It’s initialized with a default value of 16 and can be modified at runtime using the console command system.

The associated variable GLumenReSTIRUpsampleNumSamples directly interacts with this setting. They share the same value, with GLumenReSTIRUpsampleNumSamples being the actual variable used in the C++ code to store and access the setting’s value.

Developers must be aware that this setting is only used when the r.Lumen.ReSTIRGather.Upsample.Method is set to “Spiral Pattern”. This dependency on another setting is crucial for understanding when this variable will have an effect on the rendering process.

Best practices when using this variable include:

  1. Balancing quality and performance: Higher values will provide better quality but at the cost of performance.
  2. Testing different values to find the optimal balance for your specific scene and target hardware.
  3. Considering the interaction with other Lumen settings, particularly r.Lumen.ReSTIRGather.Upsample.Method.
  4. Using the console variable system to experiment with different values during development and debugging.

Regarding the associated variable GLumenReSTIRUpsampleNumSamples:

The purpose of GLumenReSTIRUpsampleNumSamples is to store and provide access to the number of reservoir samples for upsampling within the C++ code of the Lumen ReSTIR gather process.

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

The value of GLumenReSTIRUpsampleNumSamples is set by the console variable system through the r.Lumen.ReSTIRGather.Upsample.NumSamples setting.

It interacts directly with the r.Lumen.ReSTIRGather.Upsample.NumSamples console variable and is used in the upsampling and integration compute shader setup.

Developers should be aware that modifying GLumenReSTIRUpsampleNumSamples directly in code is not recommended, as its value is controlled by the console variable system.

Best practices for using GLumenReSTIRUpsampleNumSamples include:

  1. Accessing its value rather than modifying it directly in C++ code.
  2. Using it in conjunction with other Lumen ReSTIR gather parameters for consistent results.
  3. Considering its performance impact when used in frequently executed code paths.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRUpsampleNumSamples = 16;
FAutoConsoleVariableRef CVarLumenReSTIRNumSamples(
	TEXT("r.Lumen.ReSTIRGather.Upsample.NumSamples"),
	GLumenReSTIRUpsampleNumSamples,
	TEXT("Number of reservoir samples to take while upsampling. Only used when r.Lumen.ReSTIRGather.Upsample.Method is set to Spiral Pattern."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherTemporalFilter = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRUpsampleNumSamples = 16;
FAutoConsoleVariableRef CVarLumenReSTIRNumSamples(
	TEXT("r.Lumen.ReSTIRGather.Upsample.NumSamples"),
	GLumenReSTIRUpsampleNumSamples,
	TEXT("Number of reservoir samples to take while upsampling. Only used when r.Lumen.ReSTIRGather.Upsample.Method is set to Spiral Pattern."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherTemporalFilter = 1;
FAutoConsoleVariableRef CVarLumenReSTIRGatherTemporalFilter(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

		LumenReflections::SetupCompositeParameters(View, PassParameters->ReflectionsCompositeParameters);
		PassParameters->UpsampleKernelSize = GLumenReSTIRUpsampleKernelSize;
		PassParameters->UpsampleNumSamples = GLumenReSTIRUpsampleNumSamples;

		FUpsampleAndIntegrateCS::FPermutationDomain PermutationVector;
		PermutationVector.Set< FUpsampleAndIntegrateCS::FUpsampleMethod >((EReSTIRUpsampleMethod)GLumenReSTIRUpsampleMethod);
		PermutationVector.Set< FUpsampleAndIntegrateCS::FBilateralFilter >(bBilateralFilter);
		auto ComputeShader = View.ShaderMap->GetShader<FUpsampleAndIntegrateCS>(PermutationVector);