r.GlobalDistanceField.Debug.ShowStats

r.GlobalDistanceField.Debug.ShowStats

#Overview

name: r.GlobalDistanceField.Debug.ShowStats

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

• type: Var
• help: Debug drawing for the Global Distance Field.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GlobalDistanceField.Debug.ShowStats is to enable debug drawing for the Global Distance Field in Unreal Engine’s rendering system. This setting variable is primarily used for debugging and performance analysis of the Global Distance Field feature.

This setting variable is utilized within the Renderer module of Unreal Engine, specifically in the Global Distance Field subsystem. The code references are found in the GlobalDistanceField.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVarGlobalDistanceFieldDebugShowStats) using the TAutoConsoleVariable template. It is initialized with a default value of 0 (false), meaning the debug stats are not shown by default.

The associated variable CVarGlobalDistanceFieldDebugShowStats directly interacts with r.GlobalDistanceField.Debug.ShowStats. They share the same value and purpose.

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

Best practices when using this variable include:

1. Only enable it when necessary for debugging or performance analysis.
2. Disable it in production builds to avoid unnecessary performance overhead.
3. Use it in conjunction with other Global Distance Field debugging tools for comprehensive analysis.

Regarding the associated variable CVarGlobalDistanceFieldDebugShowStats:

The purpose of CVarGlobalDistanceFieldDebugShowStats is to provide a programmatic way to access and modify the r.GlobalDistanceField.Debug.ShowStats setting within the C++ code.

This console variable is used in the Renderer module, specifically in the Global Distance Field calculations and debug rendering.

The value of CVarGlobalDistanceFieldDebugShowStats is set when the engine initializes the console variables, and it can be changed at runtime through console commands.

It directly controls the behavior of the debug stats display for the Global Distance Field. When its value is true, additional debug information is rendered and calculated.

Developers should be aware that checking the value of this variable may occur in performance-critical sections of the rendering code. Therefore, frequent polling of its value should be avoided if possible.

Best practices for using CVarGlobalDistanceFieldDebugShowStats include:

1. Use GetValueOnRenderThread() when accessing its value in render thread code.
2. Consider caching its value if used frequently in a single frame to avoid repeated calls to GetValueOnRenderThread().
3. Be mindful of the performance implications when enabling this debug feature, especially in complex scenes with extensive use of Global Distance Fields.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<bool> CVarGlobalDistanceFieldDebugShowStats(
	TEXT("r.GlobalDistanceField.Debug.ShowStats"),
	0,
	TEXT("Debug drawing for the Global Distance Field."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GGlobalDistanceFieldDebugForceMovementUpdate = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<bool> CVarGlobalDistanceFieldDebugShowStats(
	TEXT("r.GlobalDistanceField.Debug.ShowStats"),
	0,
	TEXT("Debug drawing for the Global Distance Field."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     class FInitPageFreeListCS : public FGlobalShader { /*ARE_GLOBAL_SHADER
class        class FInitPageFreeListCS : public FGlobalShader
function     if

Source code excerpt:

		}

		if (CVarGlobalDistanceFieldDebugShowStats.GetValueOnRenderThread())
		{
			for (const FGlobalDistanceFieldPackedClipmap& PackedClipmap : PackedClipmaps)
			{
				FGlobalDistanceFieldAccumulateUpdatedPagesCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FGlobalDistanceFieldAccumulateUpdatedPagesCS::FParameters>();
					PassParameters->PageComposeIndirectArgBuffer = GraphBuilder.CreateSRV(PackedClipmap.PageComposeIndirectArgBuffer);
					PassParameters->RWPageStatsBuffer = GraphBuilder.CreateUAV(PageStatsBuffer);

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

Scope (from outer to inner):

file
function     void UpdateGlobalDistanceFieldVolume

Source code excerpt:

		}

		if (CVarGlobalDistanceFieldDebugShowStats.GetValueOnRenderThread()
			&& GlobalDistanceFieldInfo.PageFreeListAllocatorBuffer 
			&& GlobalDistanceFieldInfo.PageAtlasTexture)
		{
			RDG_EVENT_SCOPE(GraphBuilder, "GlobalDistanceFieldDebug");

			ShaderPrint::SetEnabled(true);