r.D3D12.EnableD3DDebug

r.D3D12.EnableD3DDebug

#Overview

name: r.D3D12.EnableD3DDebug

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.D3D12.EnableD3DDebug is to control the D3D12 debug layer in Unreal Engine’s DirectX 12 rendering system. It provides various levels of debug information and error handling for DirectX 12 graphics programming.

This setting variable is primarily used by the D3D12RHI (Direct3D 12 Rendering Hardware Interface) module of Unreal Engine. It’s specifically utilized in the graphics rendering subsystem that interacts with DirectX 12.

The value of this variable is set through a console variable (Cvar) system. It can be set programmatically, through the console, or via command-line arguments. The associated variable GD3D12DebugCvar is used to access and modify this setting throughout the code.

The variable interacts with several functions that determine the behavior of the debug layer:

Developers must be aware that this variable has different levels of debug information: 0: Disable debug layer (default) 1: Enable error logging 2: Enable error & warning logging 3: Enable breaking on errors & warnings 4: Enable continuing on errors

Best practices when using this variable include:

  1. Use it judiciously in development and debugging phases, as it can impact performance.
  2. Be cautious when setting it to higher levels (3 or 4) in production environments, as it may cause unexpected behavior.
  3. Consider using command-line arguments for quick testing without modifying code.

Regarding the associated variable GD3D12DebugCvar: The purpose of GD3D12DebugCvar is to provide a programmatic interface to access and modify the r.D3D12.EnableD3DDebug setting. It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the debug level.

This variable is used throughout the D3D12RHI module to check the current debug level and adjust behavior accordingly. It’s particularly useful in functions that need to make decisions based on the current debug settings.

Developers should be aware that changes to GD3D12DebugCvar will immediately affect the behavior of the D3D12 debug layer. It’s important to use GetValueOnAnyThread() when accessing this variable to ensure thread-safe operations.

Best practices for GD3D12DebugCvar include using it for dynamic adjustments of debug levels during runtime, and considering its performance implications when frequently accessing its value in performance-critical code paths.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> GD3D12DebugCvar (
	TEXT("r.D3D12.EnableD3DDebug"),
	0,
	TEXT("0 to disable d3ddebug layer (default)\n")
	TEXT("1 to enable error logging (-d3ddebug) \n")
	TEXT("2 to enable error & warning logging (-d3dlogwarnings)\n")
	TEXT("3 to enable breaking on errors & warnings (-d3dbreakonwarning)\n")
	TEXT("4 to enable CONTINUING on errors (-d3dcontinueonerrors)\n"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#endif // PLATFORM_WINDOWS

TAutoConsoleVariable<int32> GD3D12DebugCvar (
	TEXT("r.D3D12.EnableD3DDebug"),
	0,
	TEXT("0 to disable d3ddebug layer (default)\n")
	TEXT("1 to enable error logging (-d3ddebug) \n")
	TEXT("2 to enable error & warning logging (-d3dlogwarnings)\n")
	TEXT("3 to enable breaking on errors & warnings (-d3dbreakonwarning)\n")

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

Scope (from outer to inner):

file
function     bool D3D12_ShouldLogD3DDebugWarnings

Source code excerpt:

bool D3D12_ShouldLogD3DDebugWarnings()
{
	return GD3D12DebugCvar.GetValueOnAnyThread() > 1;
}

bool D3D12_ShouldBreakOnD3DDebugErrors()
{
	return GD3D12DebugCvar.GetValueOnAnyThread() > 0 && GD3D12DebugCvar.GetValueOnAnyThread() != 4;
}

bool D3D12_ShouldBreakOnD3DDebugWarnings()
{
	return GD3D12DebugCvar.GetValueOnAnyThread() > 3;
}

#if PLATFORM_WINDOWS
static FAutoConsoleVariableRef CVarD3D12EnableGPUBreadCrumbs(
	TEXT("r.D3D12.BreadCrumbs"),
	GD3D12EnableGPUBreadCrumbs,

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

Scope (from outer to inner):

file
function     void FD3D12DynamicRHI::SetupD3D12Debug

Source code excerpt:

		FParse::Param(FCommandLine::Get(), TEXT("dxdebug")))
	{
		GD3D12DebugCvar->Set(1, ECVF_SetByCommandline);
	}
	if (FParse::Param(FCommandLine::Get(), TEXT("d3dlogwarnings")))
	{
		GD3D12DebugCvar->Set(2, ECVF_SetByCommandline);
	}
	if (FParse::Param(FCommandLine::Get(), TEXT("d3dbreakonwarning")))
	{
		GD3D12DebugCvar->Set(3, ECVF_SetByCommandline);
	}
	if (FParse::Param(FCommandLine::Get(), TEXT("d3dcontinueonerrors")))
	{
		GD3D12DebugCvar->Set(4, ECVF_SetByCommandline);
	}
	GRHIGlobals.IsDebugLayerEnabled = (GD3D12DebugCvar.GetValueOnAnyThread() > 0);

}

void FD3D12DynamicRHI::RHIRunOnQueue(ED3D12RHIRunOnQueueType QueueType, TFunction<void(ID3D12CommandQueue*)>&& CodeToRun, bool bWaitForSubmission)
{
	FGraphEventRef SubmissionEvent;

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12RHIPrivate.h:71

Scope: file

Source code excerpt:

using namespace D3D12RHI;

extern TAutoConsoleVariable<int32> GD3D12DebugCvar;

static bool D3D12RHI_ShouldCreateWithWarp()
{
	// Use the warp adapter if specified on the command line.
	static bool bCreateWithWarp = FParse::Param(FCommandLine::Get(), TEXT("warp"));
	return bCreateWithWarp;