r.VT.Residency.LockedUpperBound

r.VT.Residency.LockedUpperBound

#Overview

name: r.VT.Residency.LockedUpperBound

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.Residency.LockedUpperBound is to control the Virtual Texture (VT) system’s behavior regarding mip bias in relation to locked page residency. It is used in the rendering system, specifically for managing virtual textures.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the Virtual Texture subsystem. It’s referenced in the VirtualTexturePhysicalSpace.cpp file, which is part of the VT (Virtual Texture) system.

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

The associated variable CVarVTResidencyLockedUpperBound interacts directly with r.VT.Residency.LockedUpperBound, as they share the same value. This variable is used in the UpdateResidencyTracking function of the FVirtualTexturePhysicalSpace class.

Developers must be aware that this variable affects the mip bias behavior of the Virtual Texture system. When the locked page residency exceeds the value set by this variable, the system will “kill” any mip bias. This is because locked pages are not affected by mip bias settings, making it unlikely for the pool to stay within budget if too many pages are locked.

Best practices when using this variable include:

  1. Carefully adjusting the value based on your specific use case and performance requirements.
  2. Monitoring the Virtual Texture pool’s performance and adjusting this value if you notice issues with memory usage or rendering quality.
  3. Considering this variable in conjunction with other VT residency-related variables for optimal performance.

Regarding the associated variable CVarVTResidencyLockedUpperBound:

The purpose of CVarVTResidencyLockedUpperBound is to provide a programmatic way to access and modify the r.VT.Residency.LockedUpperBound setting within the C++ code.

This variable is used in the Renderer module, specifically in the Virtual Texture system. It’s defined and used in the VirtualTexturePhysicalSpace.cpp file.

The value of CVarVTResidencyLockedUpperBound is set when the console variable r.VT.Residency.LockedUpperBound is initialized. It can be accessed in the C++ code using the GetValueOnRenderThread() method.

CVarVTResidencyLockedUpperBound interacts directly with r.VT.Residency.LockedUpperBound, as they represent the same setting. It’s used alongside other residency-related variables in the UpdateResidencyTracking function.

Developers should be aware that this variable provides thread-safe access to the setting value on the render thread. It’s important to use the GetValueOnRenderThread() method when accessing this variable to ensure thread safety.

Best practices for using CVarVTResidencyLockedUpperBound include:

  1. Always access its value using the GetValueOnRenderThread() method in render thread code.
  2. Consider caching the value if it’s used frequently in performance-critical sections of code.
  3. Be aware of potential performance implications when modifying this value, as it affects the Virtual Texture system’s behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTexturePhysicalSpace.cpp:40

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarVTResidencyLockedUpperBound(
	TEXT("r.VT.Residency.LockedUpperBound"),
	0.65f,
	TEXT("Virtual Texture pool locked page residency above which we kill any mip bias.\n")
	TEXT("That's because locked pages are never affected by the mip bias setting. So it is unlikely that we can get the pool within budget.\n")
	TEXT("Default 0.65"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTexturePhysicalSpace.cpp:39

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarVTResidencyLockedUpperBound(
	TEXT("r.VT.Residency.LockedUpperBound"),
	0.65f,
	TEXT("Virtual Texture pool locked page residency above which we kill any mip bias.\n")
	TEXT("That's because locked pages are never affected by the mip bias setting. So it is unlikely that we can get the pool within budget.\n")
	TEXT("Default 0.65"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VT/VirtualTexturePhysicalSpace.cpp:216

Scope (from outer to inner):

file
function     void FVirtualTexturePhysicalSpace::UpdateResidencyTracking

Source code excerpt:

void FVirtualTexturePhysicalSpace::UpdateResidencyTracking(uint32 Frame)
{
	float LockedUpperBound = CVarVTResidencyLockedUpperBound.GetValueOnRenderThread();
	float LowerBound = CVarVTResidencyLowerBound.GetValueOnRenderThread();
	float UpperBound = CVarVTResidencyUpperBound.GetValueOnRenderThread();
	float AdjustmentRate = CVarVTResidencyAdjustmentRate.GetValueOnRenderThread();
	float MaxMipMapBias = CVarVTResidencyMaxMipMapBias.GetValueOnRenderThread();

	const uint32 NumPages = Pool.GetNumPages();