D3D12.ZeroBufferSizeInMB

D3D12.ZeroBufferSizeInMB

#Overview

name: D3D12.ZeroBufferSizeInMB

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 D3D12.ZeroBufferSizeInMB is to define the size of a static allocation of zeroes used by the Direct3D 12 Rendering Hardware Interface (RHI) for streaming textures asynchronously. This setting is crucial for the rendering system, specifically for texture streaming operations in the D3D12 RHI module.

This setting variable is primarily used in the D3D12RHI module of Unreal Engine 5. It’s utilized by the D3D12 Dynamic RHI (Rendering Hardware Interface) subsystem, which is responsible for interfacing with the Direct3D 12 API.

The value of this variable is set through a console variable (CVarD3D12ZeroBufferSizeInMB) with a default value of 4 MB. It can be modified at runtime, but it’s marked as read-only, suggesting that changes should be made carefully and preferably before the engine initialization.

The associated variable CVarD3D12ZeroBufferSizeInMB directly interacts with D3D12.ZeroBufferSizeInMB. They essentially represent the same setting, with CVarD3D12ZeroBufferSizeInMB being the console variable interface to control the setting.

Developers must be aware that this buffer should be large enough to support the largest mipmap that needs to be streamed. If the buffer is too small, it might lead to issues with texture streaming, potentially causing visual artifacts or performance problems.

Best practices when using this variable include:

  1. Adjusting the value based on the project’s specific needs, considering the largest mipmap size in use.
  2. Monitoring texture streaming performance and adjusting if necessary.
  3. Avoiding frequent runtime changes, as it’s marked as read-only.
  4. Considering the memory impact, especially on platforms with limited resources.

Regarding the associated variable CVarD3D12ZeroBufferSizeInMB:

The purpose of CVarD3D12ZeroBufferSizeInMB is to provide a console-accessible interface for controlling the D3D12.ZeroBufferSizeInMB setting. It allows for runtime querying and potentially modification of the zero buffer size used in texture streaming.

This console variable is defined in the D3D12RHI module and is used to initialize the actual zero buffer in the FD3D12DynamicRHI constructor.

The value of this variable is set when it’s declared, with a default of 4 MB. It can be queried at runtime using the GetValueOnAnyThread() method.

CVarD3D12ZeroBufferSizeInMB directly interacts with the ZeroBufferSize member of the FD3D12DynamicRHI class, which determines the actual size of the allocated zero buffer.

Developers should be aware that this is a console variable, meaning it can potentially be modified through console commands or configuration files. However, its ECVF_ReadOnly flag suggests that it’s not intended for frequent runtime changes.

Best practices for using this variable include:

  1. Using it for diagnostics and debugging of texture streaming issues.
  2. Adjusting it in configuration files rather than at runtime, respecting its read-only nature.
  3. Documenting any non-default values used in a project to ensure consistency across development and deployment environments.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarD3D12ZeroBufferSizeInMB(
	TEXT("D3D12.ZeroBufferSizeInMB"),
	4,
	TEXT("The D3D12 RHI needs a static allocation of zeroes to use when streaming textures asynchronously. It should be large enough to support the largest mipmap you need to stream. The default is 4MB."),
	ECVF_ReadOnly
	);

FD3D12DynamicRHI* FD3D12DynamicRHI::SingleD3DRHI = nullptr;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:



TAutoConsoleVariable<int32> CVarD3D12ZeroBufferSizeInMB(
	TEXT("D3D12.ZeroBufferSizeInMB"),
	4,
	TEXT("The D3D12 RHI needs a static allocation of zeroes to use when streaming textures asynchronously. It should be large enough to support the largest mipmap you need to stream. The default is 4MB."),
	ECVF_ReadOnly
	);

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

Scope (from outer to inner):

file
function     FD3D12DynamicRHI::FD3D12DynamicRHI

Source code excerpt:

	// Allocate a buffer of zeroes. This is used when we need to pass D3D memory
	// that we don't care about and will overwrite with valid data in the future.
	ZeroBufferSize = FMath::Max(CVarD3D12ZeroBufferSizeInMB.GetValueOnAnyThread(), 0) * (1 << 20);
	ZeroBuffer = FMemory::Malloc(ZeroBufferSize);
	FMemory::Memzero(ZeroBuffer, ZeroBufferSize);
#else
	ZeroBufferSize = 0;
	ZeroBuffer = nullptr;
#endif // PLATFORM_WINDOWS