r.VRS.Preview

r.VRS.Preview

#Overview

name: r.VRS.Preview

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VRS.Preview is to enable a debug visualization of the Variable Rate Shading (VRS) shading rate image texture in Unreal Engine 5. It is primarily used for the rendering system, specifically for the Variable Rate Shading feature.

This setting variable is relied upon by the Renderer module of Unreal Engine 5, particularly within the Variable Rate Shading subsystem. The code references are found in the VariableRateShadingImageManager.cpp file, which is part of the renderer’s implementation of VRS.

The value of this variable is set through a console command, as it is defined as a TAutoConsoleVariable. It can be changed at runtime using the console or through code that accesses console variables.

The variable interacts closely with its associated variable CVarVRSPreview, which is the actual ConsoleVariable object. They share the same value and purpose.

Developers must be aware that this variable is intended for debugging and visualization purposes. It offers different modes of preview: 0 - off 1 - full (hardware) 2 - conservative (hardware) 3 - full (software) 4 - conservative (software)

The “conservative” and “software” options are only available when using Contrast Adaptive Shading.

Best practices when using this variable include:

  1. Use it primarily for debugging and performance optimization of VRS.
  2. Be aware that enabling the preview may impact performance, so it should be disabled in release builds.
  3. Understand the differences between hardware and software VRS implementations when interpreting the visualization.
  4. Use in conjunction with other VRS-related settings and tools for a comprehensive understanding of VRS behavior in your game.

Regarding the associated variable CVarVRSPreview:

The purpose of CVarVRSPreview is to serve as the actual console variable object that controls the VRS preview functionality. It is used internally by the engine to store and retrieve the current preview state.

This variable is used within the FDebugVariableRateShadingCS class, which is likely responsible for rendering the debug visualization. The value of CVarVRSPreview is retrieved on the render thread to determine the type of preview to display.

Developers should be aware that modifying CVarVRSPreview directly (instead of through the console command) may require proper synchronization with the render thread to ensure thread-safe access.

Best practices for CVarVRSPreview include:

  1. Prefer using the console command “r.VRS.Preview” to modify the value rather than directly accessing CVarVRSPreview.
  2. When reading the value in code, use the appropriate thread-safe methods provided by the TAutoConsoleVariable class.
  3. Be cautious about caching the value, as it can be changed at runtime through the console.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/VariableRateShadingImageManager.cpp:40

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarVRSPreview(
	TEXT("r.VRS.Preview"),
	0,
	TEXT("Show a debug visualization of the VRS shading rate image texture. Conservative and software images are only available via Contrast Adaptive Shading.")
	TEXT("0 - off, 1 - full (hardware), 2 - conservative (hardware), 3 - full (software), 4 - conservative (software)"),
	FConsoleVariableDelegate::CreateStatic(&CVarVRSPreviewCallback),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/VariableRateShadingImageManager.cpp:39

Scope: file

Source code excerpt:

}

TAutoConsoleVariable<int32> CVarVRSPreview(
	TEXT("r.VRS.Preview"),
	0,
	TEXT("Show a debug visualization of the VRS shading rate image texture. Conservative and software images are only available via Contrast Adaptive Shading.")
	TEXT("0 - off, 1 - full (hardware), 2 - conservative (hardware), 3 - full (software), 4 - conservative (software)"),
	FConsoleVariableDelegate::CreateStatic(&CVarVRSPreviewCallback),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/VariableRateShadingImageManager.cpp:547

Scope (from outer to inner):

file
class        class FDebugVariableRateShadingCS : public FGlobalShader

Source code excerpt:

	}

	uint32 ImageTypeAsInt = CVarVRSPreview.GetValueOnRenderThread();
	EVRSImageType PreviewImageType = EVRSImageType::Disabled;
	bool bUseSoftwareImage = false;
	
	switch (ImageTypeAsInt)
	{
		// Full hardware