r.VT.MaskedPageTableUpdates

r.VT.MaskedPageTableUpdates

#Overview

name: r.VT.MaskedPageTableUpdates

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

• type: Var
• help: Masks the page table update quads to reduce pixel fill costs

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VT.MaskedPageTableUpdates is to control the masking of page table update quads in the Virtual Texturing system of Unreal Engine 5. This setting is primarily used for optimizing the rendering performance by reducing pixel fill costs associated with virtual texture page table updates.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the Virtual Texturing (VT) subsystem. It is referenced in the VirtualTextureSpace.cpp file, which is part of the core rendering functionality for virtual textures.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1, meaning the masking is enabled by default. Developers can change this value at runtime using console commands or through project settings.

The associated variable CVarVTMaskedPageTableUpdates directly interacts with r.VT.MaskedPageTableUpdates. They share the same value and purpose.

Developers must be aware that this variable affects the performance of virtual texture rendering. When enabled (set to 1), it uses a masked approach for page table updates, which can reduce pixel fill costs. When disabled (set to 0), it uses a different method (ExpandPageTableUpdatePainters) which might have different performance characteristics.

Best practices when using this variable include:

1. Keeping it enabled (1) for most scenarios, as it’s the default and optimized setting.
2. Only disabling it if specific performance issues are observed or if a different update method is required for certain use cases.
3. Profiling the application with both settings to determine which performs better in the specific use case.

Regarding the associated variable CVarVTMaskedPageTableUpdates:

The purpose of CVarVTMaskedPageTableUpdates is identical to r.VT.MaskedPageTableUpdates. It’s the actual console variable implementation that controls the behavior described above.

This variable is used within the Renderer module, specifically in the VirtualTextureSpace.cpp file. It’s checked during the ApplyUpdates function of the FVirtualTextureSpace class to determine which page table update method to use.

The value of CVarVTMaskedPageTableUpdates is set through the console variable system and can be modified at runtime.

There are no other variables directly interacting with CVarVTMaskedPageTableUpdates besides r.VT.MaskedPageTableUpdates.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarVTMaskedPageTableUpdates are the same as those for r.VT.MaskedPageTableUpdates, as they are essentially the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTextureSpace.cpp:28

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarVTMaskedPageTableUpdates(
	TEXT("r.VT.MaskedPageTableUpdates"),
	1,
	TEXT("Masks the page table update quads to reduce pixel fill costs"),
	ECVF_RenderThreadSafe
	);

static EPixelFormat GetFormatForNumLayers(uint32 NumLayers, EVTPageTableFormat Format)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTextureSpace.cpp:27

Scope: file

Source code excerpt:

	);

static TAutoConsoleVariable<int32> CVarVTMaskedPageTableUpdates(
	TEXT("r.VT.MaskedPageTableUpdates"),
	1,
	TEXT("Masks the page table update quads to reduce pixel fill costs"),
	ECVF_RenderThreadSafe
	);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTextureSpace.cpp:386

Scope (from outer to inner):

file
function     void FVirtualTextureSpace::ApplyUpdates

Source code excerpt:

			for (const FPageTableUpdate& Update : PageTableUpdates[LayerIndex])
			{
				if (CVarVTMaskedPageTableUpdates.GetValueOnRenderThread())
				{
					PageMap.ExpandPageTableUpdateMasked(System, Update, ExpandedUpdates[LayerIndex]);
				}
				else
				{
					PageMap.ExpandPageTableUpdatePainters(System, Update, ExpandedUpdates[LayerIndex]);