r.RHICmdMergeSmallDeferredContexts

r.RHICmdMergeSmallDeferredContexts

#Overview

name: r.RHICmdMergeSmallDeferredContexts

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 r.RHICmdMergeSmallDeferredContexts is to control the merging of small parallel translate tasks in the rendering pipeline. This setting is part of the RHI (Rendering Hardware Interface) system in Unreal Engine 5.

This variable is primarily used in the RHI module, specifically within the RHICommandList system. It’s referenced in the RHICommandList.cpp file, which is a core component of Unreal Engine’s rendering system.

The value of this variable is set using a console variable (CVar) system. It’s initialized with a default value of 1 (enabled) but can be changed at runtime through console commands or configuration files.

The associated variable CVarRHICmdMergeSmallDeferredContexts directly interacts with r.RHICmdMergeSmallDeferredContexts. They share the same value and purpose.

Developers must be aware that this variable affects the performance and behavior of parallel rendering tasks. When enabled (set to 1), the engine will attempt to merge small parallel translate tasks based on another setting, r.RHICmdMinDrawsPerParallelCmdList.

Best practices when using this variable include:

  1. Keeping it enabled (default value of 1) for most scenarios, as it can potentially improve performance by reducing overhead from many small tasks.
  2. Disabling it (set to 0) if you notice any rendering artifacts or inconsistencies that may be caused by task merging.
  3. Considering the interplay between this variable and r.RHICmdMinDrawsPerParallelCmdList when fine-tuning rendering performance.
  4. Using profiling tools to measure the impact of enabling or disabling this feature in your specific use case.

Regarding the associated variable CVarRHICmdMergeSmallDeferredContexts:

The purpose of CVarRHICmdMergeSmallDeferredContexts is identical to r.RHICmdMergeSmallDeferredContexts. It’s an internal representation of the console variable used within the C++ code.

This variable is used in the RHI module, specifically in the FRHICommandListImmediate::QueueAsyncCommandListSubmit function. It controls whether small deferred contexts should be merged during command list submission.

The value of this variable is set through the console variable system and can be accessed in C++ code using GetValueOnRenderThread() method.

CVarRHICmdMergeSmallDeferredContexts directly interacts with r.RHICmdMergeSmallDeferredContexts, as they represent the same setting.

Developers should be aware that this variable is used in performance-critical rendering code. Changes to its value can affect rendering efficiency and behavior.

Best practices for using CVarRHICmdMergeSmallDeferredContexts include:

  1. Avoid changing its value directly in C++ code unless absolutely necessary.
  2. Use the console variable r.RHICmdMergeSmallDeferredContexts to modify this setting during development and testing.
  3. Be cautious when modifying this value in shipping builds, as it can affect rendering performance and stability.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHICommandList.cpp:53

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRHICmdMergeSmallDeferredContexts(
	TEXT("r.RHICmdMergeSmallDeferredContexts"),
	1,
	TEXT("When it can be determined, merge small parallel translate tasks based on r.RHICmdMinDrawsPerParallelCmdList."));

static TAutoConsoleVariable<int32> CVarRHICmdBufferWriteLocks(
	TEXT("r.RHICmdBufferWriteLocks"),
	1,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHICommandList.cpp:52

Scope: file

Source code excerpt:

	TEXT("If true, then we flush the render thread tasks every pass. For issue diagnosis. This is a main switch for more granular cvars."));

static TAutoConsoleVariable<int32> CVarRHICmdMergeSmallDeferredContexts(
	TEXT("r.RHICmdMergeSmallDeferredContexts"),
	1,
	TEXT("When it can be determined, merge small parallel translate tasks based on r.RHICmdMinDrawsPerParallelCmdList."));

static TAutoConsoleVariable<int32> CVarRHICmdBufferWriteLocks(
	TEXT("r.RHICmdBufferWriteLocks"),

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHICommandList.cpp:516

Scope (from outer to inner):

file
function     void FRHICommandListImmediate::QueueAsyncCommandListSubmit

Source code excerpt:

		TArrayView<FTask> Tasks = AllocArrayUninitialized<FTask>(CommandLists.Num());

		const bool bMerge = !!CVarRHICmdMergeSmallDeferredContexts.GetValueOnRenderThread();
		for (int32 RangeStart = 0, RangeEnd = 0; RangeStart < CommandLists.Num(); RangeStart = RangeEnd)
		{
			RangeEnd = RangeStart + 1;

			if (bMerge)
			{