D3D12.ResidencyManagement

D3D12.ResidencyManagement

#Overview

name: D3D12.ResidencyManagement

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.ResidencyManagement is to control whether Direct3D 12 resource residency management is active in the Unreal Engine’s D3D12RHI (Direct3D 12 Rendering Hardware Interface) module.

This setting variable is primarily used by the D3D12RHI module, which is responsible for interfacing with the Direct3D 12 API for rendering in Unreal Engine. It specifically affects the resource management aspect of the D3D12 implementation.

The value of this variable is set through a console variable (CVarResidencyManagement) defined in the D3D12Adapter.cpp file. It’s initialized with a default value of 1, meaning the residency management is enabled by default.

The associated variable GEnableResidencyManagement interacts directly with D3D12.ResidencyManagement. It’s a boolean variable that reflects the state of the console variable and is used throughout the code to check if residency management is enabled.

Developers must be aware that this variable is marked as ECVF_ReadOnly, meaning it should not be changed during runtime. It’s intended to be set before the engine initializes the D3D12 subsystem.

Best practices when using this variable include:

  1. Only disable it if there’s a specific need, as resource residency management can improve performance.
  2. If disabling, do so early in the initialization process, before the D3D12 device is created.
  3. Be aware that changing this setting may have performance implications and should be thoroughly tested.

Regarding the associated variable CVarResidencyManagement:

The purpose of CVarResidencyManagement is to provide a console-accessible way to control the D3D12 resource residency management feature.

It’s used in the same D3D12RHI module and is checked during the creation of the root D3D12 device.

The value is set through the console or configuration files, with a default value of 1 (enabled).

It directly influences the GEnableResidencyManagement global variable.

Developers should be aware that this is a read-only console variable, meaning it can’t be changed at runtime through normal means.

Best practices for CVarResidencyManagement include:

  1. Use it for debugging or performance testing purposes.
  2. If needed, set it in configuration files or startup parameters rather than trying to change it at runtime.
  3. Always validate performance impacts when changing this setting, as it can affect memory management and overall rendering performance.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

bool GEnableResidencyManagement = true;
static TAutoConsoleVariable<int32> CVarResidencyManagement(
	TEXT("D3D12.ResidencyManagement"),
	1,
	TEXT("Controls whether D3D12 resource residency management is active (default = on)."),
	ECVF_ReadOnly
);
#endif // ENABLE_RESIDENCY_MANAGEMENT

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#if ENABLE_RESIDENCY_MANAGEMENT
bool GEnableResidencyManagement = true;
static TAutoConsoleVariable<int32> CVarResidencyManagement(
	TEXT("D3D12.ResidencyManagement"),
	1,
	TEXT("Controls whether D3D12 resource residency management is active (default = on)."),
	ECVF_ReadOnly
);
#endif // ENABLE_RESIDENCY_MANAGEMENT

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

Scope (from outer to inner):

file
function     void FD3D12Adapter::CreateRootDevice

Source code excerpt:


#if ENABLE_RESIDENCY_MANAGEMENT
	if (!CVarResidencyManagement.GetValueOnAnyThread())
	{
		UE_LOG(LogD3D12RHI, Log, TEXT("D3D12 resource residency management is disabled."));
		GEnableResidencyManagement = false;
	}
#endif // ENABLE_RESIDENCY_MANAGEMENT