r.Lumen.ScreenProbeGather

r.Lumen.ScreenProbeGather

#Overview

name: r.Lumen.ScreenProbeGather

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

• type: Var
• help: Whether to use the Screen Probe Final Gather

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather is to control whether to use the Screen Probe Final Gather in Lumen’s global illumination system. This setting is part of Unreal Engine 5’s Lumen lighting system, specifically the screen probe gathering component.

Lumen’s Screen Probe Gather is a technique used in the rendering system to collect and process lighting information for global illumination. It’s primarily used in the Renderer module of Unreal Engine.

The value of this variable is set through the engine’s console variable system, allowing it to be changed at runtime. It’s defined as an integer, with a default value of 1 (enabled).

The associated variable GLumenScreenProbeGather interacts directly with r.Lumen.ScreenProbeGather. They share the same value, with GLumenScreenProbeGather being used in the C++ code to check if the feature is enabled.

Developers should be aware that disabling this feature (setting it to 0) will result in a fallback behavior:

1. The diffuse indirect lighting will be set to black.
2. A blank texture will be created for rough specular indirect lighting.

Best practices when using this variable include:

1. Keep it enabled (1) for higher quality global illumination.
2. Consider disabling it (0) for performance optimization on lower-end hardware.
3. Test your scenes with both settings to ensure they look acceptable in both cases.

Regarding GLumenScreenProbeGather:

This is an internal variable used to quickly check the state of the Screen Probe Gather feature in the C++ code. It directly reflects the value of r.Lumen.ScreenProbeGather.

Developers should use this variable for conditional logic in the rendering pipeline related to Screen Probe Gather. For example, the code snippet shows that when GLumenScreenProbeGather is false, a simplified lighting setup is used instead of the full Screen Probe Gather process.

When working with this variable, developers should:

1. Treat it as read-only within the rendering code.
2. Use it for performance-critical checks where the full console variable system might be too slow.
3. Be aware that changes to r.Lumen.ScreenProbeGather will be reflected in GLumenScreenProbeGather.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGather = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGather(
	TEXT("r.Lumen.ScreenProbeGather"),
	GLumenScreenProbeGather,
	TEXT("Whether to use the Screen Probe Final Gather"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

FAutoConsoleVariableRef CVarLumenScreenProbeGatherTraceMeshSDFs(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

extern FLumenGatherCvarState GLumenGatherCvars;

int32 GLumenScreenProbeGather = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGather(
	TEXT("r.Lumen.ScreenProbeGather"),
	GLumenScreenProbeGather,
	TEXT("Whether to use the Screen Probe Final Gather"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

FAutoConsoleVariableRef CVarLumenScreenProbeGatherTraceMeshSDFs(
	TEXT("r.Lumen.ScreenProbeGather.TraceMeshSDFs"),

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

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseRejectBasedOnNormal

Source code excerpt:

	bool UseRejectBasedOnNormal()
	{
		return GLumenScreenProbeGather != 0
			&& CVarLumenScreenProbeTemporalRejectBasedOnNormal.GetValueOnRenderThread() != 0;
	}
}

int32 GRadianceCacheNumClipmaps = 4;
FAutoConsoleVariableRef CVarRadianceCacheNumClipmaps(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	}

	if (!GLumenScreenProbeGather)
	{
		FSSDSignalTextures ScreenSpaceDenoiserInputs;
		ScreenSpaceDenoiserInputs.Textures[0] = SystemTextures.Black;
		FRDGTextureDesc RoughSpecularIndirectDesc = FRDGTextureDesc::Create2D(SceneTextures.Config.Extent, PF_FloatRGB, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV);
		ScreenSpaceDenoiserInputs.Textures[1] = GraphBuilder.CreateTexture(RoughSpecularIndirectDesc, TEXT("Lumen.ScreenProbeGather.RoughSpecularIndirect"));
		AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(FRDGTextureUAVDesc(ScreenSpaceDenoiserInputs.Textures[1])), FLinearColor::Black);