r.VT.MaxUploadMemory

r.VT.MaxUploadMemory

#Overview

name: r.VT.MaxUploadMemory

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VT.MaxUploadMemory is to control the maximum amount of memory allocated for uploading virtual textures in Unreal Engine 5’s rendering system. It sets a threshold for throttling virtual texture streaming requests to manage memory usage efficiently.

This setting variable is primarily used by the Virtual Texture (VT) system, which is part of Unreal Engine’s rendering subsystem. Specifically, it is utilized in the FVirtualTextureUploadCache class, which handles the caching and uploading of virtual textures.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 64 MB but can be modified at runtime using console commands or through configuration files.

The associated variable CVarVTMaxUploadMemory directly interacts with r.VT.MaxUploadMemory. They share the same value and purpose, with CVarVTMaxUploadMemory being the actual TAutoConsoleVariable object that stores and manages the setting.

Developers must be aware that this variable sets a soft limit on memory allocation. High priority requests may cause the actual memory usage to exceed this limit temporarily. The value is in megabytes (MB), and it affects the throttling of virtual texture streaming requests.

Best practices when using this variable include:

  1. Monitoring the virtual texture memory usage in your project to set an appropriate value.
  2. Balancing between having enough memory for smooth texture streaming and not over-allocating memory that could be used elsewhere.
  3. Considering adjusting this value based on target hardware capabilities, especially for different quality settings or platforms.

Regarding the associated variable CVarVTMaxUploadMemory:

The purpose of CVarVTMaxUploadMemory is to provide programmatic access to the r.VT.MaxUploadMemory setting within the engine’s C++ code. It is the actual console variable object that stores and manages the setting value.

This variable is used in the Virtual Texture system, specifically in the FVirtualTextureUploadCache class, to determine if the current memory usage is within the set budget.

The value of CVarVTMaxUploadMemory is set when the console variable is created, but it can be modified at runtime through console commands or configuration changes.

CVarVTMaxUploadMemory interacts directly with the IsInMemoryBudget() function of FVirtualTextureUploadCache, which uses its value to determine if more virtual texture data can be uploaded without exceeding the memory budget.

Developers should be aware that this variable is accessed on the render thread, as indicated by the GetValueOnRenderThread() call. This ensures thread-safe access to the value.

Best practices for using CVarVTMaxUploadMemory include:

  1. Using GetValueOnRenderThread() when accessing the value from render thread code.
  2. Considering the impact of changing this value at runtime on performance and memory usage.
  3. Using this variable in conjunction with other Virtual Texture system settings for optimal performance tuning.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureUploadCache.cpp:26

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVTMaxUploadMemory(
	TEXT("r.VT.MaxUploadMemory"),
	64,
	TEXT("Maximum amount of upload memory to allocate in MB before throttling virtual texture streaming requests.\n")
	TEXT("We never throttle high priority requests so allocation can peak above this value."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureUploadCache.h:153

Scope (from outer to inner):

file
class        class FVirtualTextureUploadCache : public IVirtualTextureFinalizer, public FRenderResource

Source code excerpt:

	void UpdateFreeList(FRHICommandList& RHICmdList, bool bForceFreeAll = false);

	/** Returns true if underlying allocator within the budget set by r.VT.MaxUploadMemory.  */
	uint32 IsInMemoryBudget() const;

private:
	int32 GetOrCreatePoolIndex(EPixelFormat InFormat, uint32 InTileSize);

	/** Description of a single allocated tile. Carries mutable state as tile moves from uploading to submitting to pending delete. */

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureUploadCache.cpp:25

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarVTMaxUploadMemory(
	TEXT("r.VT.MaxUploadMemory"),
	64,
	TEXT("Maximum amount of upload memory to allocate in MB before throttling virtual texture streaming requests.\n")
	TEXT("We never throttle high priority requests so allocation can peak above this value."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/VT/VirtualTextureUploadCache.cpp:508

Scope (from outer to inner):

file
function     uint32 FVirtualTextureUploadCache::IsInMemoryBudget

Source code excerpt:

	return 
		PendingUpload.Num() + PendingRelease.Num() <= CVarMaxUploadRequests.GetValueOnRenderThread() &&
		TileAllocator.TotalAllocatedBytes() <= (uint32)CVarVTMaxUploadMemory.GetValueOnRenderThread() * 1024u * 1024u;
}