r.D3D12.DiagnosticBufferExtraMemory

r.D3D12.DiagnosticBufferExtraMemory

#Overview

name: r.D3D12.DiagnosticBufferExtraMemory

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

• type: Var
• help: Extra allocated memory for diagnostic buffer

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.D3D12.DiagnosticBufferExtraMemory is to allocate extra memory for the diagnostic buffer in the Direct3D 12 rendering system of Unreal Engine 5. This setting variable is primarily used in the D3D12RHI (Direct3D 12 Rendering Hardware Interface) module of Unreal Engine.

The D3D12RHI module relies on this setting variable to determine the additional memory to allocate for diagnostic purposes. Specifically, it’s used in the FD3D12Queue class when setting up the device after creation.

The value of this variable is set through a console variable (CVarD3D12ExtraDiagnosticBufferMemory) defined in the D3D12Device.cpp file. It’s initialized with a default value of 0 and is marked as read-only (ECVF_ReadOnly), meaning it can’t be changed at runtime.

This variable interacts with the ShaderDiagnosticBufferSize calculation. The extra memory specified by this variable is added to the base size of FD3D12DiagnosticBufferData structure.

Developers must be aware that this variable affects memory allocation for diagnostic purposes. Increasing this value will result in more memory being allocated, which could be useful for extensive debugging but might impact performance or memory usage in production builds.

Best practices when using this variable include:

1. Keep it at 0 for production builds to minimize unnecessary memory usage.
2. Increase it only when needed for debugging or diagnostics.
3. Be mindful of the total memory allocation, especially on platforms with limited resources.

Regarding the associated variable CVarD3D12ExtraDiagnosticBufferMemory:

The purpose of CVarD3D12ExtraDiagnosticBufferMemory is to provide a console-accessible way to control the r.D3D12.DiagnosticBufferExtraMemory setting. It’s defined as a TAutoConsoleVariable, which allows it to be changed via the console or configuration files.

This variable is used in the D3D12RHI module, specifically in the FD3D12Queue class during device setup.

The value of this variable is initially set to 0, but can be changed through the console or configuration files due to its nature as a console variable.

It directly interacts with the r.D3D12.DiagnosticBufferExtraMemory setting, effectively controlling its value.

Developers should be aware that while this variable allows for runtime configuration, it’s marked as read-only (ECVF_ReadOnly), which means changes may not take effect immediately or may require a restart to apply.

Best practices for using this variable include:

1. Use it for debugging and diagnostic purposes only.
2. Document any non-zero values used during development to ensure consistency across the team.
3. Ensure it’s set back to 0 for production builds to avoid unnecessary memory allocation.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarD3D12ExtraDiagnosticBufferMemory(
	TEXT("r.D3D12.DiagnosticBufferExtraMemory"),
	0,
	TEXT("Extra allocated memory for diagnostic buffer"),
	ECVF_ReadOnly
);

static uint32 GetQueryHeapPoolIndex(D3D12_QUERY_HEAP_TYPE HeapType)

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarD3D12ExtraDiagnosticBufferMemory(
	TEXT("r.D3D12.DiagnosticBufferExtraMemory"),
	0,
	TEXT("Extra allocated memory for diagnostic buffer"),
	ECVF_ReadOnly
);

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

Scope (from outer to inner):

file
function     void FD3D12Queue::SetupAfterDeviceCreation

Source code excerpt:

		if (SUCCEEDED(hr))
		{
			const uint32 ShaderDiagnosticBufferSize = sizeof(FD3D12DiagnosticBufferData) + FMath::Max(0, CVarD3D12ExtraDiagnosticBufferMemory.GetValueOnAnyThread());

			// Allocate persistent CPU readable memory which will still be valid after a device lost and wrap this data in a placed resource
			// so the GPU command list can write to it
			int32 MaxBreadcrumbsContexts = MAX_GPU_BREADCRUMB_CONTEXTS;
			int32 MaxBreadcrumbsSize = MAX_GPU_BREADCRUMB_SIZE;
			const uint32 EventBufferSize = MaxBreadcrumbsSize * MaxBreadcrumbsContexts * sizeof(uint32);