r.VirtualTexturedLightmaps

#Overview

name: r.VirtualTexturedLightmaps

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

type: Var
help: Controls wether to stream the lightmaps using virtual texturing.\n 0: Disabled.\n 1: Enabled.

It is referenced in 20 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VirtualTexturedLightmaps is to control whether to stream lightmaps using virtual texturing in Unreal Engine 5. This setting is primarily used in the rendering system, specifically for managing lightmap textures.

The Unreal Engine subsystems that rely on this setting variable include:

Rendering system
Lightmap generation and management
Static mesh and landscape rendering
Ray tracing system

The value of this variable is set through the console variable system, with a default value of 0 (disabled). It can be changed at runtime using console commands.

This variable interacts closely with the UseVirtualTexturing() function, which checks if virtual texturing is supported on the current platform. It’s often used in conjunction with other rendering-related variables and functions.

Developers must be aware of the following when using this variable:

Enabling virtual textured lightmaps may have performance implications, especially on platforms with limited memory or bandwidth.
It affects how lightmaps are generated, stored, and rendered in the engine.
The setting is read-only, meaning it cannot be changed during gameplay without restarting the engine.

Best practices for using this variable include:

Test performance with both enabled and disabled states to determine the best setting for your project.
Consider platform-specific implications when enabling this feature.
Ensure that your lightmap generation pipeline is compatible with virtual texturing if you enable this feature.

The associated variable CVarVirtualTexturedLightMaps serves the same purpose as r.VirtualTexturedLightmaps. It is used internally within the engine code to access the value of the console variable. The usage and considerations for CVarVirtualTexturedLightMaps are the same as those for r.VirtualTexturedLightmaps, as they represent the same setting.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:105, section: [/Script/Engine.RendererSettings]

INI Section: /Script/Engine.RendererSettings
Raw value: False
Is Array: False

#References in C++ code

#Callsites

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

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:89`

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVirtualTexturedLightMaps(
	TEXT("r.VirtualTexturedLightmaps"),
	0,
	TEXT("Controls wether to stream the lightmaps using virtual texturing.\n") \
	TEXT(" 0: Disabled.\n") \
	TEXT(" 1: Enabled."),
	ECVF_ReadOnly);

#Loc: `<Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Scene.cpp:1874`

Scope (from outer to inner):

file
namespace    GPULightmass
function     void FScene::ApplyFinishedLightmapsToWorld

Source code excerpt:

	UWorld* World = GPULightmass->World;

	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(World->GetFeatureLevel()));

	bool bHasSkyShadowing = LightScene.SkyLight.IsSet() && LightScene.SkyLight->CastsStationaryShadow();
	
	{
		FScopedSlowTask SlowTask(3);

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:2802`

Scope (from outer to inner):

file
function     void UInstancedStaticMeshComponent::ApplyLightMapping

Source code excerpt:

void UInstancedStaticMeshComponent::ApplyLightMapping(FStaticLightingTextureMapping_InstancedStaticMesh* InMapping, ULevel* LightingScenario)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);

	NumPendingLightmaps--;

	if (NumPendingLightmaps == 0)
	{

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightmapUniformShaderParameters.cpp:64`

Scope (from outer to inner):

file
function     void GetPrecomputedLightingParameters

Source code excerpt:

)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnRenderThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(FeatureLevel));

	// TDistanceFieldShadowsAndLightMapPolicy
	const FShadowMapInteraction ShadowMapInteraction = LCI ? LCI->GetShadowMapInteraction(FeatureLevel) : FShadowMapInteraction();
	if (ShadowMapInteraction.GetType() == SMIT_Texture)
	{

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/ModelLight.cpp:997`

Scope (from outer to inner):

file
function     void UModel::ApplyStaticLighting

Source code excerpt:

{
#if WITH_EDITOR
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);

	check(CachedMappings[0]->QuantizedData);

	// Group surfaces based on their static lighting relevance.
	TArray<FSurfaceStaticLightingGroup> SurfaceGroups;

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/SceneManagement.cpp:1336`

Scope (from outer to inner):

file
function     void GetLightmapClusterResourceParameters

Source code excerpt:

	const bool bAllowHighQualityLightMaps = AllowHighQualityLightmaps(FeatureLevel);

	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnRenderThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(FeatureLevel));

	Parameters.LightMapTexture = GBlackTexture->TextureRHI;
	Parameters.SkyOcclusionTexture = GWhiteTexture->TextureRHI;
	Parameters.AOMaterialMaskTexture = GBlackTexture->TextureRHI;
	Parameters.StaticShadowTexture = GWhiteTexture->TextureRHI;

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshLight.cpp:211`

Scope (from outer to inner):

file
function     void FStaticMeshStaticLightingTextureMapping::Apply

Source code excerpt:

void FStaticMeshStaticLightingTextureMapping::Apply(FQuantizedLightmapData* QuantizedData, const TMap<ULightComponent*,FShadowMapData2D*>& ShadowMapData, ULevel* LightingScenario)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);

	UStaticMeshComponent* StaticMeshComponent = Primitive.Get();

	if (StaticMeshComponent && StaticMeshComponent->GetOwner() && StaticMeshComponent->GetOwner()->GetLevel())
	{

#Loc: `<Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeLight.cpp:46`

Scope (from outer to inner):

file
function     void FLandscapeStaticLightingTextureMapping::Apply

Source code excerpt:

void FLandscapeStaticLightingTextureMapping::Apply(FQuantizedLightmapData* QuantizedData, const TMap<ULightComponent*,FShadowMapData2D*>& ShadowMapData, ULevel* LightingScenario)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextures = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);

	//ELightMapPaddingType PaddingType = GAllowLightmapPadding ? LMPT_NormalPadding : LMPT_NoPadding;
	ELightMapPaddingType PaddingType = LMPT_NoPadding;

	ULevel* StorageLevel = LightingScenario ? LightingScenario : LandscapeComponent->GetOwner()->GetLevel();

#Loc: `<Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1167`

Scope (from outer to inner):

file
function     bool UseVirtualTextureLightmap

Source code excerpt:

RENDERCORE_API bool UseVirtualTextureLightmap(const FStaticShaderPlatform InShaderPlatform, const ITargetPlatform* TargetPlatform)
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool bUseVirtualTextureLightmap = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(InShaderPlatform, TargetPlatform);
	return bUseVirtualTextureLightmap;
}

RENDERCORE_API bool UseVirtualTextureLightmap(const FStaticFeatureLevel InFeatureLevel, const ITargetPlatform* TargetPlatform)
{

#Loc: `<Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2179`

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:


	{
		static const auto CVarVirtualTextureLightmaps = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
		const bool VTLightmaps = CVarVirtualTextureLightmaps && CVarVirtualTextureLightmaps->GetValueOnAnyThread() != 0;

		static const auto CVarVirtualTexture = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTextures"));
		bool VTTextures = CVarVirtualTexture && CVarVirtualTexture->GetValueOnAnyThread() != 0;

		static const auto CVarVTAnisotropic = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VT.AnisotropicFiltering"));

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapDensityRendering.cpp:162`

Scope: file

Source code excerpt:

			(MeshBatch.LCI->GetLightMapInteraction(FeatureLevel).GetTexture(bHighQualityLightMaps) || MeshBatch.LCI->GetLightMapInteraction(FeatureLevel).GetVirtualTexture()))
		{
			static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
			if (CVar->GetValueOnRenderThread() == 1)
			{
				IAllocatedVirtualTexture* AllocatedVT = MeshBatch.LCI->GetResourceCluster()->AllocatedVT;
				if (AllocatedVT)
				{
					ShaderElementData.LightMapResolutionScale.X = AllocatedVT->GetWidthInPixels();

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapRendering.cpp:41`

Scope (from outer to inner):

file
function     void LightMapPolicyImpl::ModifyCompilationEnvironment

Source code excerpt:

	OutEnvironment.SetDefine(TEXT("NUM_LIGHTMAP_COEFFICIENTS"), GNumLightmapCoefficients[LightmapQuality]);

	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
	const bool VirtualTextureLightmaps = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(Parameters.Platform);
	OutEnvironment.SetDefine(TEXT("LIGHTMAP_VT_ENABLED"), VirtualTextureLightmaps);
}

bool LightMapPolicyImpl::ShouldCompilePermutation(ELightmapQuality LightmapQuality, const FMeshMaterialShaderPermutationParameters& Parameters)
{

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingMaterialHitShaders.cpp:155`

Scope (from outer to inner):

file
class        class TMaterialCHS : public FMaterialCHS
function     static void ModifyCompilationEnvironment

Source code excerpt:

		LightMapPolicyType::ModifyCompilationEnvironment(Parameters, OutEnvironment);
		FMeshMaterialShader::ModifyCompilationEnvironment(Parameters, OutEnvironment);
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.VirtualTexturedLightmaps"));
		const bool VirtualTextureLightmaps = (CVar->GetValueOnAnyThread() != 0) && UseVirtualTexturing(Parameters.Platform);
		OutEnvironment.SetDefine(TEXT("LIGHTMAP_VT_ENABLED"), VirtualTextureLightmaps);
	}

	static bool ValidateCompiledResult(EShaderPlatform Platform, const FShaderParameterMap& ParameterMap, TArray<FString>& OutError)
	{

#Associated Variable and Callsites

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

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:88`

Scope: file

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<int32> CVarVirtualTexturedLightMaps(
	TEXT("r.VirtualTexturedLightmaps"),
	0,
	TEXT("Controls wether to stream the lightmaps using virtual texturing.\n") \
	TEXT(" 0: Disabled.\n") \
	TEXT(" 1: Enabled."),
	ECVF_ReadOnly);

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:1187`

Scope (from outer to inner):

file
function     void FLightMapPendingTexture::CreateUObjects

Source code excerpt:

	
	// Only build VT lightmaps if they are enabled
	const bool bUseVirtualTextures = (CVarVirtualTexturedLightMaps.GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);
	const bool bIncludeNonVirtualTextures = !bUseVirtualTextures || (CVarIncludeNonVirtualTexturedLightMaps.GetValueOnAnyThread() != 0);
	
	if (bIncludeNonVirtualTextures)
	{
		if (NeedsSkyOcclusionTexture())
		{

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2388`

Scope (from outer to inner):

file
function     void FLightMap2D::EncodeTextures

Source code excerpt:

	if (bLightingSuccessful)
	{
		const bool bUseVirtualTextures = (CVarVirtualTexturedLightMaps.GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform);
		const bool bIncludeNonVirtualTextures = !bUseVirtualTextures || (CVarIncludeNonVirtualTexturedLightMaps.GetValueOnAnyThread() != 0);

		GWarn->BeginSlowTask( NSLOCTEXT("LightMap2D", "BeginEncodingLightMapsTask", "Encoding light-maps"), false );
		int32 PackedLightAndShadowMapTextureSizeX = InWorld->GetWorldSettings()->PackedLightAndShadowMapTextureSize;
		int32 PackedLightAndShadowMapTextureSizeY = PackedLightAndShadowMapTextureSizeX / 2;

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2967`

Scope (from outer to inner):

file
function     void FLightMap2D::Serialize

Source code excerpt:

	FLightMap::Serialize(Ar);

	const bool bUsingVTLightmaps = (CVarVirtualTexturedLightMaps.GetValueOnAnyThread() != 0) && UseVirtualTexturing(GMaxRHIShaderPlatform, Ar.CookingTarget());

	if( Ar.IsLoading() && Ar.UEVer() < VER_UE4_LOW_QUALITY_DIRECTIONAL_LIGHTMAPS )
	{
		for(uint32 CoefficientIndex = 0;CoefficientIndex < 3;CoefficientIndex++)
		{
			ULightMapTexture2D* Dummy = NULL;

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3179`

Scope (from outer to inner):

file
function     FLightMapInteraction FLightMap2D::GetInteraction

Source code excerpt:

	int32 LightmapIndex = bHighQuality ? 0 : 1;

	const bool bUseVirtualTextures = (CVarVirtualTexturedLightMaps.GetValueOnAnyThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(InFeatureLevel));
	if (!bUseVirtualTextures)
	{
		bool bValidTextures = Textures[LightmapIndex] && Textures[LightmapIndex]->GetResource();

		// When the FLightMap2D is first created, the textures aren't set, so that case needs to be handled.
		if (bValidTextures)

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3209`

Scope (from outer to inner):

file
function     FShadowMapInteraction FLightMap2D::GetShadowInteraction

Source code excerpt:

	int32 LightmapIndex = bHighQuality ? 0 : 1;

	const bool bUseVirtualTextures = (CVarVirtualTexturedLightMaps.GetValueOnAnyThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(InFeatureLevel));
	if (bUseVirtualTextures)
	{
		// Preview lightmaps don't stream from disk, thus no FVirtualTexture2DResource
		const bool bValidVirtualTexture = VirtualTextures[LightmapIndex] && (VirtualTextures[LightmapIndex]->GetResource() != nullptr || VirtualTextures[LightmapIndex]->bPreviewLightmap);
		if (bValidVirtualTexture)
		{

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3361`

Scope (from outer to inner):

file
function     bool FLightmapResourceCluster::GetUseVirtualTexturing

Source code excerpt:

bool FLightmapResourceCluster::GetUseVirtualTexturing() const
{
	return (CVarVirtualTexturedLightMaps.GetValueOnRenderThread() != 0) && UseVirtualTexturing(GetFeatureLevelShaderPlatform(GetFeatureLevel()));
}

// Two stage initialization of FLightmapResourceCluster
// 1. when UMapBuildDataRegistry is post-loaded and render resource is initialized
// 2. when the level is made visible (ULevel::InitializeRenderingResources()), which calls UMapBuildDataRegistry::InitializeClusterRenderingResources() and fills FeatureLevel
// When both parts are provided, TryInitialize() creates the final UB with actual content

r.VirtualTexturedLightmaps

r.VirtualTexturedLightmaps

#Overview

#Summary

#Usage in the C++ source code

#Setting Variables

#References In INI files

#References in C++ code

#Callsites

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:89

#Loc: <Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Scene.cpp:1874

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:2802

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightmapUniformShaderParameters.cpp:64

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ModelLight.cpp:997

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneManagement.cpp:1336

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshLight.cpp:211

#Loc: <Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeLight.cpp:46

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1167

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2179

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapDensityRendering.cpp:162

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapRendering.cpp:41

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingMaterialHitShaders.cpp:155

#Associated Variable and Callsites

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:88

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:1187

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2388

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2967

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3179

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3209

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3361

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:89`

#Loc: `<Workspace>/Engine/Plugins/Experimental/GPULightmass/Source/GPULightmass/Private/Scene/Scene.cpp:1874`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:2802`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightmapUniformShaderParameters.cpp:64`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/ModelLight.cpp:997`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/SceneManagement.cpp:1336`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshLight.cpp:211`

#Loc: `<Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeLight.cpp:46`

#Loc: `<Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1167`

#Loc: `<Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2179`

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapDensityRendering.cpp:162`

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/LightMapRendering.cpp:41`

#Loc: `<Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingMaterialHitShaders.cpp:155`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:88`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:1187`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2388`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:2967`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3179`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3209`

#Loc: `<Workspace>/Engine/Source/Runtime/Engine/Private/LightMap.cpp:3361`