r.LumenScene.SurfaceCache.MeshCardsMergeInstances

r.LumenScene.SurfaceCache.MeshCardsMergeInstances

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMergeInstances

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

• type: Var
• help: Whether to merge all instances of a Instanced Static Mesh Component into a single MeshCards.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsMergeInstances is to control whether all instances of an Instanced Static Mesh Component should be merged into a single MeshCards in the Lumen rendering system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically relating to the surface cache and mesh card optimization.

This setting variable is primarily used in the Lumen rendering subsystem, which is part of Unreal Engine 5’s renderer module. It’s specifically utilized in the mesh cards generation process for the Lumen scene.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files.

The associated variable GLumenMeshCardsMergeInstances directly interacts with this setting. They share the same value, with GLumenMeshCardsMergeInstances being the actual integer variable used in the code logic.

Developers should be aware that changing this variable triggers a recreation of render states for global components. This is evident from the FGlobalComponentRecreateRenderStateContext being created in the console variable delegate.

Best practices when using this variable include:

1. Understanding the performance implications of merging instances. While it can reduce draw calls, it might increase memory usage for large scenes.
2. Testing the impact on your specific scene, as the benefits may vary depending on the number and complexity of instanced static meshes.
3. Being cautious when changing this setting at runtime, as it triggers a potentially expensive render state recreation.

Regarding the associated variable GLumenMeshCardsMergeInstances:

This is an integer variable that directly controls the behavior defined by r.LumenScene.SurfaceCache.MeshCardsMergeInstances. It’s used in the UpdateLumenScenePrimitives function to determine whether instances should be merged.

The code checks if GLumenMeshCardsMergeInstances is true (non-zero), along with other conditions like having more than one instance and the primitive box size being below a certain threshold (GLumenMeshCardsMergedMaxWorldSize).

Developers should note that this variable interacts with another setting, GLumenMeshCardsMergedMaxWorldSize, to determine when instance merging should occur. The combination of these two variables allows for fine-tuning of the merging behavior based on both the desire to merge and the size of the objects involved.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:33

Scope: file

Source code excerpt:

int32 GLumenMeshCardsMergeInstances = 0;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeInstances(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeInstances"),
	GLumenMeshCardsMergeInstances,
	TEXT("Whether to merge all instances of a Instanced Static Mesh Component into a single MeshCards."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:31

Scope: file

Source code excerpt:

);

int32 GLumenMeshCardsMergeInstances = 0;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeInstances(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeInstances"),
	GLumenMeshCardsMergeInstances,
	TEXT("Whether to merge all instances of a Instanced Static Mesh Component into a single MeshCards."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:909

Scope (from outer to inner):

file
function     void UpdateLumenScenePrimitives

Source code excerpt:

					{
						// Check if we can merge all instances into one MeshCards
						extern int32 GLumenMeshCardsMergeInstances;
						extern float GLumenMeshCardsMergedMaxWorldSize;

						const FBox PrimitiveBox = SceneProxy->GetBounds().GetBox();
						const FRenderBounds PrimitiveBounds = FRenderBounds(PrimitiveBox);

						if (GLumenMeshCardsMergeInstances
							&& NumInstances > 1
							&& PrimitiveBox.GetSize().GetMax() < GLumenMeshCardsMergedMaxWorldSize)
						{
							FRenderBounds PrimitiveRelativeBounds;
							double TotalInstanceSurfaceArea = 0;