r.Lumen.ReSTIRGather.Upsample.Method

r.Lumen.ReSTIRGather.Upsample.Method

#Overview

name: r.Lumen.ReSTIRGather.Upsample.Method

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.Method is to control the upsampling method used when calculating full resolution irradiance from downsampled reservoir radiance in the Lumen ReSTIR (Reservoir Spatio-Temporal Importance Resampling) gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system.

This setting variable is primarily used in the Renderer subsystem, specifically within the Lumen module. It’s utilized in the LumenReSTIRGather.cpp file, which is responsible for handling the ReSTIR gathering process in Lumen.

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

The associated variable GLumenReSTIRUpsampleMethod directly interacts with r.Lumen.ReSTIRGather.Upsample.Method. They share the same value, with GLumenReSTIRUpsampleMethod being the actual integer variable used in the C++ code.

Developers must be aware that this variable affects the quality and performance of the Lumen global illumination system. The chosen method can impact both the visual results and the rendering performance.

Best practices when using this variable include:

  1. Understanding the trade-offs between quality and performance for each method.
  2. Testing different values in various scenarios to find the best balance for your specific game or application.
  3. Considering scalability options, as this variable is marked with ECVF_Scalability flag.

Regarding GLumenReSTIRUpsampleMethod: This is the actual integer variable used in the C++ code to store the upsampling method. It’s directly linked to the r.Lumen.ReSTIRGather.Upsample.Method console variable.

The variable is used to set the upsampling method in the FUpsampleAndIntegrateCS::FPermutationDomain, which likely controls the shader permutations for the upsampling and integration compute shader.

Developers should be aware that changing GLumenReSTIRUpsampleMethod will directly affect the shader permutations and the rendering pipeline. It’s important to ensure that any modifications to this variable are properly synchronized with the rest of the Lumen system.

Best practices for GLumenReSTIRUpsampleMethod include:

  1. Avoid directly modifying this variable in C++ code unless absolutely necessary.
  2. Use the console variable r.Lumen.ReSTIRGather.Upsample.Method to change the value instead.
  3. When debugging or profiling, consider using the passthrough option (value 2) to isolate the effects of the upsampling method.

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

Scope: file

Source code excerpt:

int32 GLumenReSTIRUpsampleMethod = 1;
FAutoConsoleVariableRef CVarLumenReSTIRUpsampleMethod(
	TEXT("r.Lumen.ReSTIRGather.Upsample.Method"),
	GLumenReSTIRUpsampleMethod,
	TEXT("Upsample method, when calculating full resolution irradiance from downsampled reservoir radiance\n")
	TEXT("0 - Jittered bilinear sample, when jittered position lies in the same plane, and fallback to unjittered when all samples fail\n")
	TEXT("1 - Spiral sample pattern\n")
	TEXT("2 - Passthrough for debugging.  Also effectively disables the bilateral filter as variance is not computed."),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenReSTIRUpsampleMethod = 1;
FAutoConsoleVariableRef CVarLumenReSTIRUpsampleMethod(
	TEXT("r.Lumen.ReSTIRGather.Upsample.Method"),
	GLumenReSTIRUpsampleMethod,
	TEXT("Upsample method, when calculating full resolution irradiance from downsampled reservoir radiance\n")
	TEXT("0 - Jittered bilinear sample, when jittered position lies in the same plane, and fallback to unjittered when all samples fail\n")
	TEXT("1 - Spiral sample pattern\n")
	TEXT("2 - Passthrough for debugging.  Also effectively disables the bilateral filter as variance is not computed."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenReSTIRGather

Source code excerpt:


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

		FComputeShaderUtils::AddPass(
			GraphBuilder,
			RDG_EVENT_NAME("IntegrateAndUpsample Type=%u %ux%u", GLumenReSTIRUpsampleMethod, View.ViewRect.Width(), View.ViewRect.Height()),
			ERDGPassFlags::Compute,
			ComputeShader,
			PassParameters,
			FComputeShaderUtils::GetGroupCount(View.ViewRect.Size(), FUpsampleAndIntegrateCS::GetGroupSize()));
	}