r.VT.PageFreeThreshold

r.VT.PageFreeThreshold

#Overview

name: r.VT.PageFreeThreshold

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.VT.PageFreeThreshold is to control the memory management of Virtual Texturing (VT) pages in Unreal Engine’s rendering system. Specifically, it determines how long a VT page should remain in memory after its last use before being considered free and available for reuse.

This setting variable is primarily used by the Virtual Texturing system, which is part of Unreal Engine’s rendering module. Based on the callsites, it’s implemented in the VirtualTextureScalability namespace, suggesting it’s closely tied to the scalability features of the Virtual Texturing system.

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

The associated variable CVarVTPageFreeThreshold directly interacts with r.VT.PageFreeThreshold. It’s the actual TAutoConsoleVariable object that holds and manages the value set by r.VT.PageFreeThreshold.

Developers should be aware that:

  1. This threshold is measured in frames, not in time units.
  2. Increasing this value reduces the chances of prematurely freeing a page that might still be in use, but it also increases memory usage.
  3. VT pages are not necessarily marked as used on the CPU every time they’re accessed by the GPU, which is why this threshold exists.

Best practices when using this variable include:

  1. Monitor performance and memory usage when adjusting this value.
  2. Consider the specific requirements of your project. Games with rapid scene changes might benefit from lower values, while more static scenes might perform better with higher values.
  3. Use in conjunction with other VT-related settings for optimal performance.

Regarding the associated variable CVarVTPageFreeThreshold: Its purpose is to provide a programmatic interface to get and set the r.VT.PageFreeThreshold value. It’s used internally by the engine to retrieve the current threshold value, as seen in the GetPageFreeThreshold() function.

The value of CVarVTPageFreeThreshold is set automatically when r.VT.PageFreeThreshold is modified through console commands. It can also be accessed and modified programmatically if needed.

Developers should be aware that CVarVTPageFreeThreshold.GetValueOnRenderThread() is used to retrieve the value, ensuring thread-safe access in render thread contexts.

Best practices for CVarVTPageFreeThreshold include using it for read-only operations in most cases, and only modifying it through the established console variable system to ensure consistency across the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureScalability.cpp:64

Scope (from outer to inner):

file
namespace    VirtualTextureScalability

Source code excerpt:


	static TAutoConsoleVariable<int32> CVarVTPageFreeThreshold(
		TEXT("r.VT.PageFreeThreshold"),
		60,
		TEXT("Number of frames since the last time a VT page was used, before it's considered free.\n")
		TEXT("VT pages are not necesarily marked as used on the CPU every time they're accessed by the GPU.\n")
		TEXT("Increasing this threshold reduces the chances that an in-use frame is considered free."),
		ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureScalability.cpp:63

Scope (from outer to inner):

file
namespace    VirtualTextureScalability

Source code excerpt:

	);

	static TAutoConsoleVariable<int32> CVarVTPageFreeThreshold(
		TEXT("r.VT.PageFreeThreshold"),
		60,
		TEXT("Number of frames since the last time a VT page was used, before it's considered free.\n")
		TEXT("VT pages are not necesarily marked as used on the CPU every time they're accessed by the GPU.\n")
		TEXT("Increasing this threshold reduces the chances that an in-use frame is considered free."),
		ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureScalability.cpp:207

Scope (from outer to inner):

file
namespace    VirtualTextureScalability
function     uint32 GetPageFreeThreshold

Source code excerpt:

	uint32 GetPageFreeThreshold()
	{
		return FMath::Max(CVarVTPageFreeThreshold.GetValueOnRenderThread(), 0);
	}

	int32 GetRuntimeVirtualTextureSizeBias(uint32 GroupIndex)
	{
		return GroupIndex < NumScalabilityGroups ? GTileCountBiases[GroupIndex] : 0;
	}