r.VirtualTexture

r.VirtualTexture

#Overview

name: r.VirtualTexture

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.VirtualTexture is to enable or disable virtual texturing for texture resources in Unreal Engine. Virtual texturing allows textures to use virtual memory, enabling them to be partially resident in memory, which can significantly improve memory management and performance for large or complex textures.

This setting variable is primarily used by the rendering system, specifically in the texture streaming and resource management subsystems of Unreal Engine. Based on the callsites, it’s evident that the Engine module relies on this variable, particularly in the texture resource and derived data generation processes.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1 (enabled) but can be changed at runtime or through configuration files.

The r.VirtualTexture variable interacts closely with its associated variable CVarVirtualTextureEnabled. They share the same value and are used interchangeably in different parts of the engine code.

Developers must be aware of several things when using this variable:

  1. It affects texture memory management and can impact performance and memory usage.
  2. It’s platform-dependent, as indicated by the check for bPlatformSupportsVirtualTextureStreaming.
  3. It can influence the generation of derived data for textures.
  4. Some texture types (like ULightMapVirtualTexture2D) may behave differently with this setting.

Best practices when using this variable include:

  1. Ensure it’s enabled (set to 1) for projects that benefit from virtual texturing, especially those with large or numerous textures.
  2. Be cautious when changing this value at runtime, as it can affect ongoing texture streaming operations.
  3. Consider platform limitations and test thoroughly on target platforms.
  4. Be aware of its interaction with other texture-related settings and flags.

Regarding the associated variable CVarVirtualTextureEnabled: The purpose of CVarVirtualTextureEnabled is to provide a runtime-accessible way to check and modify the virtual texturing setting. It’s defined using TAutoConsoleVariable, which allows it to be changed via console commands or configuration files.

This variable is used directly in the texture resource management system to determine if textures can be created with partially resident mips. It’s checked in various parts of the engine to enable or disable virtual texturing features.

The value of CVarVirtualTextureEnabled is set at initialization but can be modified at runtime through the console or configuration systems.

Developers should be aware that changes to CVarVirtualTextureEnabled will immediately affect the behavior of texture resource creation and management. It’s important to understand the performance implications of enabling or disabling virtual texturing, especially in a running game.

Best practices for CVarVirtualTextureEnabled include:

  1. Use it for debugging or performance testing scenarios.
  2. Be cautious about changing its value in shipping builds, as it can significantly affect memory usage and performance.
  3. Consider exposing it as a configurable option for end-users only if there’s a compelling reason to do so.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/StreamableTextureResource.cpp:18

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVirtualTextureEnabled(
	TEXT("r.VirtualTexture"),
	1,
	TEXT("If set to 1, textures will use virtual memory so they can be partially resident."),
	ECVF_RenderThreadSafe);

bool CanCreateWithPartiallyResidentMips(ETextureCreateFlags TexCreateFlags)
{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedData.cpp:950

Scope (from outer to inner):

file
function     static void GetTextureBuildSettings

Source code excerpt:


	static const auto CVarVirtualTexturesEnabled = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTextures")); check(CVarVirtualTexturesEnabled);
	// A ULightMapVirtualTexture2D with multiple layers saved in MapBuildData could be loaded with the r.VirtualTexture disabled, it will generate DDC before we decide to invalidate the light map data, to skip the ensure failure let it generate VT DDC anyway.
	const bool bForVirtualTextureStreamingBuild = ULightMapVirtualTexture2D::StaticClass() == Texture.GetClass();
	bool bVirtualTextureStreaming = bForVirtualTextureStreamingBuild || (CVarVirtualTexturesEnabled->GetValueOnAnyThread() && bPlatformSupportsVirtualTextureStreaming && Texture.VirtualTextureStreaming);
	if (Texture.Availability == ETextureAvailability::CPU && TextureClass == ETextureClass::TwoD)
	{
		// We are swapping with a placeholder - don't VT it.
		OutBuildSettings.bCPUAccessible = true;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/StreamableTextureResource.cpp:17

Scope: file

Source code excerpt:

#endif

static TAutoConsoleVariable<int32> CVarVirtualTextureEnabled(
	TEXT("r.VirtualTexture"),
	1,
	TEXT("If set to 1, textures will use virtual memory so they can be partially resident."),
	ECVF_RenderThreadSafe);

bool CanCreateWithPartiallyResidentMips(ETextureCreateFlags TexCreateFlags)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/StreamableTextureResource.cpp:36

Scope (from outer to inner):

file
function     bool CanCreateWithPartiallyResidentMips

Source code excerpt:

		TexCreate_OfflineProcessed;

	return ((TexCreateFlags & (iDisableFlags | iRequiredFlags)) == iRequiredFlags) && CVarVirtualTextureEnabled.GetValueOnAnyThread();
	
#else
	return false;
#endif
}