r.Lumen.Reflections.HairStrands.ScreenTrace

r.Lumen.Reflections.HairStrands.ScreenTrace

#Overview

name: r.Lumen.Reflections.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.Reflections.HairStrands.ScreenTrace is to control whether hair strands should be included in screen-space tracing for reflections in the Lumen global illumination system. This setting is specifically related to the rendering of hair and its interaction with reflections.

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

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files. By default, it is set to 1 (enabled).

The associated variable GLumenReflectionHairStrands_ScreenTrace directly interacts with this setting. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the performance and visual quality of reflections, particularly in scenes with hair or fur. Enabling this feature (set to 1) will include hair strands in the screen-space tracing for reflections, which can improve the accuracy of reflections on or near hair, but may also impact performance.

Best practices when using this variable include:

1. Enable it (set to 1) when hair or fur is an important visual element in your scene and accurate reflections are crucial.
2. Consider disabling it (set to 0) for performance-critical scenarios or on lower-end hardware.
3. Test the visual impact and performance implications in your specific use case, as the effects can vary depending on the amount and complexity of hair in your scene.

Regarding the associated variable GLumenReflectionHairStrands_ScreenTrace:

The purpose of GLumenReflectionHairStrands_ScreenTrace is to serve as the internal representation of the r.Lumen.Reflections.HairStrands.ScreenTrace setting within the C++ code.

This variable is used directly in the TraceReflections function to determine whether to include hair strands data in the reflection tracing process. It’s checked in conjunction with the presence of hair strands data for the current view.

The value of this variable is set by the FAutoConsoleVariableRef mechanism, which links it to the r.Lumen.Reflections.HairStrands.ScreenTrace console variable.

Developers should be aware that modifying GLumenReflectionHairStrands_ScreenTrace directly in code is not recommended. Instead, they should use the r.Lumen.Reflections.HairStrands.ScreenTrace console variable to control this setting.

Best practices for using GLumenReflectionHairStrands_ScreenTrace include:

1. Treat it as a read-only variable in most scenarios.
2. Use it for conditional logic in rendering code related to hair strands and reflections.
3. If you need to modify its value programmatically, use the appropriate Unreal Engine Console Variable API rather than changing it directly.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:63

Scope: file

Source code excerpt:

int32 GLumenReflectionHairStrands_ScreenTrace = 1;
FAutoConsoleVariableRef GVarLumenReflectionHairStrands_ScreenTrace(
	TEXT("r.Lumen.Reflections.HairStrands.ScreenTrace"),
	GLumenReflectionHairStrands_ScreenTrace,
	TEXT("Whether to trace against hair depth for hair casting shadow onto opaques."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionTraceCompactionGroupSizeInTiles = 16;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:61

Scope: file

Source code excerpt:

);

int32 GLumenReflectionHairStrands_ScreenTrace = 1;
FAutoConsoleVariableRef GVarLumenReflectionHairStrands_ScreenTrace(
	TEXT("r.Lumen.Reflections.HairStrands.ScreenTrace"),
	GLumenReflectionHairStrands_ScreenTrace,
	TEXT("Whether to trace against hair depth for hair casting shadow onto opaques."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenReflectionTraceCompactionGroupSizeInTiles = 16;
FAutoConsoleVariableRef GVarLumenReflectionTraceCompactionGroupSizeInTiles(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:913

Scope (from outer to inner):

file
function     void TraceReflections

Source code excerpt:

		PassParameters->IndirectTracingParameters = IndirectTracingParameters;

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