r.gpucrash.datadepth

r.gpucrash.datadepth

#Overview

name: r.gpucrash.datadepth

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

• type: Var
• help: Limits the amount of marker scope depth we record for GPU crash debugging to the given scope depth.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.gpucrash.datadepth is to limit the amount of marker scope depth recorded for GPU crash debugging. This setting variable is primarily used for GPU profiling and crash debugging in Unreal Engine 5.

This setting variable is utilized by multiple Unreal Engine subsystems, specifically the GPU profilers for different graphics APIs:

1. The core RHI (Rendering Hardware Interface) module
2. The D3D12RHI module (for DirectX 12)
3. The VulkanRHI module (for Vulkan)
4. The D3D11RHI module (for DirectX 11)

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with a default value of -1, which means there’s no limit on the scope depth by default.

This variable interacts closely with another console variable, r.gpucrash.collectionenable, which enables or disables GPU crash data collection. Together, these variables control the behavior of GPU crash debugging features.

Developers should be aware that:

1. Setting this variable to a positive integer will limit the depth of marker scopes recorded, which can be useful for performance reasons or to focus on specific levels of the rendering pipeline.
2. A value of -1 (the default) means no limit is applied.
3. This variable is marked as ECVF_RenderThreadSafe, meaning it can be changed at runtime without causing threading issues.

Best practices when using this variable include:

1. Only modify this variable when necessary for debugging GPU crashes or optimizing performance.
2. Consider the trade-off between debugging granularity and performance impact when setting a value.
3. Use in conjunction with r.gpucrash.collectionenable to fully control GPU crash debugging behavior.
4. Be aware that limiting the data depth might hide some useful information in complex scenarios, so adjust as needed based on the specific debugging requirements.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/GPUProfiler.cpp:79

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarGPUCrashDataDepth(
	TEXT("r.gpucrash.datadepth"),
	-1,
	TEXT("Limits the amount of marker scope depth we record for GPU crash debugging to the given scope depth."),
	ECVF_RenderThreadSafe);

enum class EGPUProfileSortMode
{

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

Scope (from outer to inner):

file
function     void D3D12RHI::FD3DGPUProfiler::BeginFrame

Source code excerpt:

	// update the crash tracking variables
	static auto* CrashCollectionEnableCvar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.collectionenable"));
	static auto* CrashCollectionDataDepth = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.datadepth"));

	bTrackingGPUCrashData = CrashCollectionEnableCvar ? (FD3D12DynamicRHI::GetD3DRHI()->GetAdapter().GetGPUCrashDebuggingModes() != ED3D12GPUCrashDebuggingModes::None && CrashCollectionEnableCvar->GetValueOnRenderThread() != 0) : false;
	GPUCrashDataDepth = CrashCollectionDataDepth ? CrashCollectionDataDepth->GetValueOnRenderThread() : -1;

	// latch the bools from the game thread into our private copy
	bLatchedGProfilingGPU = GTriggerGPUProfile;

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanUtil.cpp:561

Scope (from outer to inner):

file
function     void FVulkanGPUProfiler::BeginFrame

Source code excerpt:

	{
		static auto* CrashCollectionEnableCvar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.collectionenable"));
		static auto* CrashCollectionDataDepth = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.datadepth"));
		bTrackingGPUCrashData = CrashCollectionEnableCvar ? CrashCollectionEnableCvar->GetValueOnRenderThread() != 0 : false;
		GPUCrashDataDepth = CrashCollectionDataDepth ? CrashCollectionDataDepth->GetValueOnRenderThread() : -1;
		if (GPUCrashDataDepth == -1 || GPUCrashDataDepth > GMaxCrashBufferEntries)
		{
			if (Device->GetOptionalExtensions().HasAMDBufferMarker)
			{

#Loc: <Workspace>/Engine/Source/Runtime/Windows/D3D11RHI/Private/D3D11RHI.cpp:282

Scope (from outer to inner):

file
function     void FD3DGPUProfiler::BeginFrame

Source code excerpt:

	static auto* CrashCollectionEnableCvar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.collectionenable"));
	static auto* CrashCollectionDataDepth = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.gpucrash.datadepth"));

	bTrackingGPUCrashData = CrashCollectionEnableCvar ? CrashCollectionEnableCvar->GetValueOnRenderThread() != 0 : false;
	GPUCrashDataDepth = CrashCollectionDataDepth ? CrashCollectionDataDepth->GetValueOnRenderThread() : -1;
	
	// latch the bools from the game thread into our private copy
	bLatchedGProfilingGPU = GTriggerGPUProfile;