r.Lumen.ScreenProbeGather.ReferenceMode

r.Lumen.ScreenProbeGather.ReferenceMode

#Overview

name: r.Lumen.ScreenProbeGather.ReferenceMode

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ReferenceMode is to enable a reference mode for Lumen’s screen probe gathering process in the rendering system. This setting is part of Unreal Engine 5’s Lumen global illumination system.

The Lumen rendering subsystem relies on this setting variable, specifically within the screen probe gathering module. It is primarily used in the LumenScreenProbeGather namespace.

The value of this variable is set through the Unreal Engine console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime using console commands or through project settings.

This variable interacts closely with GLumenScreenProbeGatherReferenceMode, which is the associated C++ variable that stores the actual value. They share the same value and are used interchangeably in the code.

Developers must be aware that when this reference mode is enabled, it significantly changes the behavior of the screen probe gathering process. It forces the system to trace 1024 uniform rays per probe without any filtering, Importance Sampling, or Radiance Caching. This is likely intended for testing or reference comparisons.

Best practices when using this variable include:

  1. Use it primarily for debugging or quality comparisons, not in production builds.
  2. Be aware of the performance impact, as tracing 1024 rays per probe is computationally expensive.
  3. Understand that it disables several optimization techniques, which may affect visual quality and performance in ways that don’t represent typical usage.

Regarding the associated variable GLumenScreenProbeGatherReferenceMode:

The purpose of GLumenScreenProbeGatherReferenceMode is to store the actual value of the reference mode setting within the C++ code.

This variable is used across multiple functions in the LumenScreenProbeGather namespace to modify behavior based on whether the reference mode is active. It affects various aspects of the screen probe gathering process, including:

Developers should be aware that this variable has a significant impact on the entire screen probe gathering pipeline. When it’s enabled (non-zero), it overrides many other settings and optimizations.

Best practices for using GLumenScreenProbeGatherReferenceMode include:

  1. Use it in conjunction with performance profiling tools to understand its impact.
  2. Be cautious about enabling it in shipping builds, as it’s primarily intended for testing and comparison.
  3. When debugging visual artifacts or quality issues, consider toggling this setting to isolate whether the issue is related to the optimizations that are disabled in reference mode.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:52

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherReferenceMode = 0;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherReferenceMode(
	TEXT("r.Lumen.ScreenProbeGather.ReferenceMode"),
	GLumenScreenProbeGatherReferenceMode,
	TEXT("When enabled, traces 1024 uniform rays per probe with no filtering, Importance Sampling or Radiance Caching."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeTracingOctahedronResolution = 8;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:50

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherReferenceMode = 0;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherReferenceMode(
	TEXT("r.Lumen.ScreenProbeGather.ReferenceMode"),
	GLumenScreenProbeGatherReferenceMode,
	TEXT("When enabled, traces 1024 uniform rays per probe with no filtering, Importance Sampling or Radiance Caching."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeTracingOctahedronResolution = 8;
FAutoConsoleVariableRef GVarLumenScreenProbeTracingOctahedronResolution(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:335

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     int32 GetTracingOctahedronResolution

Source code excerpt:

		const int32 TracingOctahedronResolution = FMath::Clamp(FMath::RoundToInt(SqrtQuality * GLumenScreenProbeTracingOctahedronResolution), 4, 16);
		ensureMsgf(IsProbeTracingResolutionSupportedForImportanceSampling(TracingOctahedronResolution), TEXT("Tracing resolution %u requested that is not supported by importance sampling"), TracingOctahedronResolution);
		return GLumenScreenProbeGatherReferenceMode ? 32 : TracingOctahedronResolution;
	}

	int32 GetGatherOctahedronResolution(int32 TracingOctahedronResolution)
	{
		if (GLumenScreenProbeGatherReferenceMode)
		{
			return 8;
		}

		if (GLumenScreenProbeGatherOctahedronResolutionScale >= 1.0f)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:359

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     int32 GetScreenDownsampleFactor

Source code excerpt:

	int32 GetScreenDownsampleFactor(const FViewInfo& View)
	{
		if (GLumenScreenProbeGatherReferenceMode)
		{
			return 16;
		}

		return FMath::Clamp(GLumenScreenProbeDownsampleFactor / (View.FinalPostProcessSettings.LumenFinalGatherQuality >= 6.0f ? 2 : 1), 4, 64);
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:369

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseShortRangeAmbientOcclusion

Source code excerpt:

	bool UseShortRangeAmbientOcclusion(const FEngineShowFlags& ShowFlags)
	{
		return GLumenScreenProbeGatherReferenceMode ? false : (GLumenShortRangeAmbientOcclusion != 0 && ShowFlags.LumenShortRangeAmbientOcclusion);
	}

	bool ApplyShortRangeAODuringIntegration()
	{
		return GLumenShortRangeAOApplyDuringIntegration != 0;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:379

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseProbeSpatialFilter

Source code excerpt:

	bool UseProbeSpatialFilter()
	{
		return GLumenScreenProbeGatherReferenceMode ? false : GLumenScreenProbeSpatialFilter != 0;
	}

	bool UseProbeTemporalFilter()
	{
		return GLumenScreenProbeGatherReferenceMode ? false : GLumenScreenProbeTemporalFilterProbes != 0;
	}

	bool UseRadianceCache(const FViewInfo& View)
	{
		return GLumenScreenProbeGatherReferenceMode ? false : GLumenRadianceCache != 0;
	}

	int32 GetDiffuseIntegralMethod()
	{
		return GLumenScreenProbeGatherReferenceMode ? 2 : GLumenScreenProbeDiffuseIntegralMethod;
	}

	EScreenProbeIrradianceFormat GetScreenProbeIrradianceFormat(const FEngineShowFlags& ShowFlags)
	{
		const bool bApplyShortRangeAO = UseShortRangeAmbientOcclusion(ShowFlags) && ApplyShortRangeAODuringIntegration();
		if (bApplyShortRangeAO)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeImportanceSampling.cpp:70

Scope: file

Source code excerpt:

	);

extern int32 GLumenScreenProbeGatherReferenceMode;

class FScreenProbeComputeBRDFProbabilityDensityFunctionCS : public FGlobalShader
{
	DECLARE_GLOBAL_SHADER(FScreenProbeComputeBRDFProbabilityDensityFunctionCS)
	SHADER_USE_PARAMETER_STRUCT(FScreenProbeComputeBRDFProbabilityDensityFunctionCS, FGlobalShader)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeImportanceSampling.cpp:225

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseImportanceSampling

Source code excerpt:

	bool UseImportanceSampling(const FViewInfo& View)
	{
		if (GLumenScreenProbeGatherReferenceMode)
		{
			return false;
		}

		// Shader permutations only created for these resolutions
		const int32 TracingResolution = GetTracingOctahedronResolution(View);