rhi.UseSubmissionThread

rhi.UseSubmissionThread

#Overview

name: rhi.UseSubmissionThread

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

• type: Var
• help: Whether to enable the RHI submission thread.\n 0: No\n 1: Yes, but not when running with multi-gpu.\n 2: Yes, always\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of rhi.UseSubmissionThread is to control the usage of a submission thread in the RHI (Rendering Hardware Interface) system of Unreal Engine 5. This setting is specifically related to the Direct3D 12 (D3D12) rendering backend.

This setting variable is primarily used in the D3D12RHI module, which is responsible for interfacing with the Direct3D 12 API. Based on the callsites, it’s clear that this variable is crucial for the submission process in the D3D12 rendering pipeline.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with three possible values: 0: Do not use the submission thread 1: Use the submission thread, but not when running with multi-GPU 2: Always use the submission thread

The associated variable CVarRHIUseSubmissionThread directly interacts with rhi.UseSubmissionThread. They share the same value and purpose.

Developers must be aware of several important points when using this variable:

1. The comment suggests there are potential crashes when the submission thread is enabled with multi-GPU setups.
2. The variable is marked as ECVF_ReadOnly, meaning it should not be changed during runtime.
3. The choice of whether to use the submission thread can impact performance and stability, especially in multi-GPU scenarios.

Best practices when using this variable include:

1. Test thoroughly with different values, especially in multi-GPU environments.
2. Be cautious when enabling the submission thread (values 1 or 2) in multi-GPU setups due to potential crashes.
3. Consider the impact on performance and stability when choosing a value.
4. Be aware that using a submission thread might interfere with certain debugging tools, as indicated by the comment about RenderDoc captures.

Regarding the associated variable CVarRHIUseSubmissionThread: Its purpose is identical to rhi.UseSubmissionThread, serving as the programmatic interface to control the RHI submission thread usage. It’s used within the D3D12RHI module to determine whether to initialize the submission thread. The value is retrieved using GetValueOnAnyThread(), suggesting it can be accessed from multiple threads. Developers should be aware that changes to this variable will directly affect the behavior of the D3D12 rendering backend, potentially impacting performance and stability. Best practices include using this variable consistently with rhi.UseSubmissionThread and considering its impact on different GPU configurations and debugging scenarios.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

// @todo mgpu - fix crashes when submission thread is enabled)
static TAutoConsoleVariable<int32> CVarRHIUseSubmissionThread(
	TEXT("rhi.UseSubmissionThread"),
	2,
	TEXT("Whether to enable the RHI submission thread.\n")
	TEXT("  0: No\n")
	TEXT("  1: Yes, but not when running with multi-gpu.\n")
	TEXT("  2: Yes, always\n"),
	ECVF_ReadOnly);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// @todo mgpu - fix crashes when submission thread is enabled)
static TAutoConsoleVariable<int32> CVarRHIUseSubmissionThread(
	TEXT("rhi.UseSubmissionThread"),
	2,
	TEXT("Whether to enable the RHI submission thread.\n")
	TEXT("  0: No\n")
	TEXT("  1: Yes, but not when running with multi-gpu.\n")
	TEXT("  2: Yes, always\n"),

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

Scope (from outer to inner):

file
function     void FD3D12DynamicRHI::InitializeSubmissionPipe

Source code excerpt:

#if D3D12_USE_SUBMISSION_THREAD
		bool bUseSubmissionThread = false;
		switch (CVarRHIUseSubmissionThread.GetValueOnAnyThread())
		{
		case 1: bUseSubmissionThread = FRHIGPUMask::All().HasSingleIndex(); break;
		case 2: bUseSubmissionThread = true; break;
		}

		// Currently RenderDoc can't make programmatic captures when we use a submission thread.