r.VT.MaxUploadsPerFrame.Streaming

r.VT.MaxUploadsPerFrame.Streaming

#Overview

name: r.VT.MaxUploadsPerFrame.Streaming

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.MaxUploadsPerFrame.Streaming is to control the maximum number of page uploads per frame for streaming Virtual Textures (VTs) in Unreal Engine 5. It is primarily used for managing the performance and resource allocation of the Virtual Texturing system, which is a part of the rendering subsystem.

This setting variable is utilized by the Virtual Texturing system within Unreal Engine’s rendering module. It’s specifically related to the streaming aspect of Virtual Textures, which is crucial for efficient texture management in large-scale environments.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable, which allows it to be adjusted at runtime through console commands or configuration files.

This variable interacts closely with another console variable, r.VT.MaxUploadsPerFrame. When r.VT.MaxUploadsPerFrame.Streaming is set to zero, the streaming VTs are limited by r.VT.MaxUploadsPerFrame along with other types of VTs.

Developers must be aware of several important aspects when using this variable:

  1. A positive value sets a specific limit on streaming VT uploads per frame.
  2. A negative value means no limit is applied.
  3. A zero value reverts to the old behavior where streaming VTs are not budgeted separately.
  4. This setting is render thread safe and can be adjusted for scalability.

Best practices when using this variable include:

  1. Set a high limit if streaming pages is slow to prevent I/O request throttling.
  2. Adjust the value based on the specific needs of your project and target hardware capabilities.
  3. Monitor performance impacts when changing this value, especially on lower-end hardware.
  4. Consider the interaction with r.VT.MaxUploadsPerFrame when fine-tuning Virtual Texture performance.

Regarding the associated variable CVarVTMaxUploadsPerFrameStreaming:

This is the actual console variable object that corresponds to r.VT.MaxUploadsPerFrame.Streaming. It’s used internally by the engine to store and retrieve the current value of the setting. The purpose and usage are identical to r.VT.MaxUploadsPerFrame.Streaming.

The value of CVarVTMaxUploadsPerFrameStreaming is accessed in the GetMaxUploadsPerFrameForStreamingVT() function, which likely controls the actual implementation of the upload limit in the Virtual Texturing system.

When working with this variable, developers should:

  1. Use CVarVTMaxUploadsPerFrameStreaming.GetValueOnAnyThread() to retrieve the current value safely from any thread.
  2. Be aware that a value less than 0 is treated as MAX_int32, effectively removing the upload limit.
  3. Consider the potential impact on editor performance, as there appears to be special handling for editor builds (indicated by the #if WITH_EDITOR preprocessor directive).

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

Scope (from outer to inner):

file
namespace    VirtualTextureScalability

Source code excerpt:


	static TAutoConsoleVariable<int32> CVarVTMaxUploadsPerFrameStreaming(
		TEXT("r.VT.MaxUploadsPerFrame.Streaming"),
		0,
		TEXT("If positive, max number of page uploads per frame in game for streaming VT. Negative means no limit.\n")
		TEXT("If zero, SVTs won't be budgeted separately. They will be limited by r.VT.MaxUploadsPerFrame along with other types of VTs. This is the old behavior.\n")
		TEXT("This limit should be high if streaming pages is slow so that I/O requests are not throttled which can cause long delays to acquire page data."),
		ECVF_RenderThreadSafe | ECVF_Scalability
	);

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    VirtualTextureScalability

Source code excerpt:

	);

	static TAutoConsoleVariable<int32> CVarVTMaxUploadsPerFrameStreaming(
		TEXT("r.VT.MaxUploadsPerFrame.Streaming"),
		0,
		TEXT("If positive, max number of page uploads per frame in game for streaming VT. Negative means no limit.\n")
		TEXT("If zero, SVTs won't be budgeted separately. They will be limited by r.VT.MaxUploadsPerFrame along with other types of VTs. This is the old behavior.\n")
		TEXT("This limit should be high if streaming pages is slow so that I/O requests are not throttled which can cause long delays to acquire page data."),
		ECVF_RenderThreadSafe | ECVF_Scalability

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

Scope (from outer to inner):

file
namespace    VirtualTextureScalability
function     int32 GetMaxUploadsPerFrameForStreamingVT

Source code excerpt:

	int32 GetMaxUploadsPerFrameForStreamingVT()
	{
		int32 Budget = CVarVTMaxUploadsPerFrameStreaming.GetValueOnAnyThread();

		if (Budget < 0)
		{
			Budget = MAX_int32;
		}
#if WITH_EDITOR