r.VT.AVT.MaxPageResidency

r.VT.AVT.MaxPageResidency

#Overview

name: r.VT.AVT.MaxPageResidency

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

• type: Var
• help: Percentage of page table to allocate before we start freeing to make space

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VT.AVT.MaxPageResidency is to control the maximum page residency for Adaptive Virtual Texturing (AVT) in Unreal Engine’s rendering system. It sets a threshold for the percentage of the page table that can be allocated before the engine starts freeing space.

This setting variable is primarily used by the Renderer module, specifically within the Adaptive Virtual Texturing system. The code references are found in the AdaptiveVirtualTexture.cpp file, which is part of the rendering subsystem.

The value of this variable is set as a console variable with a default value of 75. It can be changed at runtime through the console or configuration files.

The associated variable CVarAVTMaxPageResidency directly interacts with r.VT.AVT.MaxPageResidency. They share the same value and purpose.

Developers must be aware that this variable affects the memory management of virtual textures. Setting it too high might lead to excessive memory usage, while setting it too low could cause frequent page swapping and potential performance issues.

Best practices when using this variable include:

1. Adjusting it based on the available system memory and the complexity of your virtual texturing needs.
2. Monitoring performance and memory usage when changing this value.
3. Considering the trade-off between memory usage and texture streaming performance.

Regarding the associated variable CVarAVTMaxPageResidency:

The purpose of CVarAVTMaxPageResidency is identical to r.VT.AVT.MaxPageResidency. It’s an internal representation of the console variable within the engine’s code.

This variable is used directly in the FAdaptiveVirtualTexture::UpdateAllocations function to calculate the target number of pages for allocation. It’s clamped between 10% and 95% to ensure a reasonable range of values.

The value is retrieved using GetValueOnRenderThread(), indicating that it’s accessed from the render thread for thread-safe operations.

Developers should be aware that changes to r.VT.AVT.MaxPageResidency will directly affect the behavior controlled by CVarAVTMaxPageResidency.

Best practices for CVarAVTMaxPageResidency include:

1. Avoid directly modifying this variable in code; instead, use the r.VT.AVT.MaxPageResidency console variable.
2. When reading its value, always use GetValueOnRenderThread() if operating on the render thread to ensure thread safety.
3. Consider the impact on performance and memory usage when adjusting this value, as it directly affects the virtual texture page allocation strategy.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/AdaptiveVirtualTexture.cpp:24

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAVTMaxPageResidency(
	TEXT("r.VT.AVT.MaxPageResidency"),
	75,
	TEXT("Percentage of page table to allocate before we start freeing to make space"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarAVTAgeToFree(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/AdaptiveVirtualTexture.cpp:23

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarAVTMaxPageResidency(
	TEXT("r.VT.AVT.MaxPageResidency"),
	75,
	TEXT("Percentage of page table to allocate before we start freeing to make space"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/AdaptiveVirtualTexture.cpp:691

Scope (from outer to inner):

file
function     void FAdaptiveVirtualTexture::UpdateAllocations

Source code excerpt:

		FVirtualTextureSpace* Space = InSystem->GetSpace(GetSpaceID());
		const uint32 TotalPages = Space->GetDescription().MaxSpaceSize * Space->GetDescription().MaxSpaceSize;
		const uint32 ResidencyPercent = FMath::Clamp(CVarAVTMaxPageResidency.GetValueOnRenderThread(), 10, 95);
		const uint32 TargetPages = TotalPages * ResidencyPercent / 100;
		const int32 NumToFree = FMath::Min(NumAllocated, CVarAVTMaxFreePerFrame.GetValueOnRenderThread());

		bool bFreeSuccess = true;
		for (int32 FreeCount = 0; bFreeSuccess && FreeCount < NumToFree && Space->GetAllocator().GetNumAllocatedPages() > TargetPages; FreeCount++)
		{