r.Lumen.ReSTIRGather.ResamplingAngleThreshold

r.Lumen.ReSTIRGather.ResamplingAngleThreshold

#Overview

name: r.Lumen.ReSTIRGather.ResamplingAngleThreshold

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.ResamplingAngleThreshold is to control the maximum angle allowed between two reservoirs during reservoir resampling in the Lumen ReSTIR (Reservoir Spatio-Temporal Importance Resampling) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically its ReSTIR implementation for efficient light sampling.

This setting variable is primarily used in the Lumen subsystem, which is part of Unreal Engine 5’s rendering module. Based on the callsites, it’s clear that this variable is utilized within the LumenReSTIRGather.cpp file, which handles the ReSTIR gather process for Lumen.

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

The associated variable GLumenReSTIRResamplingAngleThreshold directly interacts with r.Lumen.ReSTIRGather.ResamplingAngleThreshold. They share the same value, with GLumenReSTIRResamplingAngleThreshold being the C++ variable that stores the console variable’s value for use in the code.

Developers must be aware that this variable affects the quality and performance of the Lumen global illumination system. A larger angle threshold allows for more aggressive resampling, potentially improving performance at the cost of accuracy. Conversely, a smaller angle threshold can lead to more accurate results but may impact performance.

Best practices when using this variable include:

  1. Carefully balancing between performance and visual quality.
  2. Testing different values to find the optimal setting for your specific scene and performance requirements.
  3. Considering the impact on different hardware configurations, as more restrictive settings may affect performance on lower-end systems.

Regarding the associated variable GLumenReSTIRResamplingAngleThreshold:

The purpose of GLumenReSTIRResamplingAngleThreshold is to store the value of r.Lumen.ReSTIRGather.ResamplingAngleThreshold for use within the C++ code. It’s used directly in calculations, such as converting the angle to radians and calculating the cosine of the angle for efficient comparisons.

This variable is used in the Lumen ReSTIR gather process, specifically in the RenderLumenReSTIRGather function. It’s set automatically by the console variable system and doesn’t need to be manually modified by developers.

Developers should be aware that changes to r.Lumen.ReSTIRGather.ResamplingAngleThreshold will directly affect GLumenReSTIRResamplingAngleThreshold. When analyzing or debugging the Lumen ReSTIR gather process, this is the variable to look for in the code.

Best practices for GLumenReSTIRResamplingAngleThreshold include:

  1. Avoid modifying this variable directly in code; instead, use the console variable system to ensure consistency.
  2. When profiling or debugging, monitor this variable to understand the current resampling angle threshold 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:114

Scope: file

Source code excerpt:

float GLumenReSTIRResamplingAngleThreshold = 25.0f;
FAutoConsoleVariableRef CVarLumenReSTIRResamplingAngleThreshold(
	TEXT("r.Lumen.ReSTIRGather.ResamplingAngleThreshold"),
	GLumenReSTIRResamplingAngleThreshold,
	TEXT("Largest angle between two reservoirs that will be allowed during reservoir resampling, in degrees"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRResamplingDepthErrorThreshold = .01f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenReSTIRResamplingAngleThreshold = 25.0f;
FAutoConsoleVariableRef CVarLumenReSTIRResamplingAngleThreshold(
	TEXT("r.Lumen.ReSTIRGather.ResamplingAngleThreshold"),
	GLumenReSTIRResamplingAngleThreshold,
	TEXT("Largest angle between two reservoirs that will be allowed during reservoir resampling, in degrees"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenReSTIRResamplingDepthErrorThreshold = .01f;
FAutoConsoleVariableRef CVarLumenReSTIRSpatialResamplingDepthErrorThreshold(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:

	ReSTIRParameters.ReservoirBufferSize = ReservoirBufferSize;
	ReSTIRParameters.FixedJitterIndex = GLumenReSTIRGatherFixedJitterIndex;
	ReSTIRParameters.ResamplingNormalDotThreshold = FMath::Cos(GLumenReSTIRResamplingAngleThreshold * PI / 180.0f);
	ReSTIRParameters.ResamplingDepthErrorThreshold = GLumenReSTIRResamplingDepthErrorThreshold;

	ReSTIRParameters.Textures = AllocateReservoirTextures(GraphBuilder, ReservoirBufferSize);
	ReSTIRParameters.UAVs = CreateReservoirUAVs(GraphBuilder, ReSTIRParameters.Textures);
	
	FRDGTextureDesc DownsampledSceneDepthDesc(FRDGTextureDesc::Create2D(ReservoirBufferSize, PF_R32_FLOAT, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV));