r.Vulkan.VRSFormat

r.Vulkan.VRSFormat

#Overview

name: r.Vulkan.VRSFormat

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Vulkan.VRSFormat is to control the preferred Variable Rate Shading (VRS) option in the Vulkan rendering pipeline. This setting is primarily used for the rendering system, specifically for managing Variable Rate Shading techniques.

This setting variable is mainly relied upon by the Vulkan RHI (Runtime Hardware Interface) module of Unreal Engine 5. It’s used in the VulkanRHI subsystem to determine which VRS method to use when multiple options are available.

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 closely with another variable named GVulkanVariableRateShadingFormatCVar. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the choice between Fragment Shading Rate (FSR) and Fragment Density Map (FDM) when both are available. The value of this variable determines which technique is preferred or required:

0: Prefer FSR if both FSR and FDM are available 1: Use FSR if available, report a message if not 2: Require FSR, generate an error if not available 3: Prefer FDM if both FSR and FDM are available

Best practices when using this variable include:

  1. Consider the hardware capabilities of target platforms when setting this value.
  2. Be aware that forcing a specific VRS method might lead to errors or suboptimal performance on some hardware.
  3. Use the console variable system to experiment with different settings during development.

Regarding the associated variable GVulkanVariableRateShadingFormatCVar:

The purpose of GVulkanVariableRateShadingFormatCVar is to provide a runtime-configurable way to set and access the VRS format preference. It’s defined as a TAutoConsoleVariable, which allows it to be changed through console commands.

This variable is used in the same Vulkan RHI module as r.Vulkan.VRSFormat. It’s primarily used in the initialization of Vulkan extensions related to VRS.

The value of this variable is set when it’s defined, but can be changed at runtime using console commands.

GVulkanVariableRateShadingFormatCVar interacts directly with the VRS-related Vulkan extensions. It’s used to determine whether certain extensions should be enabled based on the preferred VRS method.

Developers should be aware that changes to this variable can affect the initialization of Vulkan extensions, potentially impacting rendering performance or compatibility.

Best practices for using this variable include:

  1. Use it in conjunction with other Vulkan and rendering settings for optimal performance.
  2. Be cautious when changing its value at runtime, as it may affect already initialized Vulkan extensions.
  3. Consider platform-specific requirements when setting or changing this value.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:1153, section: [Oculus_Quest DeviceProfile]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> GVulkanVariableRateShadingFormatCVar(
	TEXT("r.Vulkan.VRSFormat"),
	0,
	TEXT("Allows to choose the preferred Variable Rate Shading option. \n")
	TEXT("0: Prefer Fragment Shading Rate if both Fragment Shading Rate and Fragment Density Map are available.\n")
	TEXT("1: Use Fragment Shading Rate if available. A message will be reported if not available. \n")
	TEXT("2: Require Fragment Shading Rate. Will generate an error if the extension is not available. \n")
	TEXT("3: Prefer Fragment Density Map if both Fragment Shading Rate and Fragment Density Map are available.\n")

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

Scope (from outer to inner):

file
function     void FVulkanDevice::ChooseVariableRateShadingMethod

Source code excerpt:

	};

	int32 VRSFormatPreference = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Vulkan.VRSFormat"))->GetValueOnAnyThread();
	UE_LOG(LogVulkanRHI, Display, TEXT("Vulkan Variable Rate Shading choice: %d."), VRSFormatPreference);

	// If both FSR and FDM are available we turn off the one that we're not using to prevent Vulkan validation layers warnings.
	if (IsFragmentDensityMapAvailable(OptionalDeviceExtensions) && IsFragmentShadingRateAvailable(OptionalDeviceExtensionProperties.FragmentShadingRateFeatures))
	{
		if (VRSFormatPreference <= (uint8)EVulkanVariableRateShadingPreference::RequireFSR)

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> GVulkanVariableRateShadingFormatCVar(
	TEXT("r.Vulkan.VRSFormat"),
	0,
	TEXT("Allows to choose the preferred Variable Rate Shading option. \n")
	TEXT("0: Prefer Fragment Shading Rate if both Fragment Shading Rate and Fragment Density Map are available.\n")
	TEXT("1: Use Fragment Shading Rate if available. A message will be reported if not available. \n")
	TEXT("2: Require Fragment Shading Rate. Will generate an error if the extension is not available. \n")

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

Scope (from outer to inner):

file
class        class FVulkanKHRFragmentShadingRateExtension : public FVulkanDeviceExtension
function     FVulkanKHRFragmentShadingRateExtension

Source code excerpt:

		: FVulkanDeviceExtension(InDevice, VK_KHR_FRAGMENT_SHADING_RATE_EXTENSION_NAME, VULKAN_EXTENSION_ENABLED)
	{
		int32 VRSFormatPreference = GVulkanVariableRateShadingFormatCVar->GetInt();
		bEnabledInCode = bEnabledInCode && GRHIVariableRateShadingEnabled;
		// FSR should be enabled even if FDM is preferred because it could be not available.
		bEnabledInCode &= (VRSFormatPreference <= (uint8) EVulkanVariableRateShadingPreference::RequireFSR || VRSFormatPreference == (uint8)EVulkanVariableRateShadingPreference::PreferFDM);
	}

	virtual void PrePhysicalDeviceProperties(VkPhysicalDeviceProperties2KHR& PhysicalDeviceProperties2) override final

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

Scope (from outer to inner):

file
class        class FVulkanEXTFragmentDensityMapExtension : public FVulkanDeviceExtension
function     FVulkanEXTFragmentDensityMapExtension

Source code excerpt:

		: FVulkanDeviceExtension(InDevice, VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME, VULKAN_EXTENSION_ENABLED)
	{
		int32 VRSFormatPreference = GVulkanVariableRateShadingFormatCVar->GetInt();
		bEnabledInCode = bEnabledInCode && GRHIVariableRateShadingEnabled;
		// FDM should be enabled even if the preferred choice is FSR because that might not be available.
		bEnabledInCode &= (VRSFormatPreference >= (uint8) EVulkanVariableRateShadingPreference::PreferFDM || VRSFormatPreference == (uint8) EVulkanVariableRateShadingPreference::PreferFSR);
	}

	virtual void PrePhysicalDeviceProperties(VkPhysicalDeviceProperties2KHR& PhysicalDeviceProperties2) override final

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

Scope (from outer to inner):

file
class        class FVulkanEXTFragmentDensityMapExtension : public FVulkanDeviceExtension
function     virtual void PostPhysicalDeviceProperties

Source code excerpt:

		// Fragment Density Map is the preferred user choice.
		// NOTE: FVulkanKHRFragmentShadingRateExtension must be placed before FVulkanEXTFragmentDensityMapExtension for this to work!
		if ((!GRHISupportsAttachmentVariableRateShading || (GVulkanVariableRateShadingFormatCVar->GetInt() >= (uint8) EVulkanVariableRateShadingPreference::PreferFDM)) && bRequirementsPassed)
		{
			GRHISupportsAttachmentVariableRateShading = true;

			// Go with the smallest tile size for now, and also force to square, since this seems to be standard.
			// TODO: Eventually we may want to surface the range of possible tile sizes depending on end use cases, but for now this is being used for foveated rendering and smallest tile size
			// is preferred.