r.D3D12.BreadCrumbs

r.D3D12.BreadCrumbs

#Overview

name: r.D3D12.BreadCrumbs

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

• type: Var
• help: Enable minimal overhead GPU Breadcrumbs to track the current GPU state and logs information what operations the GPU executed last.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.D3D12.BreadCrumbs is to enable minimal overhead GPU Breadcrumbs for tracking the current GPU state and logging information about the last operations executed by the GPU. This setting is part of the GPU crash debugging system in Unreal Engine 5’s D3D12 rendering implementation.

This setting variable is primarily used by the D3D12RHI (Direct3D 12 Rendering Hardware Interface) module of Unreal Engine 5. It’s specifically utilized in the GPU crash debugging functionality within the D3D12 adapter implementation.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

This variable interacts with other GPU crash debugging-related variables, such as r.D3D12.NvAfterMath and r.D3D12.DRED. It’s part of a broader set of options for GPU crash debugging, including the r.GPUCrashDebugging console variable and command-line arguments like “gpucrashdebugging”.

Developers should be aware that enabling this variable will introduce some overhead, albeit minimal, to GPU operations. It’s primarily intended for debugging purposes and may impact performance slightly when enabled.

Best practices for using this variable include:

1. Enable it when investigating GPU-related crashes or performance issues.
2. Use it in conjunction with other GPU crash debugging tools like NvAftermath and DRED for comprehensive analysis.
3. Consider disabling it in release builds or when performance is critical, unless GPU crash information is necessary for your specific use case.
4. Be aware of its interaction with other GPU crash debugging settings and command-line arguments to ensure the desired debugging configuration.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Adapter.cpp:94

Scope: file

Source code excerpt:

#if PLATFORM_WINDOWS
static FAutoConsoleVariableRef CVarD3D12EnableGPUBreadCrumbs(
	TEXT("r.D3D12.BreadCrumbs"),
	GD3D12EnableGPUBreadCrumbs,
	TEXT("Enable minimal overhead GPU Breadcrumbs to track the current GPU state and logs information what operations the GPU executed last.\n"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

static FAutoConsoleVariableRef CVarD3D12EnableNvAftermath(
	TEXT("r.D3D12.NvAfterMath"),

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Adapter.cpp:1415

Scope (from outer to inner):

file
function     void FD3D12Adapter::SetupGPUCrashDebuggingModesCommon

Source code excerpt:

	// - via RHI independent r.GPUCrashDebugging cvar: by default enable low overhead breadcrumbs and NvAftermath are enabled
	// - via 'gpucrashdebugging' command line argument: enable all possible GPU crash debug modes (minor performance impact)
	// - via 'r.D3D12.BreadCrumbs', 'r.D3D12.AfterMath' or 'r.D3D12.Dred' each type of GPU crash debugging mode can be enabled
	// - via '-gpubreadcrumbs(=0)', '-nvaftermath(=0)' or '-dred(=0)' command line argument: each type of gpu crash debugging mode can enabled/disabled
	if (FParse::Param(FCommandLine::Get(), TEXT("gpucrashdebugging")))
	{
		GPUCrashDebuggingModes = ED3D12GPUCrashDebuggingModes::All;
	}
	else

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Adapter.cpp:1433

Scope (from outer to inner):

file
function     void FD3D12Adapter::SetupGPUCrashDebuggingModesCommon

Source code excerpt:

		};
		ParseCVar(TEXT("r.GPUCrashDebugging"), ED3D12GPUCrashDebuggingModes((int)ED3D12GPUCrashDebuggingModes::NvAftermath | (int)ED3D12GPUCrashDebuggingModes::DRED));
		ParseCVar(TEXT("r.D3D12.BreadCrumbs"), ED3D12GPUCrashDebuggingModes::BreadCrumbs);
		ParseCVar(TEXT("r.D3D12.NvAfterMath"), ED3D12GPUCrashDebuggingModes::NvAftermath);
		ParseCVar(TEXT("r.D3D12.DRED"), ED3D12GPUCrashDebuggingModes::DRED);

		// Enable/disable specific crash debugging modes if requested via command line argument
		const auto ParseCommandLine = [this](const TCHAR* CommandLineArgument, ED3D12GPUCrashDebuggingModes DebuggingMode)
		{