r.Lumen.ReSTIRGather

r.Lumen.ReSTIRGather

#Overview

name: r.Lumen.ReSTIRGather

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 is to control whether to use the prototype ReSTIR (Reservoir-based Spatio-Temporal Importance Resampling) Final Gather in Lumen, Unreal Engine 5’s global illumination system. This setting is part of the rendering system, specifically the Lumen lighting subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Lumen module within the Renderer. It’s specifically used in the ReSTIR gather implementation for Lumen.

The value of this variable is set through a console variable (CVarLumenReSTIRGather) defined in the LumenReSTIRGather.cpp file. It’s initialized with a default value of 0, meaning the feature is disabled by default.

The associated variable CVarLumenReSTIRGather interacts directly with r.Lumen.ReSTIRGather. They share the same value and purpose.

Developers must be aware of several things when using this variable:

  1. It’s disabled by default due to lower quality compared to LumenScreenProbeGather.
  2. It supports fewer features than the default gather method.
  3. It requires ray tracing to be enabled and supported by the hardware.
  4. It’s tagged with ECVF_Scalability and ECVF_RenderThreadSafe, indicating it affects performance scaling and can be safely changed on the render thread.

Best practices when using this variable include:

  1. Only enable it if you’re specifically testing or implementing the ReSTIR gather method.
  2. Be prepared for potential quality degradation compared to the default gather method.
  3. Ensure that ray tracing is enabled and supported on the target hardware before enabling this feature.
  4. Consider the performance implications, as this feature may impact rendering performance.

Regarding the associated variable CVarLumenReSTIRGather: This is the actual console variable that controls the r.Lumen.ReSTIRGather setting. It’s defined as an integer console variable, allowing for potential future expansion beyond a simple on/off toggle. The variable is used in the UseReSTIRGather function to determine if the ReSTIR gather should be used, in conjunction with other conditions such as ray tracing being enabled and platform support.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenReSTIRGather(
	TEXT("r.Lumen.ReSTIRGather"),
	0,
	TEXT("Whether to use the prototype ReSTIR Final Gather.  Disabled by default, as quality is currently much lower than LumenScreenProbeGather, and fewer features supported."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReSTIRDownsampleFactor = 2;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#endif

static TAutoConsoleVariable<int32> CVarLumenReSTIRGather(
	TEXT("r.Lumen.ReSTIRGather"),
	0,
	TEXT("Whether to use the prototype ReSTIR Final Gather.  Disabled by default, as quality is currently much lower than LumenScreenProbeGather, and fewer features supported."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
namespace    Lumen
function     bool UseReSTIRGather

Source code excerpt:

		return IsRayTracingEnabled()
			&& Lumen::UseHardwareRayTracing(ViewFamily)
			&& (CVarLumenReSTIRGather.GetValueOnAnyThread() != 0)
			&& DoesPlatformSupportLumenReSTIRGather(ShaderPlatform);
#else
		return false;
#endif
	}
} // namespace Lumen