r.GlobalDistanceField.Debug.DrawModifiedPrimitives

r.GlobalDistanceField.Debug.DrawModifiedPrimitives

#Overview

name: r.GlobalDistanceField.Debug.DrawModifiedPrimitives

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.GlobalDistanceField.Debug.DrawModifiedPrimitives is to enable debugging visualization for the Global Distance Field system in Unreal Engine 5. It specifically controls whether to draw primitive modifications that cause updates to the global distance field.

This setting variable is primarily used by the rendering system, particularly the Global Distance Field subsystem within the Renderer module. The Global Distance Field is a technique used for various rendering effects, including ambient occlusion, shadow casting, and other lighting-related calculations.

The value of this variable is set through the console or configuration files using the “r.GlobalDistanceField.Debug.DrawModifiedPrimitives” command. It is associated with the C++ variable GGlobalDistanceFieldDebugDrawModifiedPrimitives, which directly controls the behavior in the engine’s code.

The main interaction with this variable occurs in the ComputeUpdateRegionsAndUpdateViewState function within the GlobalDistanceField.cpp file. When enabled, it triggers the drawing of debug visualizations for modified primitives that cause updates to the global distance field.

Developers should be aware that enabling this debug feature may have performance implications, as it adds additional drawing operations. It should primarily be used for debugging and optimization purposes, not in production builds.

Best practices for using this variable include:

  1. Enable it temporarily when investigating performance issues related to frequent global distance field updates.
  2. Use it in conjunction with other debugging tools to identify which primitives are causing frequent updates.
  3. Disable it in production or when not actively debugging to avoid unnecessary performance overhead.

Regarding the associated variable GGlobalDistanceFieldDebugDrawModifiedPrimitives:

This is an integer variable that directly corresponds to the console variable. It is initialized to 0 (disabled) by default. The purpose of this variable is to provide a C++ accessible flag for the debug drawing feature.

The Renderer module uses this variable to determine whether to perform the debug drawing operations. It is checked in the ComputeUpdateRegionsAndUpdateViewState function to conditionally execute the debug visualization code.

Developers working directly with the C++ code can read or modify this variable to control the debug visualization programmatically. However, it’s generally recommended to use the console variable (r.GlobalDistanceField.Debug.DrawModifiedPrimitives) for consistency and to allow runtime toggling of the feature.

When using this variable in C++ code, developers should be mindful of the performance implications and ensure it’s only enabled in appropriate debug scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:287

Scope: file

Source code excerpt:

int32 GGlobalDistanceFieldDebugDrawModifiedPrimitives = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugDrawModifiedPrimitives(
	TEXT("r.GlobalDistanceField.Debug.DrawModifiedPrimitives"),
	GGlobalDistanceFieldDebugDrawModifiedPrimitives,
	TEXT("Whether to draw primitive modifications (add, remove, updatetransform) that caused an update of the global distance field.\n")
	TEXT("This can be useful for tracking down why updating the global distance field is always costing a lot, since it should be mostly cached."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:285

Scope: file

Source code excerpt:

);

int32 GGlobalDistanceFieldDebugDrawModifiedPrimitives = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugDrawModifiedPrimitives(
	TEXT("r.GlobalDistanceField.Debug.DrawModifiedPrimitives"),
	GGlobalDistanceFieldDebugDrawModifiedPrimitives,
	TEXT("Whether to draw primitive modifications (add, remove, updatetransform) that caused an update of the global distance field.\n")
	TEXT("This can be useful for tracking down why updating the global distance field is always costing a lot, since it should be mostly cached."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

bool UseGlobalDistanceField()

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/GlobalDistanceField.cpp:1148

Scope (from outer to inner):

file
function     static void ComputeUpdateRegionsAndUpdateViewState

Source code excerpt:

							Clipmap.UpdateBounds.Add(FClipmapUpdateBounds(ModifiedBounds.GetCenter(), ModifiedBounds.GetExtent(), true));
							
							if (GGlobalDistanceFieldDebugDrawModifiedPrimitives)
							{
								const uint8 MarkerHue = ((ClipmapIndex * 10 + BoundsIndex) * 10) & 0xFF;
								const uint8 MarkerSaturation = 0xFF;
								const uint8 MarkerValue = 0xFF;

								FLinearColor MarkerColor = FLinearColor::MakeFromHSV8(MarkerHue, MarkerSaturation, MarkerValue);