r.Vulkan.AllowSynchronization2

r.Vulkan.AllowSynchronization2

#Overview

name: r.Vulkan.AllowSynchronization2

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

• type: Var
• help: Enables the use of advanced barriers that combine the use of the VK_KHR_separate_depth_stencil_layouts \nand VK_KHR_synchronization2 to reduce the reliance on layout tracking (except for defragging).\nThis is necessary in order to support parallel command buffer generation.\n0: Do not enable support for sync2 barriers.\n1: Enable sync2 barriers (default)

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Vulkan.AllowSynchronization2 is to enable the use of advanced barriers in Vulkan that combine the VK_KHR_separate_depth_stencil_layouts and VK_KHR_synchronization2 extensions. This setting is primarily used for the Vulkan rendering system within Unreal Engine 5.

The Vulkan RHI (Rendering Hardware Interface) module relies on this setting variable. Specifically, it is used in the implementation of various Vulkan extensions within the engine.

The value of this variable is set through a console variable (CVar) named GVulkanAllowSync2BarriersCVar. By default, it is set to 1, enabling the use of sync2 barriers.

This variable interacts with several Vulkan extension implementations:

1. FVulkanKHRSeparateDepthStencilLayoutsExtension
2. FVulkanKHRSynchronization2
3. FVulkanEXTDescriptorBuffer

Developers must be aware that this variable affects the engine’s use of advanced Vulkan features. Enabling this (which is the default) allows for reduced reliance on layout tracking and supports parallel command buffer generation.

Best practices when using this variable include:

1. Keep it enabled (default value of 1) unless there are specific reasons to disable it.
2. Be aware that changing this setting may impact performance and compatibility with certain Vulkan features.
3. Test thoroughly if modifying this setting, as it affects core rendering functionality.

Regarding the associated variable GVulkanAllowSync2BarriersCVar:

The purpose of GVulkanAllowSync2BarriersCVar is to provide a runtime-configurable way to control the r.Vulkan.AllowSynchronization2 setting. It is defined as a TAutoConsoleVariable, allowing it to be changed during runtime through console commands.

This variable is used directly in the Vulkan RHI module to determine whether to enable certain Vulkan extensions and features.

The value of GVulkanAllowSync2BarriersCVar is set when it’s declared, with a default value of 1. It can be changed at runtime through the console.

It interacts directly with the Vulkan extension implementations mentioned earlier, controlling whether these extensions are enabled in the code.

Developers should be aware that changing this variable at runtime may have immediate effects on the rendering pipeline and could potentially cause instability if not handled properly.

Best practices for using GVulkanAllowSync2BarriersCVar include:

1. Use it for debugging or performance testing purposes.
2. Be cautious when changing its value in a shipping game, as it may impact stability and performance.
3. If disabling it, ensure that your rendering code can handle the absence of these advanced Vulkan features.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanExtensions.cpp:60

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> GVulkanAllowSync2BarriersCVar(
	TEXT("r.Vulkan.AllowSynchronization2"),
	1,
	TEXT("Enables the use of advanced barriers that combine the use of the VK_KHR_separate_depth_stencil_layouts \n")
	TEXT("and VK_KHR_synchronization2 to reduce the reliance on layout tracking (except for defragging).\n")
	TEXT("This is necessary in order to support parallel command buffer generation.\n")
	TEXT("0: Do not enable support for sync2 barriers.\n")
	TEXT("1: Enable sync2 barriers (default)"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanExtensions.cpp:59

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> GVulkanAllowSync2BarriersCVar(
	TEXT("r.Vulkan.AllowSynchronization2"),
	1,
	TEXT("Enables the use of advanced barriers that combine the use of the VK_KHR_separate_depth_stencil_layouts \n")
	TEXT("and VK_KHR_synchronization2 to reduce the reliance on layout tracking (except for defragging).\n")
	TEXT("This is necessary in order to support parallel command buffer generation.\n")
	TEXT("0: Do not enable support for sync2 barriers.\n")

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanExtensions.cpp:316

Scope (from outer to inner):

file
class        class FVulkanKHRSeparateDepthStencilLayoutsExtension : public FVulkanDeviceExtension
function     FVulkanKHRSeparateDepthStencilLayoutsExtension

Source code excerpt:

		: FVulkanDeviceExtension(InDevice, VK_KHR_SEPARATE_DEPTH_STENCIL_LAYOUTS_EXTENSION_NAME, VULKAN_EXTENSION_ENABLED, VK_API_VERSION_1_2)
	{
		bEnabledInCode = bEnabledInCode && (GVulkanAllowSync2BarriersCVar.GetValueOnAnyThread() != 0);
	}

	virtual void PrePhysicalDeviceFeatures(VkPhysicalDeviceFeatures2KHR& PhysicalDeviceFeatures2) override final
	{
		ZeroVulkanStruct(SeparateDepthStencilLayoutsFeatures, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SEPARATE_DEPTH_STENCIL_LAYOUTS_FEATURES_KHR);
		AddToPNext(PhysicalDeviceFeatures2, SeparateDepthStencilLayoutsFeatures);

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanExtensions.cpp:353

Scope (from outer to inner):

file
class        class FVulkanKHRSynchronization2 : public FVulkanDeviceExtension
function     FVulkanKHRSynchronization2

Source code excerpt:

		: FVulkanDeviceExtension(InDevice, VK_KHR_SYNCHRONIZATION_2_EXTENSION_NAME, VULKAN_EXTENSION_ENABLED, VK_API_VERSION_1_3)
	{
		bEnabledInCode = bEnabledInCode && (GVulkanAllowSync2BarriersCVar.GetValueOnAnyThread() != 0);
	}

	virtual void PrePhysicalDeviceFeatures(VkPhysicalDeviceFeatures2KHR& PhysicalDeviceFeatures2) override final
	{
		ZeroVulkanStruct(Synchronization2Features, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES);
		AddToPNext(PhysicalDeviceFeatures2, Synchronization2Features);

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanExtensions.cpp:1142

Scope (from outer to inner):

file
class        class FVulkanEXTDescriptorBuffer : public FVulkanDeviceExtension
function     FVulkanEXTDescriptorBuffer

Source code excerpt:

	{
		// Sync2 is a prereq
		bEnabledInCode = bEnabledInCode && (GVulkanAllowSync2BarriersCVar.GetValueOnAnyThread() != 0);
	}

	virtual void PrePhysicalDeviceFeatures(VkPhysicalDeviceFeatures2KHR& PhysicalDeviceFeatures2) override final
	{
		ZeroVulkanStruct(DescriptorBufferFeatures, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_BUFFER_FEATURES_EXT);
		AddToPNext(PhysicalDeviceFeatures2, DescriptorBufferFeatures);