r.GlobalDistanceField.Debug.LogModifiedPrimitives

r.GlobalDistanceField.Debug.LogModifiedPrimitives

#Overview

name: r.GlobalDistanceField.Debug.LogModifiedPrimitives

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

• type: Var
• help: Whether to log primitive modifications (add, remove, updatetransform) that caused an update of the global distance field.\nThis can be useful for tracking down why updating the global distance field is always costing a lot, since it should be mostly cached.\nPass 2 to log only non movable object updates.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GlobalDistanceField.Debug.LogModifiedPrimitives is to enable logging of primitive modifications that cause updates to the global distance field in Unreal Engine 5. This setting variable is primarily used for debugging and performance optimization in the rendering system, specifically for the global distance field feature.

This setting variable is used in the Renderer module of Unreal Engine 5, particularly in the global distance field and distance field object management subsystems.

The value of this variable is set through the console variable system in Unreal Engine. It can be changed at runtime using console commands or through configuration files.

The associated variable GGlobalDistanceFieldDebugLogModifiedPrimitives interacts directly with r.GlobalDistanceField.Debug.LogModifiedPrimitives. They share the same value, with the console variable controlling the internal engine variable.

Developers must be aware that:

1. This variable is intended for debugging purposes and may impact performance when enabled.
2. It has three possible states: 0 (off), 1 (log all modifications), and 2 (log only non-movable object updates).
3. Enabling this logging can help identify why the global distance field is being updated frequently, which could be a performance concern.

Best practices when using this variable include:

1. Use it temporarily for debugging performance issues related to global distance field updates.
2. Start with setting 2 to focus on non-movable object updates, which are less expected to change frequently.
3. Disable the logging (set to 0) in production builds to avoid any potential performance impact.

Regarding the associated variable GGlobalDistanceFieldDebugLogModifiedPrimitives:

• Its purpose is to serve as the internal engine representation of the console variable.
• It is used directly in the C++ code to control the logging behavior.
• The value is set by the console variable system and read in the LogDistanceFieldUpdate function.
• Developers should not modify this variable directly but instead use the console variable r.GlobalDistanceField.Debug.LogModifiedPrimitives to control its value.
• When using this variable in code, developers should be aware of the potential performance impact of frequent logging and use it judiciously.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GGlobalDistanceFieldDebugLogModifiedPrimitives = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugLogModifiedPrimitives(
	TEXT("r.GlobalDistanceField.Debug.LogModifiedPrimitives"),
	GGlobalDistanceFieldDebugLogModifiedPrimitives,
	TEXT("Whether to log 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.\n")
	TEXT("Pass 2 to log only non movable object updates."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldObjectManagement.cpp:299

Scope (from outer to inner):

file
function     void LogDistanceFieldUpdate

Source code excerpt:

void LogDistanceFieldUpdate(FPrimitiveSceneInfo const* PrimitiveSceneInfo, float BoundingRadius, bool bIsAddOperation)
{
	extern int32 GGlobalDistanceFieldDebugLogModifiedPrimitives;

	if (GGlobalDistanceFieldDebugLogModifiedPrimitives == 1
		|| (GGlobalDistanceFieldDebugLogModifiedPrimitives == 2 && !PrimitiveSceneInfo->Proxy->IsOftenMoving()))
	{
		UE_LOG(LogDistanceField, Log,
			TEXT("Global Distance Field %s primitive %s %s %s bounding radius %.1f"),
			PrimitiveSceneInfo->Proxy->IsOftenMoving() ? TEXT("Movable") : TEXT("CACHED"),
			(bIsAddOperation ? TEXT("add") : TEXT("update")),
			*PrimitiveSceneInfo->Proxy->GetOwnerName().ToString(),

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

Scope: file

Source code excerpt:

);

int32 GGlobalDistanceFieldDebugLogModifiedPrimitives = 0;
FAutoConsoleVariableRef CVarGlobalDistanceFieldDebugLogModifiedPrimitives(
	TEXT("r.GlobalDistanceField.Debug.LogModifiedPrimitives"),
	GGlobalDistanceFieldDebugLogModifiedPrimitives,
	TEXT("Whether to log 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.\n")
	TEXT("Pass 2 to log only non movable object updates."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);