r.Lumen.ReSTIRGather.DownsampleFactor

r.Lumen.ReSTIRGather.DownsampleFactor

#Overview

name: r.Lumen.ReSTIRGather.DownsampleFactor

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ReSTIRGather.DownsampleFactor is to control the downsampling factor for ray tracing, reservoir creation, and resampling in the Lumen ReSTIR (Reservoir-based Spatiotemporal Importance Resampling) gather process. This setting is primarily used in the rendering system, specifically for the Lumen global illumination feature in Unreal Engine 5.

This setting variable is relied upon by the Lumen subsystem within the Renderer module of Unreal Engine 5. It is particularly used in the ReSTIR gather process, which is part of the Lumen global illumination implementation.

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

The associated variable GLumenReSTIRDownsampleFactor directly interacts with this setting. It shares the same value and is used in the C++ code to apply the downsampling factor.

Developers must be aware that this variable significantly impacts performance and quality. A higher downsample factor will improve performance but may reduce image quality, while a lower factor will increase quality at the cost of performance.

Best practices for using this variable include:

  1. Adjusting it based on the target hardware capabilities and performance requirements.
  2. Testing different values to find the optimal balance between performance and visual quality for your specific use case.
  3. Considering dynamic adjustment based on the scene complexity or performance metrics.

Regarding the associated variable GLumenReSTIRDownsampleFactor:

The purpose of GLumenReSTIRDownsampleFactor is to store and provide access to the downsampling factor value within the C++ code of the Lumen ReSTIR gather system.

It is used directly in the Lumen ReSTIR gather implementation within the Renderer module.

The value of this variable is set by the console variable system, mirroring the value of r.Lumen.ReSTIRGather.DownsampleFactor.

This variable interacts closely with the console variable r.Lumen.ReSTIRGather.DownsampleFactor, effectively serving as its in-code representation.

Developers should be aware that modifications to this variable will directly affect the ReSTIR gather process’s performance and quality.

Best practices for using this variable include:

  1. Avoiding direct modification of this variable in code, instead using the console variable system to ensure consistency.
  2. Using the GetScreenDownsampleFactor function to access the value, which applies additional clamping for safety.
  3. Being mindful of its impact on performance when used in performance-critical 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:34

Scope: file

Source code excerpt:

int32 GLumenReSTIRDownsampleFactor = 2;
FAutoConsoleVariableRef CVarLumenReSTIRDownsampleFactor(
	TEXT("r.Lumen.ReSTIRGather.DownsampleFactor"),
	GLumenReSTIRDownsampleFactor,
	TEXT("Downsample factor from the main viewport to trace rays, create and resample reservoirs at.  This is the main performance control for the tracing / resampling part of the algorithm."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherFixedJitterIndex = -1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRDownsampleFactor = 2;
FAutoConsoleVariableRef CVarLumenReSTIRDownsampleFactor(
	TEXT("r.Lumen.ReSTIRGather.DownsampleFactor"),
	GLumenReSTIRDownsampleFactor,
	TEXT("Downsample factor from the main viewport to trace rays, create and resample reservoirs at.  This is the main performance control for the tracing / resampling part of the algorithm."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRGatherFixedJitterIndex = -1;
FAutoConsoleVariableRef CVarLumenReSTIRGatherFixedJitterIndex(

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

Scope (from outer to inner):

file
namespace    LumenReSTIRGather
function     int32 GetScreenDownsampleFactor

Source code excerpt:

	int32 GetScreenDownsampleFactor(const FViewInfo& View)
	{
		return FMath::Clamp(GLumenReSTIRDownsampleFactor, 1, 8);
	}
}

bool DoesPlatformSupportLumenReSTIRGather(EShaderPlatform Platform)
{
	// Prototype feature, don't want to spend time fixing other platforms until it matters

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:


	FReSTIRParameters ReSTIRParameters;
	ReSTIRParameters.ReservoirDownsampleFactor = GLumenReSTIRDownsampleFactor;

	const FIntPoint ViewSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), (int32)ReSTIRParameters.ReservoirDownsampleFactor);
	FIntPoint ReservoirBufferSize = FIntPoint::DivideAndRoundUp(SceneTextures.Config.Extent, (int32)ReSTIRParameters.ReservoirDownsampleFactor);

	ReSTIRParameters.ReservoirViewSize = ViewSize;
	ReSTIRParameters.ReservoirBufferSize = ReservoirBufferSize;