r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits

r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits

#Overview

name: r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits is to control whether screen traces in Lumen’s Screen Probe Gather system should skip hits on Subsurface and TwoSided Foliage shading models. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically within the screen probe tracing component.

This variable is primarily used in the Lumen rendering subsystem, particularly in the Screen Probe Gathering process. It’s referenced 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 (true), meaning it will skip foliage hits by default.

The associated C++ variable GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits directly interacts with this console variable. It’s used in the screen tracing logic to determine whether to skip foliage hits.

Developers should be aware that this setting can be used to work around aliasing issues from high-frequency grass geometry. When enabled, it may improve performance and reduce artifacts in scenes with dense foliage, but it might also affect the accuracy of lighting on foliage surfaces.

Best practices when using this variable include:

  1. Enable it (set to 1) in scenes with dense grass or foliage to reduce aliasing artifacts.
  2. Disable it (set to 0) if accurate lighting on foliage surfaces is crucial for your scene.
  3. Test your scenes with both settings to find the best balance between performance and visual quality.

Regarding the associated variable GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits:

This is an integer variable that directly corresponds to the console variable. It’s used in the C++ code to actually implement the skipping of foliage hits during screen tracing. When this variable is true (1), the tracing algorithm will skip hits on Subsurface and TwoSided Foliage shading models.

The variable is used in the screen tracing logic, specifically in the TraceScreenProbes function, to set up parameters for the screen tracing compute shader. It affects how the tracing algorithm interacts with foliage geometry, potentially improving performance and reducing artifacts in scenes with dense vegetation.

Developers should be aware that changes to this variable will directly impact the behavior of the screen tracing algorithm. It’s important to test thoroughly when modifying this value, as it can affect both performance and visual quality, especially in scenes with significant foliage.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits( 
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits"),
	GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits,
	TEXT("Whether to allow screen traces to hit Subsurface and TwoSided Foliage shading models.  Can be used to work around aliasing from high frequency grass geometry."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations = 50;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits( 
	TEXT("r.Lumen.ScreenProbeGather.ScreenTraces.HZBTraversal.SkipFoliageHits"),
	GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits,
	TEXT("Whether to allow screen traces to hit Subsurface and TwoSided Foliage shading models.  Can be used to work around aliasing from high frequency grass geometry."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations = 50;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherHierarchicalScreenTracesMaxIterations(

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

Scope (from outer to inner):

file
function     void TraceScreenProbes
lambda-function

Source code excerpt:

			PassParameters->RelativeDepthThickness = GLumenScreenProbeGatherRelativeDepthThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->HistoryDepthTestRelativeThickness = GLumenScreenProbeGatherHistoryDepthTestRelativeThickness * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
			PassParameters->NumThicknessStepsToDetermineCertainty = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits ? 0 : GLumenScreenProbeGatherNumThicknessStepsToDetermineCertainty;
			PassParameters->MinimumTracingThreadOccupancy = GLumenScreenProbeGatherScreenTracesMinimumOccupancy;
			PassParameters->SkipFoliageHits = GLumenScreenProbeGatherHierarchicalScreenTracesSkipFoliageHits;

			PassParameters->ScreenProbeParameters = ScreenProbeParameters;
			PassParameters->IndirectTracingParameters = IndirectTracingParameters;
			PassParameters->RadianceCacheParameters = RadianceCacheParameters;

			const bool bHasHairStrands = HairStrands::HasViewHairStrandsData(View) && GLumenScreenProbeGatherHairStrands_ScreenTrace > 0;