r.Vulkan.Allow64bitShaderAtomics

r.Vulkan.Allow64bitShaderAtomics

#Overview

name: r.Vulkan.Allow64bitShaderAtomics

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.Allow64bitShaderAtomics is to control the enablement of 64-bit buffer and image atomics in Vulkan, which are required by the Nanite system in Unreal Engine 5.

This setting variable is primarily used in the Vulkan RHI (Rendering Hardware Interface) subsystem of Unreal Engine 5. It specifically affects the functionality related to Vulkan extensions for shader atomic operations.

The value of this variable is set through a console variable (CVar) named GRHIAllow64bitShaderAtomicsCvar. It is initialized with a default value of 1, meaning 64-bit shader atomics are enabled by default.

Two other variables interact closely with this setting:

  1. FVulkanShaderAtomicInt64Extension: This extension is for 64-bit buffer atomics.
  2. FVulkanShaderImageAtomicInt64Extension: This extension is for 64-bit image atomics.

Both of these extensions check the value of GRHIAllow64bitShaderAtomicsCvar to determine if they should be enabled.

Developers should be aware that:

  1. This setting is marked as ECVF_ReadOnly, meaning it should be set at startup and not changed during runtime.
  2. Disabling this feature (by setting it to 0) may affect the functionality of the Nanite system, which relies on these 64-bit atomic operations.

Best practices when using this variable include:

  1. Only disable it if you’re certain your project doesn’t require 64-bit shader atomics or Nanite functionality.
  2. If experiencing issues with Vulkan rendering, particularly related to Nanite, ensure this setting is enabled.
  3. When debugging Vulkan-related problems, checking the state of this variable might provide insights into the behavior of 64-bit shader atomics.

Regarding the associated variable GRHIAllow64bitShaderAtomicsCvar:

The purpose of GRHIAllow64bitShaderAtomicsCvar is to provide a programmatic interface to control the r.Vulkan.Allow64bitShaderAtomics setting. It’s an instance of TAutoConsoleVariable, which allows the engine to expose this setting as a console variable that can be adjusted in development builds.

This variable is defined in the VulkanRHI module and is used to determine whether the Vulkan extensions for 64-bit shader atomics should be enabled. It directly influences the behavior of FVulkanShaderAtomicInt64Extension and FVulkanShaderImageAtomicInt64Extension.

The value of GRHIAllow64bitShaderAtomicsCvar is set at initialization, but can be queried at runtime using the GetValueOnAnyThread() method.

Developers should be aware that changes to GRHIAllow64bitShaderAtomicsCvar will affect the Vulkan rendering pipeline, particularly features that rely on 64-bit atomics like Nanite.

Best practices for using GRHIAllow64bitShaderAtomicsCvar include:

  1. Use it for debugging or testing purposes in development builds.
  2. Be cautious about disabling it in shipping builds, as it may impact performance or functionality of certain features.
  3. If you need to query its value in code, use the GetValueOnAnyThread() method as demonstrated in the provided code snippets.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> GRHIAllow64bitShaderAtomicsCvar(
	TEXT("r.Vulkan.Allow64bitShaderAtomics"),
	1,
	TEXT("Whether to enable 64bit buffer/image atomics required by Nanite\n")
	TEXT("0 to disable 64bit atomics\n")
	TEXT("1 to enable (default)"),
	ECVF_ReadOnly
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// - If an extension is supported on multiple platforms, it may be cleaner to include it here and simply disable its VULKAN_SUPPORTS_* value in the Vulkan platform header where it's not supported.

TAutoConsoleVariable<int32> GRHIAllow64bitShaderAtomicsCvar(
	TEXT("r.Vulkan.Allow64bitShaderAtomics"),
	1,
	TEXT("Whether to enable 64bit buffer/image atomics required by Nanite\n")
	TEXT("0 to disable 64bit atomics\n")
	TEXT("1 to enable (default)"),
	ECVF_ReadOnly

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

Scope (from outer to inner):

file
class        class FVulkanShaderAtomicInt64Extension : public FVulkanDeviceExtension
function     FVulkanShaderAtomicInt64Extension

Source code excerpt:

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

	virtual void PrePhysicalDeviceFeatures(VkPhysicalDeviceFeatures2KHR& PhysicalDeviceFeatures2) override final
	{
		ZeroVulkanStruct(BufferAtomicFeatures, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR);
		AddToPNext(PhysicalDeviceFeatures2, BufferAtomicFeatures);

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

Scope (from outer to inner):

file
class        class FVulkanShaderImageAtomicInt64Extension : public FVulkanDeviceExtension
function     FVulkanShaderImageAtomicInt64Extension

Source code excerpt:

		: FVulkanDeviceExtension(InDevice, VK_EXT_SHADER_IMAGE_ATOMIC_INT64_EXTENSION_NAME, VULKAN_EXTENSION_ENABLED)
	{
		bEnabledInCode = bEnabledInCode && (GRHIAllow64bitShaderAtomicsCvar.GetValueOnAnyThread() != 0);
	}

	virtual void PrePhysicalDeviceFeatures(VkPhysicalDeviceFeatures2KHR& PhysicalDeviceFeatures2) override final
	{
		ZeroVulkanStruct(ImageAtomicFeatures, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_ATOMIC_INT64_FEATURES_EXT);
		AddToPNext(PhysicalDeviceFeatures2, ImageAtomicFeatures);