ShowFlag.LumenDetailTraces

ShowFlag.LumenDetailTraces

#Overview

name: ShowFlag.LumenDetailTraces

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.LumenDetailTraces is to control the use of detail tracing in Lumen, Unreal Engine 5’s global illumination system. This setting variable is part of the rendering system, specifically the Lumen subsystem, which handles real-time global illumination.

The Unreal Engine subsystem that relies on this setting variable is primarily the Lumen module within the rendering system. This can be seen from the references in the Lumen-related source files such as LumenDiffuseIndirect.cpp, LumenHeightfields.cpp, and LumenVisualize.cpp.

The value of this variable is set through the engine’s show flags system. It’s defined in the ShowFlagsValues.inl file, which suggests it can be toggled in the engine’s user interface or through code that manipulates show flags.

This variable interacts with several other Lumen-related variables, such as LumenScreenTraces, LumenGlobalTraces, LumenFarFieldTraces, and LumenSecondaryBounces. These variables collectively control different aspects of Lumen’s tracing system.

Developers must be aware that this variable affects the detail level of Lumen’s tracing. When enabled, it allows for more detailed global illumination calculations, which can improve visual quality but may also impact performance.

Best practices when using this variable include:

  1. Balancing visual quality with performance requirements.
  2. Using it in conjunction with other Lumen settings for optimal results.
  3. Testing thoroughly to ensure it doesn’t negatively impact frame rates in your specific use case.

Regarding the associated variable LumenDetailTraces, it appears to be the same variable as ShowFlag.LumenDetailTraces. The ShowFlag prefix likely indicates its use in the show flags system, while LumenDetailTraces is the actual variable name used in the code. This variable is used in multiple places to control the detail tracing feature of Lumen:

  1. In LumenDiffuseIndirect.cpp, it’s used to determine if mesh SDF tracing should be used.
  2. In LumenHeightfields.cpp, it’s part of the condition to determine if heightfield tracing should be used.
  3. In LumenVisualize.cpp, it’s used to control visualization of mesh SDF tracing.

The same considerations and best practices apply to this variable as discussed for ShowFlag.LumenDetailTraces. Developers should be aware that toggling this flag can significantly affect the visual quality and performance of Lumen’s global illumination system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(LumenScreenTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenScreenTracesSF", "Screen Traces"))
/** Use detail tracing in Lumen */
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"))

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_ALWAYS_ACCESSIBLE(LumenScreenTraces, SFG_Lumen, NSLOCTEXT("UnrealEd", "LumenScreenTracesSF", "Screen Traces"))
/** Use detail tracing in Lumen */
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"))

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

Scope (from outer to inner):

file
function     bool Lumen::UseMeshSDFTracing

Source code excerpt:

	return GLumenTraceMeshSDFs != 0 
		&& GLumenAllowTracingMeshSDFs != 0
		&& ViewFamily.EngineShowFlags.LumenDetailTraces;
}

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHeightfields.cpp:36

Scope (from outer to inner):

file
function     bool Lumen::UseHeightfieldTracing

Source code excerpt:

	return UseHeightfieldTracingForVoxelLighting(LumenSceneData)
		&& Lumen::UseMeshSDFTracing(ViewFamily)
		&& ViewFamily.EngineShowFlags.LumenDetailTraces;
}

int32 Lumen::GetHeightfieldMaxTracingSteps()
{
	return FMath::Clamp(CVarLumenSceneHeightfieldMaxTracingSteps.GetValueOnRenderThread(), 1, 256);
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:670

Scope (from outer to inner):

file
function     void SetupVisualizeParameters

Source code excerpt:

	// FLumenVisualizeSceneSoftwareRayTracingParameters
	{
		bool bTraceMeshSDF = GVisualizeLumenSceneTraceMeshSDFs != 0 && View.Family->EngineShowFlags.LumenDetailTraces;
		if (!bTraceMeshSDF)
		{
			MaxMeshSDFTraceDistance = 0.0f;
		}

		VisualizeParameters.VisualizeStepFactor = FMath::Clamp(GVisualizeLumenSceneConeStepFactor, .1f, 10.0f);