ShowFlag.LumenGlobalTraces

ShowFlag.LumenGlobalTraces

#Overview

name: ShowFlag.LumenGlobalTraces

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 ShowFlag.LumenGlobalTraces is to control the use of global traces in the Lumen global illumination system within Unreal Engine 5. This setting variable is part of the rendering system, specifically the Lumen lighting technology.

This setting variable is primarily relied upon by the Lumen subsystem within Unreal Engine’s rendering module. It’s used to determine whether global traces should be performed as part of the Lumen lighting calculations.

The value of this variable is set through the engine’s show flags system, which allows for runtime toggling of various rendering features. It can be accessed and modified through the ViewFamily.EngineShowFlags structure.

The associated variable LumenGlobalTraces interacts directly with ShowFlag.LumenGlobalTraces, as they share the same value. This is evident from their declaration in the same ShowFlagsValues.inl file.

Developers must be aware that enabling or disabling this flag will affect the global illumination quality and performance of the Lumen system. Global traces contribute to the overall lighting accuracy but may have a performance impact.

Best practices when using this variable include:

  1. Consider the performance implications of enabling global traces, especially on lower-end hardware.
  2. Use it in conjunction with other Lumen settings like LumenDetailTraces and LumenFarFieldTraces for a balanced approach to lighting quality and performance.
  3. Test the visual impact and performance with this flag both enabled and disabled to find the optimal setting for your specific use case.

Regarding the associated variable LumenGlobalTraces:

The purpose of LumenGlobalTraces is identical to ShowFlag.LumenGlobalTraces, as they are essentially the same setting represented in different contexts.

This variable is used directly in the Lumen subsystem of the rendering module, as seen in the LumenDiffuseIndirect.cpp file. Specifically, it’s used in the UseGlobalSDFTracing function to determine if global SDF (Signed Distance Field) tracing should be performed.

The value of LumenGlobalTraces is set through the same mechanism as ShowFlag.LumenGlobalTraces, via the engine’s show flags system.

Developers should be aware that this variable directly affects the Lumen global illumination calculations, particularly the use of global SDF tracing. Enabling or disabling this can significantly impact both visual quality and performance.

Best practices for using LumenGlobalTraces include:

  1. Carefully consider the trade-off between lighting quality and performance when enabling or disabling this feature.
  2. Use profiling tools to measure the performance impact of enabling global SDF tracing in your specific scenes.
  3. Consider using this in combination with other Lumen settings to achieve the desired balance of quality and performance for your project.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:435

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(LumenDetailTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenDetailTracesSF", "Detail Traces"))
/** Use global traces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenGlobalTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenGlobalTracesSF", "Global Traces"))
/** Use far field traces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenFarFieldTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenFarFieldTracesSF", "Far Field Traces"))
/** Compute secondary bounces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenSecondaryBounces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenSecondaryBouncesSF", "Secondary Bounces"))
/** Compute screen space directional occlusion in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenShortRangeAmbientOcclusion, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenShortRangeAmbientOcclusionSF", "Short Range Ambient Occlusion"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:435

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(LumenDetailTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenDetailTracesSF", "Detail Traces"))
/** Use global traces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenGlobalTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenGlobalTracesSF", "Global Traces"))
/** Use far field traces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenFarFieldTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenFarFieldTracesSF", "Far Field Traces"))
/** Compute secondary bounces in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenSecondaryBounces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenSecondaryBouncesSF", "Secondary Bounces"))
/** Compute screen space directional occlusion in Lumen */
SHOWFLAG_ALWAYS_ACCESSIBLE(LumenShortRangeAmbientOcclusion, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenShortRangeAmbientOcclusionSF", "Short Range Ambient Occlusion"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:199

Scope (from outer to inner):

file
function     bool Lumen::UseGlobalSDFTracing

Source code excerpt:

bool Lumen::UseGlobalSDFTracing(const FSceneViewFamily& ViewFamily)
{
	return ViewFamily.EngineShowFlags.LumenGlobalTraces;
}

bool Lumen::UseGlobalSDFSimpleCoverageBasedExpand()
{
	return GLumenSceneGlobalSDFSimpleCoverageBasedExpand != 0;
}