r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace

r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace

#Overview

name: r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace

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

• type: Var
• help: Whether to trace against hair depth for hair casting shadow onto opaques.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace is to control whether to trace against hair depth for hair casting shadows onto opaque surfaces in the Lumen lighting system. This setting is part of Unreal Engine 5’s screen probe gathering process for hair strands rendering.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine 5’s rendering module. Specifically, it’s utilized in the screen probe tracing functionality for hair strands.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an integer (int32) and initialized to 0 by default. Developers can modify this value at runtime or in configuration files.

The associated variable GLumenScreenProbeGatherHairStrands_ScreenTrace directly interacts with this console variable. They share the same value and purpose.

Developers should be aware that:

1. This variable affects the rendering performance and visual quality of hair shadows on opaque surfaces.
2. It’s marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s safe to change at runtime and can be used for performance scaling.

Best practices when using this variable include:

1. Only enable it (set to 1) when hair strand shadows on opaque surfaces are necessary for visual quality.
2. Consider the performance impact, especially on lower-end hardware.
3. Use it in conjunction with other hair rendering settings for optimal results.

Regarding the associated variable GLumenScreenProbeGatherHairStrands_ScreenTrace:

1. It’s used directly in the TraceScreenProbes function to determine if hair strands data should be processed.
2. The check GLumenScreenProbeGatherHairStrands_ScreenTrace > 0 suggests that any positive value will enable the feature.
3. It’s used in combination with HairStrands::HasViewHairStrandsData(View) to ensure both that the feature is enabled and that hair strand data is available.

Developers should use this variable in tandem with other hair rendering settings and be mindful of its performance implications, especially in scenes with complex hair rendering requirements.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherHairStrands_ScreenTrace = 0;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHairStrands_ScreenTrace(
	TEXT("r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace"),
	GLumenScreenProbeGatherHairStrands_ScreenTrace,
	TEXT("Whether to trace against hair depth for hair casting shadow onto opaques."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherScreenTracesMinimumOccupancy = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherHairStrands_ScreenTrace = 0;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHairStrands_ScreenTrace(
	TEXT("r.Lumen.ScreenProbeGather.HairStrands.ScreenTrace"),
	GLumenScreenProbeGatherHairStrands_ScreenTrace,
	TEXT("Whether to trace against hair depth for hair casting shadow onto opaques."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherScreenTracesMinimumOccupancy = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeGatherScreenTraceMinimumOccupancy(

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->RadianceCacheParameters = RadianceCacheParameters;

			const bool bHasHairStrands = HairStrands::HasViewHairStrandsData(View) && GLumenScreenProbeGatherHairStrands_ScreenTrace > 0;
			if (bHasHairStrands)
			{
				PassParameters->HairStrands = HairStrands::BindHairStrandsViewUniformParameters(View);
			}

			const bool bTerminateOnLowOccupancy = GLumenScreenProbeGatherScreenTracesMinimumOccupancy > 0