r.Vulkan.DebugBarrier

r.Vulkan.DebugBarrier

#Overview

name: r.Vulkan.DebugBarrier

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.DebugBarrier is to force full barriers for debugging in the Vulkan rendering system. It is a debug-focused setting that allows developers to insert heavy barriers at specific points in the rendering pipeline to help diagnose synchronization issues.

This setting variable is primarily used in the Vulkan RHI (Rendering Hardware Interface) subsystem of Unreal Engine 5. It’s specifically implemented in the VulkanRHI module, as evidenced by its references in VulkanRenderTarget.cpp and VulkanRHIPrivate.h.

The value of this variable is set through the console variable system. It’s defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands or configuration files.

The variable interacts with itself as a bitmask. Different bit values correspond to different barrier insertion points:

Developers must be aware that this is a debug-only feature, available only in Debug and Development builds. It’s not meant for use in shipping builds. Also, enabling these barriers can significantly impact performance, so it should only be used when necessary for debugging purposes.

Best practices for using this variable include:

  1. Only enable it when debugging synchronization issues in Vulkan rendering.
  2. Use the bitmask to target specific areas of concern rather than enabling all barriers at once.
  3. Remember to disable it after debugging to restore normal performance.

The associated variable CVarVulkanDebugBarrier is the actual console variable object that stores and manages the r.Vulkan.DebugBarrier setting. It’s used internally by the engine to check the current value of the setting and apply the appropriate debug barriers.

The purpose of CVarVulkanDebugBarrier is to provide a runtime-accessible interface for the r.Vulkan.DebugBarrier setting. It’s used in the DebugHeavyWeightBarrier function to determine whether to insert a heavy-weight barrier based on the current setting value and a condition mask.

Developers should be aware that CVarVulkanDebugBarrier is only defined in debug and development builds. In release builds, any code referencing this variable should be automatically excluded by the preprocessor.

When working with CVarVulkanDebugBarrier, developers should:

  1. Use GetValueOnAnyThread() to safely read its value from any thread.
  2. Be cautious about frequently checking its value in performance-critical code paths, as it could introduce unnecessary overhead.
  3. Remember that changes to this variable at runtime will immediately affect the engine’s behavior, which can be useful for interactive debugging but could also lead to inconsistent behavior if not managed carefully.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanRenderTarget.cpp:47

Scope: file

Source code excerpt:

#if UE_BUILD_DEBUG || UE_BUILD_DEVELOPMENT
TAutoConsoleVariable<int32> CVarVulkanDebugBarrier(
	TEXT("r.Vulkan.DebugBarrier"),
	0,
	TEXT("Forces a full barrier for debugging. This is a mask/bitfield (so add up the values)!\n")
	TEXT(" 0: Don't (default)\n")
	TEXT(" 1: Enable heavy barriers after EndRenderPass()\n")
	TEXT(" 2: Enable heavy barriers after every dispatch\n")
	TEXT(" 4: Enable heavy barriers after upload cmd buffers\n")

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanRHIPrivate.h:737

Scope: file

Source code excerpt:


#if UE_BUILD_DEBUG || UE_BUILD_DEVELOPMENT
extern TAutoConsoleVariable<int32> CVarVulkanDebugBarrier;
#endif

namespace VulkanRHI
{
	static inline FString GetPipelineCacheFilename()
	{

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanRHIPrivate.h:890

Scope (from outer to inner):

file
namespace    VulkanRHI
function     inline void DebugHeavyWeightBarrier

Source code excerpt:

	{
#if UE_BUILD_DEBUG || UE_BUILD_DEVELOPMENT
		if (CVarVulkanDebugBarrier.GetValueOnAnyThread() & CVarConditionMask)
		{
			HeavyWeightBarrier(CmdBuffer);
		}
#endif
	}
}

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanRenderTarget.cpp:46

Scope: file

Source code excerpt:


#if UE_BUILD_DEBUG || UE_BUILD_DEVELOPMENT
TAutoConsoleVariable<int32> CVarVulkanDebugBarrier(
	TEXT("r.Vulkan.DebugBarrier"),
	0,
	TEXT("Forces a full barrier for debugging. This is a mask/bitfield (so add up the values)!\n")
	TEXT(" 0: Don't (default)\n")
	TEXT(" 1: Enable heavy barriers after EndRenderPass()\n")
	TEXT(" 2: Enable heavy barriers after every dispatch\n")