r.Lumen.ScreenProbeGather.ScreenTraces

r.Lumen.ScreenProbeGather.ScreenTraces

#Overview

name: r.Lumen.ScreenProbeGather.ScreenTraces

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

• type: Var
• help: Whether to trace against the screen before falling back to other tracing methods.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces is to control whether the Lumen global illumination system should trace against the screen before falling back to other tracing methods during the screen probe gathering process. This setting is part of Unreal Engine 5’s rendering system, specifically the Lumen global illumination feature.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenScreenProbeTracing.cpp file, which is part of the Renderer module.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime using console commands or through project settings.

The associated variable GLumenScreenProbeGatherScreenTraces directly interacts with r.Lumen.ScreenProbeGather.ScreenTraces. They share the same value, with GLumenScreenProbeGatherScreenTraces being the actual variable used in the C++ code.

Developers should be aware that this variable affects the performance and quality of Lumen’s global illumination. Enabling screen tracing (value set to 1) may improve the accuracy of indirect lighting but could also impact performance. It’s also important to note that this setting is marked with ECVF_Scalability, indicating it can be adjusted for different performance targets.

Best practices when using this variable include:

1. Testing different values to find the optimal balance between visual quality and performance for your specific project.
2. Considering the target hardware when setting this value, as lower-end devices might benefit from disabling screen tracing.
3. Using it in conjunction with other Lumen settings for fine-tuning the global illumination system.

Regarding the associated variable GLumenScreenProbeGatherScreenTraces: The purpose of GLumenScreenProbeGatherScreenTraces is to serve as the actual C++ variable that controls the screen tracing behavior in the Lumen system. It’s directly tied to the console variable r.Lumen.ScreenProbeGather.ScreenTraces.

This variable is used within the Lumen subsystem of the rendering module, specifically in the screen probe tracing logic. Its value is set by the console variable system and is used to determine whether screen tracing should be performed during the screen probe gathering process.

The value of GLumenScreenProbeGatherScreenTraces is set by the console variable system when r.Lumen.ScreenProbeGather.ScreenTraces is modified. It interacts directly with the rendering code, influencing the behavior of the TraceScreenProbes function.

Developers should be aware that modifying GLumenScreenProbeGatherScreenTraces directly in code is not recommended. Instead, they should use the console variable r.Lumen.ScreenProbeGather.ScreenTraces to control this setting.

Best practices for GLumenScreenProbeGatherScreenTraces include:

1. Avoid modifying it directly in code; use the console variable instead.
2. When reading its value in code, be aware that it can change at runtime based on user settings or performance scaling.
3. Consider the implications of its value when implementing or modifying screen probe tracing logic in the Lumen system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:17

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherScreenTraces = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherScreenTraces(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces"),
	GLumenScreenProbeGatherScreenTraces,
	TEXT("Whether to trace against the screen before falling back to other tracing methods."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTraces = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:15

Scope: file

Source code excerpt:

#include "HairStrands/HairStrandsData.h"

int32 GLumenScreenProbeGatherScreenTraces = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherScreenTraces(
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces"),
	GLumenScreenProbeGatherScreenTraces,
	TEXT("Whether to trace against the screen before falling back to other tracing methods."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTraces = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTraces(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeTracing.cpp:675

Scope (from outer to inner):

file
function     void TraceScreenProbes

Source code excerpt:

	extern int32 GLumenVisualizeIndirectDiffuse;
	const bool bTraceScreen = View.PrevViewInfo.ScreenSpaceRayTracingInput.IsValid()
		&& GLumenScreenProbeGatherScreenTraces != 0
		&& GLumenVisualizeIndirectDiffuse == 0
		&& View.Family->EngineShowFlags.LumenScreenTraces
		&& View.FinalPostProcessSettings.LumenFinalGatherScreenTraces;

	if (bTraceScreen)
	{