r.IncludeNonVirtualTexturedLightmaps

r.IncludeNonVirtualTexturedLightmaps

#Overview

name: r.IncludeNonVirtualTexturedLightmaps

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.IncludeNonVirtualTexturedLightmaps is to control whether non-virtual textured (non-VT) lightmaps are generated and saved alongside virtual textured (VT) lightmaps when VT lightmaps are enabled. This setting is part of Unreal Engine’s rendering system, specifically related to lightmap generation and storage.

This setting variable is primarily used in the Engine module, specifically within the lightmap-related code. It interacts with the virtual texturing system for lightmaps.

The value of this variable is set through a console variable (CVar) named CVarIncludeNonVirtualTexturedLightMaps. It’s defined with a default value of 0, meaning non-VT lightmaps are not included by default.

This variable interacts closely with another variable, CVarVirtualTexturedLightMaps, which controls whether virtual textured lightmaps are enabled.

Developers must be aware that:

  1. This setting only has an effect when virtual textured lightmaps are enabled.
  2. Including non-VT lightmaps will constrain the lightmap atlas size, which can reduce some benefits of using VT lightmaps.
  3. The setting is read-only at runtime, meaning it should be set before the engine initializes.

Best practices when using this variable include:

  1. Only enable it if you have a specific need for non-VT lightmaps alongside VT lightmaps.
  2. Consider the performance implications, as including non-VT lightmaps may increase memory usage and potentially impact rendering performance.
  3. Test thoroughly with both settings (0 and 1) to ensure your game performs well in both scenarios.

Regarding the associated variable CVarIncludeNonVirtualTexturedLightMaps:

This is the actual console variable that controls the r.IncludeNonVirtualTexturedLightmaps setting. It’s defined as an integer with two possible values: 0: Non-VT lightmaps are not included (default) 1: Non-VT lightmaps are included

The variable is used in the FLightMapPendingTexture::CreateUObjects and FLightMap2D::EncodeTextures functions to determine whether to create and encode non-VT lightmap textures.

Developers should use this CVar to control the behavior at runtime or in configuration files, rather than directly accessing the r.IncludeNonVirtualTexturedLightmaps setting. The value can be read using CVarIncludeNonVirtualTexturedLightMaps.GetValueOnAnyThread() in C++ code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarIncludeNonVirtualTexturedLightMaps(
	TEXT("r.IncludeNonVirtualTexturedLightmaps"),
	0,
	TEXT("If 'r.VirtualTexturedLightmaps' is enabled, controls whether non-VT lightmaps are generated/saved as well.\n") \
	TEXT("Including non-VT lightmaps will constrain lightmap atlas size, which removes some of the benefit of VT lightmaps.\n") \
	TEXT(" 0: Not included.\n") \
	TEXT(" 1: Included."));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly);

static TAutoConsoleVariable<int32> CVarIncludeNonVirtualTexturedLightMaps(
	TEXT("r.IncludeNonVirtualTexturedLightmaps"),
	0,
	TEXT("If 'r.VirtualTexturedLightmaps' is enabled, controls whether non-VT lightmaps are generated/saved as well.\n") \
	TEXT("Including non-VT lightmaps will constrain lightmap atlas size, which removes some of the benefit of VT lightmaps.\n") \
	TEXT(" 0: Not included.\n") \
	TEXT(" 1: Included."));

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

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())
		{
			SkyOcclusionTexture = NewObject<ULightMapTexture2D>(Outer, GetSkyOcclusionTextureName(GLightmapCounter));

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

Scope (from outer to inner):

file
function     void FLightMap2D::EncodeTextures

Source code excerpt:

	{
		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;

		if (!bIncludeNonVirtualTextures)