xr.VRS.FoveationLevel

xr.VRS.FoveationLevel

#Overview

name: xr.VRS.FoveationLevel

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

• type: Var
• help: Level of foveated VRS to apply (when Variable Rate Shading is available)\n 0: Disabled (default);\n 1: Low;\n 2: Medium;\n 3: High;\n 4: High Top;\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of xr.VRS.FoveationLevel is to control the level of foveated Variable Rate Shading (VRS) applied in XR (Extended Reality) rendering. This setting variable is part of the rendering system, specifically for optimizing performance in XR applications.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the Variable Rate Shading subsystem. It’s implemented in the FoveatedImageGenerator class, which is responsible for generating foveated images for XR rendering.

The value of this variable is set through a console variable (CVar) system. It can be set programmatically or through console commands. The default value is 0, which disables foveated VRS.

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

Developers must be aware of the following when using this variable:

1. The variable accepts integer values from 0 to 4, representing different levels of foveation.
2. The foveation levels are: 0 (Disabled), 1 (Low), 2 (Medium), 3 (High), and 4 (presumably Very High, though not explicitly stated in the comments).
3. This variable is specific to XR rendering and may not have an effect on non-XR views.
4. The actual foveation level applied can be dynamically adjusted based on performance requirements when dynamic foveation is enabled.

Best practices when using this variable include:

1. Start with lower foveation levels and increase as needed to balance performance and visual quality.
2. Test thoroughly in various XR scenarios to ensure the chosen foveation level doesn’t negatively impact the user experience.
3. Consider using dynamic foveation (controlled by CVarDynamicFoveation) to automatically adjust the foveation level based on performance.
4. Be aware that higher foveation levels may result in noticeable visual artifacts, especially in the periphery of the user’s vision.

Regarding the associated variable CVarFoveationLevel:

• Its purpose is to provide a programmatic interface to control the foveation level within the C++ code.
• It’s used directly in the Renderer module, specifically in the FoveatedImageGenerator class.
• Its value is set through the CVar system and can be accessed using GetValueOnAnyThread() or GetValueOnRenderThread() methods.
• It interacts directly with xr.VRS.FoveationLevel, effectively serving as its in-code representation.
• Developers should use this variable when they need to read or modify the foveation level within C++ code, particularly in render thread operations.
• Best practices include using the appropriate thread-safe getter method (GetValueOnAnyThread() or GetValueOnRenderThread()) depending on the context in which the value is being accessed.

#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:16

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int> CVarFoveationLevel(
	TEXT("xr.VRS.FoveationLevel"),
	0,
	TEXT("Level of foveated VRS to apply (when Variable Rate Shading is available)\n")
	TEXT(" 0: Disabled (default);\n")
	TEXT(" 1: Low;\n")
	TEXT(" 2: Medium;\n")
	TEXT(" 3: High;\n")

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

/* CVar values used to control generator behavior */

static TAutoConsoleVariable<int> CVarFoveationLevel(
	TEXT("xr.VRS.FoveationLevel"),
	0,
	TEXT("Level of foveated VRS to apply (when Variable Rate Shading is available)\n")
	TEXT(" 0: Disabled (default);\n")
	TEXT(" 1: Low;\n")
	TEXT(" 2: Medium;\n")

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

Scope (from outer to inner):

file
function     void FFoveatedImageGenerator::PrepareImages

Source code excerpt:

	static const TArray<float> kFixedFoveationCenterY = { 0.5f, 0.5f, 0.5f, 0.5f, 0.42f };

	const int VRSMaxLevel = FMath::Clamp(CVarFoveationLevel.GetValueOnAnyThread(), 0, 4);

	// Set up dynamic VRS amount based on target framerate and use it to interpolate cutoffs (default to max level)
	float VRSDynamicAmount = 1.0f;
	if (CVarDynamicFoveation.GetValueOnAnyThread() && VRSMaxLevel > 0)
	{
		VRSDynamicAmount = UpdateDynamicVRSAmount();

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

Scope (from outer to inner):

file
function     bool FFoveatedImageGenerator::IsEnabled

Source code excerpt:

bool FFoveatedImageGenerator::IsEnabled() const
{
	return CVarFoveationLevel.GetValueOnRenderThread() > 0;
}

bool FFoveatedImageGenerator::IsSupportedByView(const FSceneView& View) const
{
	// Only used for XR views
	return true; // IStereoRendering::IsStereoEyeView(View);