r.PSOPrecache.LightMapPolicyMode

r.PSOPrecache.LightMapPolicyMode

#Overview

name: r.PSOPrecache.LightMapPolicyMode

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

• type: Var
• help: Defines which light map policies should be checked during PSO precaching of the base pass.\n 0: All possible LMP will be checked.\n 1: Only LMP_NO_LIGHTMAP will be precached (default).\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PSOPrecache.LightMapPolicyMode is to control which light map policies should be checked during PSO (Pipeline State Object) precaching of the base pass in Unreal Engine’s rendering system.

This setting variable is primarily used by the Renderer module, specifically in the base pass rendering subsystem. It affects how the engine prepares and optimizes rendering pipelines for different lighting scenarios.

The value of this variable is set through a console variable (CVar) system, initialized with a default value of 1. It can be modified at runtime, but it’s marked as read-only, suggesting that changes should be made with caution.

The variable interacts closely with the ELightMapPolicyType enum and the LMP_NO_LIGHTMAP constant. It influences the behavior of functions like GetUniformLightMapPolicyTypeForPSOCollection and CollectPSOInitializersForSkyLight.

Developers must be aware that:

1. A value of 0 will check all possible Light Map Policies during precaching.
2. A value of 1 (default) will only precache LMP_NO_LIGHTMAP.

Best practices when using this variable include:

1. Keeping it at the default value (1) unless there’s a specific need for precaching all light map policies.
2. Understanding that changing this value can affect performance and memory usage, as it determines how many PSOs are precached.
3. If modifying, do so early in the application lifecycle, preferably before rendering begins.
4. Monitor performance impacts when changing this value, especially in complex scenes with varied lighting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/BasePassRendering.cpp:95

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarPSOPrecacheLightMapPolicyMode(
	TEXT("r.PSOPrecache.LightMapPolicyMode"),
	1,
	TEXT("Defines which light map policies should be checked during PSO precaching of the base pass.\n") \
	TEXT(" 0: All possible LMP will be checked.\n") \
	TEXT(" 1: Only LMP_NO_LIGHTMAP will be precached (default).\n"),
	ECVF_ReadOnly
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/BasePassRendering.cpp:2291

Scope (from outer to inner):

file
function     TArray<ELightMapPolicyType, TInlineAllocator<2>> FBasePassMeshProcessor::GetUniformLightMapPolicyTypeForPSOCollection

Source code excerpt:

	const bool bUseVolumetricLightmap = true;// Scene&& Scene->VolumetricLightmapSceneData.HasData();

	static const auto CVarSupportLightMapPolicyMode = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PSOPrecache.LightMapPolicyMode"));
	const bool bNoLightMapOnlyMode = (CVarSupportLightMapPolicyMode && CVarSupportLightMapPolicyMode->GetValueOnAnyThread() == 1);

	TArray<ELightMapPolicyType, TInlineAllocator<2>> UniformLightMapPolicyTypes;

	// always add the fallback no lightmap mode
	UniformLightMapPolicyTypes.Add(LMP_NO_LIGHTMAP);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/BasePassRendering.cpp:2399

Scope (from outer to inner):

file
function     void FBasePassMeshProcessor::CollectPSOInitializersForSkyLight

Source code excerpt:

	const bool bIsLitMaterial = ShadingModels.IsLit();
	
	static const auto CVarSupportLightMapPolicyMode = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PSOPrecache.LightMapPolicyMode"));
	const bool bNoLightMapOnlyMode = (CVarSupportLightMapPolicyMode && CVarSupportLightMapPolicyMode->GetValueOnAnyThread() == 1);

	if (!bNoLightMapOnlyMode && bIsLitMaterial && bIsTranslucent)
	{
		const bool bAllowStaticLighting = IsStaticLightingAllowed();