ShowFlag.LumenFarFieldTraces

ShowFlag.LumenFarFieldTraces

#Overview

name: ShowFlag.LumenFarFieldTraces

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.LumenFarFieldTraces is to control the visibility of far field traces in the Lumen global illumination system within Unreal Engine 5.

This setting variable is primarily used by the Lumen subsystem, which is part of Unreal Engine’s rendering module. It specifically affects the far field tracing functionality of Lumen, which is crucial for achieving realistic global illumination over larger distances.

The value of this variable is set through the engine show flags system, which allows for runtime toggling of various rendering features. It can be controlled via the engine’s user interface or programmatically.

The associated variable LumenFarFieldTraces interacts directly with ShowFlag.LumenFarFieldTraces, as they share the same value. This is evident from the SHOWFLAG_ALWAYS_ACCESSIBLE macro used in the ShowFlagsValues.inl file.

Developers must be aware that this variable affects the quality and performance of global illumination in their scenes. Enabling far field traces can significantly improve lighting quality, especially in large open environments, but may also impact performance.

Best practices when using this variable include:

  1. Carefully balancing visual quality and performance based on the specific needs of the project.
  2. Testing scenes with and without far field traces to determine the optimal setting for different scenarios.
  3. Considering the target hardware when deciding whether to enable this feature by default.

Regarding the associated variable LumenFarFieldTraces:

The purpose of LumenFarFieldTraces is to enable or disable the far field tracing feature in Lumen. It’s used in conjunction with ShowFlag.LumenFarFieldTraces to determine whether far field traces should be computed.

This variable is used in the Lumen subsystem of the rendering module, specifically in the UseFarField function within the LumenScene.cpp file.

The value of LumenFarFieldTraces is set through the engine show flags system, similar to ShowFlag.LumenFarFieldTraces.

It interacts with the CVarLumenFarField console variable, as seen in the UseFarField function. Both conditions (CVarLumenFarField being non-zero and LumenFarFieldTraces being true) must be met for far field tracing to be enabled.

Developers should be aware that this variable works in tandem with console variables to control Lumen’s behavior. It’s part of a larger system of settings that fine-tune the global illumination solution.

Best practices include:

  1. Coordinating the use of this show flag with other Lumen-related settings for optimal results.
  2. Considering the impact on both visual quality and performance when enabling or disabling this feature.
  3. Using this in combination with CVarLumenFarField for more granular control over far field tracing.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

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"))

/** Draw Nanite meshes */

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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"))

/** Draw Nanite meshes */

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:79

Scope (from outer to inner):

file
namespace    Lumen
function     bool UseFarField

Source code excerpt:

	{
		return CVarLumenFarField.GetValueOnRenderThread() != 0 
			&& ViewFamily.EngineShowFlags.LumenFarFieldTraces;
	}

	float GetFarFieldMaxTraceDistance()
	{
		return CVarLumenFarFieldMaxTraceDistance.GetValueOnRenderThread();
	}