r.VT.UploadMemoryPageSize

r.VT.UploadMemoryPageSize

#Overview

name: r.VT.UploadMemoryPageSize

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

• type: Var
• help: Size in MB for a single page of virtual texture upload memory.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VT.UploadMemoryPageSize is to control the size of a single page of virtual texture upload memory in the Unreal Engine 5 rendering system. This setting is specifically related to the Virtual Texturing (VT) system, which is a part of the engine’s advanced rendering capabilities.

This setting variable is primarily used in the Engine module, specifically within the Virtual Texture subsystem. Based on the callsites, it’s clear that this variable is utilized in the VirtualTextureUploadCache.cpp file, which is responsible for managing the upload of virtual textures.

The value of this variable is set through a console variable (CVarVTUploadMemoryPageSize) with a default value of 4 MB. It can be modified at runtime through console commands or programmatically.

The associated variable CVarVTUploadMemoryPageSize interacts directly with r.VT.UploadMemoryPageSize, as they share the same value. This console variable is used to retrieve the value in the C++ code.

Developers should be aware that this variable affects the memory allocation for virtual texture uploads. Changing this value will impact the size of memory pages used for uploading virtual textures, which can affect performance and memory usage.

Best practices when using this variable include:

1. Carefully consider changes to this value, as it can impact memory usage and performance.
2. Monitor performance metrics when adjusting this value to find the optimal setting for your specific use case.
3. Be mindful of platform-specific memory constraints when modifying this value.

Regarding the associated variable CVarVTUploadMemoryPageSize:

The purpose of CVarVTUploadMemoryPageSize is to provide a programmatic interface to access and modify the r.VT.UploadMemoryPageSize setting within the C++ code of the engine.

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

The value of CVarVTUploadMemoryPageSize is set when the console variable is initialized, with a default value of 4. It can be modified at runtime through console commands or programmatically.

CVarVTUploadMemoryPageSize directly interacts with r.VT.UploadMemoryPageSize, as they represent the same setting.

Developers should be aware that this console variable provides a thread-safe way to access the upload memory page size setting. It’s marked as render thread safe (ECVF_RenderThreadSafe), which is important for maintaining thread safety when accessing this value.

Best practices when using CVarVTUploadMemoryPageSize include:

1. Use GetValueOnRenderThread() when accessing the value from the render thread.
2. Be cautious when modifying this value at runtime, as it can affect ongoing virtual texture operations.
3. Consider exposing this setting in user-facing graphics options if fine-tuning is necessary for different hardware configurations.

#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:19

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarVTUploadMemoryPageSize(
	TEXT("r.VT.UploadMemoryPageSize"),
	4,
	TEXT("Size in MB for a single page of virtual texture upload memory."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarVTMaxUploadMemory(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DECLARE_MEMORY_STAT(TEXT("Total CPU Upload Memory"), STAT_TotalCPUUploadSize, STATGROUP_VirtualTextureMemory);

static TAutoConsoleVariable<int32> CVarVTUploadMemoryPageSize(
	TEXT("r.VT.UploadMemoryPageSize"),
	4,
	TEXT("Size in MB for a single page of virtual texture upload memory."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FVTUploadTileAllocator::FStagingBuffer::Init

Source code excerpt:

	TileSizeAligned = Align(InTileSizeBytes, 128u);

	const uint32 RequestedBufferSize = CVarVTUploadMemoryPageSize.GetValueOnRenderThread() * 1024 * 1024;
	NumTiles = FMath::DivideAndRoundUp(RequestedBufferSize, TileSizeAligned);
	const uint32 BufferSize = TileSizeAligned * NumTiles;

	check(TileFreeList.Num() == 0);
	TileFreeList.AddUninitialized(NumTiles);
	for (uint32 Index = 0; Index < NumTiles; ++Index)