r.DumpGPU.Mask

r.DumpGPU.Mask

#Overview

name: r.DumpGPU.Mask

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.DumpGPU.Mask is to control whether the GPU mask is included in the name of each Pass when dumping GPU information. This setting is particularly relevant for systems with multiple GPUs.

This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically in the GPU dumping functionality. It’s part of the RenderCore module, as evidenced by its location in the RenderCore/Private/DumpGPU.cpp file.

The value of this variable is set through a console variable system. It’s initialized with a default value of 1 (enabled) in the C++ code, but can be changed at runtime through console commands or configuration files.

The associated variable GDumpGPUMask interacts directly with r.DumpGPU.Mask. They share the same value and purpose. GDumpGPUMask is used in the C++ code to access the current value of the setting.

Developers should be aware that this setting only has an effect on systems with multiple GPUs. When enabled, it adds the GPU mask to the name of each Pass in the GPU dump, which can be useful for debugging and performance analysis on multi-GPU systems.

Best practices for using this variable include:

  1. Leaving it enabled (default value of 1) when working on or debugging multi-GPU systems.
  2. Disabling it (setting to 0) if you don’t need the GPU mask information, as it might slightly increase the size of the dump files.
  3. Using it in conjunction with other GPU dumping tools and settings for comprehensive debugging.

Regarding the associated variable GDumpGPUMask:

The purpose of GDumpGPUMask is to provide programmatic access to the r.DumpGPU.Mask setting within the C++ code.

It’s used in the RenderCore module, specifically in the GPU dumping functionality.

The value of GDumpGPUMask is set automatically based on the r.DumpGPU.Mask console variable. It’s accessed using the GetValueOnRenderThread() method, which suggests it’s designed to be thread-safe for use in render thread operations.

GDumpGPUMask interacts directly with the r.DumpGPU.Mask setting, essentially serving as its in-code representation.

Developers should be aware that changes to r.DumpGPU.Mask will be reflected in GDumpGPUMask. They should use GDumpGPUMask.GetValueOnRenderThread() when they need to check this setting’s value in render thread code.

Best practices include using GDumpGPUMask for conditional logic in GPU-related code, especially when dealing with multi-GPU scenarios or when generating debug output related to GPU operations.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


static TAutoConsoleVariable<int32> GDumpGPUMask(
	TEXT("r.DumpGPU.Mask"), 1,
	TEXT("Whether to include GPU mask in the name of each Pass (has no effect unless system has multiple GPUs)."),
	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpExploreCVar(
	TEXT("r.DumpGPU.Explore"), 1,
	TEXT("Whether to open file explorer to where the GPU dump on completion (enabled by default)."),

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpGPUMask(
	TEXT("r.DumpGPU.Mask"), 1,
	TEXT("Whether to include GPU mask in the name of each Pass (has no effect unless system has multiple GPUs)."),
	ECVF_Default);

static TAutoConsoleVariable<int32> GDumpExploreCVar(
	TEXT("r.DumpGPU.Explore"), 1,

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

Scope (from outer to inner):

file
function     static const TCHAR* GetPassEventNameWithGPUMask

Source code excerpt:

{
#if WITH_MGPU
	if ((GNumExplicitGPUsForRendering > 1) && GDumpGPUMask.GetValueOnRenderThread())
	{
		// Prepend GPU mask on the event name of each pass, so you can see which GPUs the pass ran on.  Putting the mask at the
		// front rather than the back makes all the masks line up, and easier to read (or ignore if you don't care about them).
		// Also, it's easy to globally search for passes with a particular GPU mask using name search in the dump browser.
		OutNameStorage = FString::Printf(TEXT("[%x] %s"), Pass->GetGPUMask().GetNative(), Pass->GetEventName().GetTCHAR());
		return *OutNameStorage;