r.DumpGPU.Root

r.DumpGPU.Root

#Overview

name: r.DumpGPU.Root

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 r.DumpGPU.Root is to filter the rendering pass tree when using the r.DumpGPU command in Unreal Engine 5. It allows developers to selectively dump GPU-related information for specific rendering passes.

This setting variable is primarily used in the rendering system, specifically within the RenderCore module of Unreal Engine 5. It is utilized in the DumpGPU functionality, which is responsible for capturing and outputting information about GPU resources and rendering passes.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of “*”, which means it will dump information for all rendering passes by default.

The variable interacts closely with the r.DumpGPU command and other related variables like r.DumpGPU.Texture. It is used to determine which rendering passes should be included in the GPU dump output.

Developers must be aware that:

  1. The pattern matching for filtering is case-sensitive.
  2. Using “*” as the value will dump information for all rendering passes.
  3. The variable’s value is accessed on the render thread, so changes may not be immediately reflected.

Best practices when using this variable include:

  1. Use specific patterns to target only the rendering passes you’re interested in, to reduce the amount of output and processing time.
  2. Be mindful of performance implications when dumping GPU information, especially in production environments.
  3. Use in conjunction with other r.DumpGPU related variables for more granular control over the output.

Regarding the associated variable GDumpGPURootCVar:

The purpose of GDumpGPURootCVar is to provide a programmatic interface to the r.DumpGPU.Root console variable within the C++ code of Unreal Engine 5.

This variable is used internally by the RenderCore module to access and manipulate the value of r.DumpGPU.Root. It is defined as a TAutoConsoleVariable, which allows it to be easily integrated with Unreal Engine’s console variable system.

The value of GDumpGPURootCVar is set when the r.DumpGPU.Root console variable is modified, either through the console or programmatically.

GDumpGPURootCVar interacts directly with the r.DumpGPU.Root console variable, effectively serving as its C++ representation within the engine code.

Developers should be aware that:

  1. Changes to GDumpGPURootCVar will affect the behavior of the r.DumpGPU command.
  2. The variable is accessed on the render thread, so thread safety should be considered when modifying its value.

Best practices for using GDumpGPURootCVar include:

  1. Use the GetValueOnRenderThread() method to safely access its value from the render thread.
  2. Avoid frequent modifications to this variable, as it could impact performance.
  3. When modifying the variable programmatically, ensure it’s done in a thread-safe manner, considering the render thread implications.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:59

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


static TAutoConsoleVariable<FString> GDumpGPURootCVar(
	TEXT("r.DumpGPU.Root"),
	TEXT("*"),
	TEXT("Allows to filter the tree when using r.DumpGPU command, the pattern match is case sensitive."),
	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpTextureCVar(
	TEXT("r.DumpGPU.Texture"), 2,

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:1651

Scope (from outer to inner):

file
function     void AddDumpBufferPass

Source code excerpt:

				bDumpResourceInfos = true;

				// If not an output, it might be a resource undumped by r.DumpGPU.Root or external texture so still dump it as v0.
				if (!bIsOutputResource)
				{
					bDumpResourceBinary = true;
				}

				RegisterResourceAsDumped(Buffer, bIsOutputResource ? Pass : nullptr);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:1964

Scope: file

Source code excerpt:

	}

	// Look whether the pass matches matches r.DumpGPU.Root
	bool IsDumpingPass(const FRDGPass* Pass)
	{
		FString RootWildcardString = GDumpGPURootCVar.GetValueOnRenderThread();
		FWildcardString WildcardFilter(RootWildcardString);

		bool bDumpPass = (RootWildcardString == TEXT("*"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:58

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

{

static TAutoConsoleVariable<FString> GDumpGPURootCVar(
	TEXT("r.DumpGPU.Root"),
	TEXT("*"),
	TEXT("Allows to filter the tree when using r.DumpGPU command, the pattern match is case sensitive."),
	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpTextureCVar(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/DumpGPU.cpp:1967

Scope (from outer to inner):

file
function     bool IsDumpingPass

Source code excerpt:

	bool IsDumpingPass(const FRDGPass* Pass)
	{
		FString RootWildcardString = GDumpGPURootCVar.GetValueOnRenderThread();
		FWildcardString WildcardFilter(RootWildcardString);

		bool bDumpPass = (RootWildcardString == TEXT("*"));

		if (!bDumpPass)
		{