xr.VRS.FoveationPreview

xr.VRS.FoveationPreview

#Overview

name: xr.VRS.FoveationPreview

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 xr.VRS.FoveationPreview is to control the inclusion of foveated Variable Rate Shading (VRS) in the VRS debug overlay. This setting is part of the rendering system, specifically related to Variable Rate Shading and foveation techniques in XR (Extended Reality) applications.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the Variable Rate Shading subsystem. Based on the callsites, it’s implemented in the FoveatedImageGenerator.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1 (enabled) but can be changed at runtime through console commands or programmatically.

The xr.VRS.FoveationPreview variable interacts directly with its associated variable CVarFoveationPreview. They share the same value and are used interchangeably in the code.

Developers should be aware that this variable affects debugging and visualization rather than the actual rendering performance. It’s specifically for including foveated VRS in the debug overlay, which can be useful for development and testing but may not have a direct impact on the final rendered output in a shipping game.

Best practices when using this variable include:

  1. Use it during development and testing phases to visualize and debug foveated rendering.
  2. Remember to disable it (set to 0) in shipping builds to avoid unnecessary overhead.
  3. Use in conjunction with other VRS and foveation-related settings for a comprehensive understanding of the rendering behavior.

Regarding the associated variable CVarFoveationPreview:

The purpose of CVarFoveationPreview is to provide a programmatic interface to control the xr.VRS.FoveationPreview setting within the C++ code of the engine.

This variable is used directly in the Renderer module, specifically in the FFoveatedImageGenerator class. It’s checked in the GetDebugImage function to determine whether to return the cached foveated VRS image for debugging purposes.

The value of CVarFoveationPreview is set through the TAutoConsoleVariable template, which links it to the xr.VRS.FoveationPreview console variable.

CVarFoveationPreview interacts directly with the xr.VRS.FoveationPreview setting, essentially serving as its in-code representation.

Developers should be aware that changes to CVarFoveationPreview will affect the debug visualization of foveated VRS. It’s a render-thread safe variable, meaning it can be safely accessed and modified on the render thread.

Best practices for using CVarFoveationPreview include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Consider caching the value if it’s accessed frequently in performance-critical code paths.
  3. Be cautious about changing its value during runtime, as it may affect ongoing rendering processes.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/FoveatedImageGenerator.cpp:35

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarFoveationPreview(
	TEXT("xr.VRS.FoveationPreview"),
	1,
	TEXT("Include foveated VRS in the VRS debug overlay.")
	TEXT(" 0: Disabled;\n")
	TEXT(" 1: Enabled (default)\n"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/FoveatedImageGenerator.cpp:34

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarFoveationPreview(
	TEXT("xr.VRS.FoveationPreview"),
	1,
	TEXT("Include foveated VRS in the VRS debug overlay.")
	TEXT(" 0: Disabled;\n")
	TEXT(" 1: Enabled (default)\n"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VariableRateShading/FoveatedImageGenerator.cpp:264

Scope (from outer to inner):

file
function     FRDGTextureRef FFoveatedImageGenerator::GetDebugImage

Source code excerpt:

FRDGTextureRef FFoveatedImageGenerator::GetDebugImage(FRDGBuilder& GraphBuilder, const FViewInfo& ViewInfo, FVariableRateShadingImageManager::EVRSImageType ImageType, bool bGetSoftwareImage)
{
	if (CVarFoveationPreview.GetValueOnRenderThread() && ImageType != FVariableRateShadingImageManager::EVRSImageType::Disabled)
	{
		return CachedImage;
	}
	else
	{
		return nullptr;