r.Vulkan.DelayAcquireBackBuffer

r.Vulkan.DelayAcquireBackBuffer

#Overview

name: r.Vulkan.DelayAcquireBackBuffer

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Vulkan.DelayAcquireBackBuffer is to control the timing of back buffer acquisition in the Vulkan rendering pipeline. This setting variable is specifically for the Vulkan rendering system in Unreal Engine 5.

Based on the details in the Callsites section, this setting variable is primarily used in the VulkanRHI module, which is responsible for the Vulkan rendering implementation in Unreal Engine.

The value of this variable is set through a console variable (CVarDelayAcquireBackBuffer) defined in VulkanDevice.cpp. It can be set to 0, 1, or 2, each representing a different strategy for back buffer acquisition: 0: Acquire next image on frame start 1: Acquire next image just before presenting (default) 2: Acquire next image on first use

The associated variable GVulkanDelayAcquireImage interacts with r.Vulkan.DelayAcquireBackBuffer. It’s an enum (EDelayAcquireImageType) that gets its value based on the console variable’s setting.

Developers must be aware that changing this variable can affect the rendering pipeline’s behavior and potentially impact performance. The default value (1) is set to balance performance and flexibility, but different scenarios might benefit from other settings.

Best practices when using this variable include:

  1. Stick to the default value (1) unless there’s a specific need to change it.
  2. If changing, thoroughly test the impact on performance and rendering behavior.
  3. Be aware that setting it to 2 (LazyAcquire) might lead to scenarios where textures temporarily don’t have an associated image.

Regarding the associated variable CVarDelayAcquireBackBuffer:

The purpose of CVarDelayAcquireBackBuffer is to provide a runtime-configurable way to control the r.Vulkan.DelayAcquireBackBuffer setting. It’s defined as a TAutoConsoleVariable, which allows it to be changed during runtime via console commands.

This variable is used in the VulkanRHI module, specifically in the device initialization and management parts of the Vulkan implementation.

The value of CVarDelayAcquireBackBuffer is set when the console variable is defined, with a default value of 1. It can be changed at runtime using console commands.

The DelayAcquireBackBuffer() function uses this variable to determine the appropriate EDelayAcquireImageType to use in the Vulkan rendering pipeline.

Developers should be aware that this variable is marked as ECVF_ReadOnly, which means it should not be modified during gameplay. Changes should typically be made before the rendering pipeline is fully initialized.

Best practices for using CVarDelayAcquireBackBuffer include:

  1. Use console commands to experiment with different values during development.
  2. Document any non-default values used in shipping builds, as it affects rendering behavior.
  3. Consider exposing this setting in graphics options if you want to allow users to tweak it for performance reasons.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanDevice.cpp:68

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarDelayAcquireBackBuffer(
	TEXT("r.Vulkan.DelayAcquireBackBuffer"),
	1,
	TEXT("Whether to delay acquiring the back buffer \n")
	TEXT(" 0: acquire next image on frame start \n")
	TEXT(" 1: acquire next image just before presenting, rendering is done to intermediate image which is then copied to a real backbuffer (default) \n")
	TEXT(" 2: acquire next image on first use"),
	ECVF_ReadOnly

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanBarriers.cpp:1050

Scope (from outer to inner):

file
class        class FTransitionProcessor
function     void Process

Source code excerpt:

				const FVulkanPipelineBarrier::ImageBarrierExtraData* RemainingExtras = &Data->ImageBarrierExtras[Index];
				FVulkanTexture* Texture = RemainingExtras->BaseTexture;
				check(Texture->Image != VK_NULL_HANDLE || !Texture->IsImageOwner());  // coming in, we should always have an image, except backbuffer with r.Vulkan.DelayAcquireBackBuffer=2

				const int32 TargetIndex = ImageBatchStartIndex + Index;
				ImageBarrierType* RemainingBarriers = &ImageBarriers[TargetIndex];

				// EndTransition handles layout transition notifications
				if (!IsBeginTransition)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanDevice.cpp:67

Scope: file

Source code excerpt:

EDelayAcquireImageType GVulkanDelayAcquireImage = EDelayAcquireImageType::DelayAcquire;

TAutoConsoleVariable<int32> CVarDelayAcquireBackBuffer(
	TEXT("r.Vulkan.DelayAcquireBackBuffer"),
	1,
	TEXT("Whether to delay acquiring the back buffer \n")
	TEXT(" 0: acquire next image on frame start \n")
	TEXT(" 1: acquire next image just before presenting, rendering is done to intermediate image which is then copied to a real backbuffer (default) \n")
	TEXT(" 2: acquire next image on first use"),

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanDevice.cpp:79

Scope (from outer to inner):

file
function     static EDelayAcquireImageType DelayAcquireBackBuffer

Source code excerpt:

static EDelayAcquireImageType DelayAcquireBackBuffer()
{
	int32 DelayType = CVarDelayAcquireBackBuffer.GetValueOnAnyThread();
	switch (DelayType)
	{
	case 1:
		return EDelayAcquireImageType::DelayAcquire;
	case 2:
		return EDelayAcquireImageType::LazyAcquire;