r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize

r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize

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

• type: Var
• help: Only merged bounds less than this size on any axis are considered, since Lumen Scene streaming relies on object granularity.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize is to control the maximum size of merged mesh card bounds in the Lumen Scene system, which is part of Unreal Engine 5’s global illumination solution.

This setting variable is primarily used in the Lumen rendering system, specifically in the mesh cards generation and merging process. It’s part of the Renderer module and is closely tied to the Lumen Scene’s surface cache functionality.

The value of this variable is set through the Unreal Engine console system, using the FAutoConsoleVariableRef mechanism. It’s initialized with a default value of 10000.0f units.

The associated variable GLumenMeshCardsMergedMaxWorldSize directly interacts with it, sharing the same value. This global variable is used in the actual rendering code to apply the size limit.

Developers must be aware that this variable affects the granularity of object representation in the Lumen Scene. It’s particularly important for scene streaming, as noted in the comment: “Only merged bounds less than this size on any axis are considered, since Lumen Scene streaming relies on object granularity.”

Best practices when using this variable include:

1. Adjusting it based on the scale of your game world. Smaller values may lead to more accurate lighting but could increase memory usage and processing time.
2. Considering the impact on scene streaming performance when modifying this value.
3. Testing thoroughly after changes, as it can affect both visual quality and performance.

Regarding the associated variable GLumenMeshCardsMergedMaxWorldSize:

This is the actual float variable that stores the value set by the console variable. It’s used directly in the rendering code, specifically in the UpdateLumenScenePrimitives function.

The purpose of GLumenMeshCardsMergedMaxWorldSize is to provide a quick access point for the renderer to check the maximum allowed size for merged mesh cards. It’s used in conjunction with other conditions to determine if multiple instances of a primitive can be merged into a single mesh card representation in the Lumen Scene.

Developers should be aware that changing the console variable will directly affect this global variable, and thus the behavior of the mesh card merging process. Any performance optimizations or visual quality tweaks related to Lumen’s mesh cards should consider this variable’s value.

Best practices for GLumenMeshCardsMergedMaxWorldSize include:

1. Avoiding direct modification of this variable; instead, use the console variable to ensure proper synchronization.
2. Considering its interaction with other Lumen settings, particularly those related to mesh cards and instance merging.
3. Profiling the impact of different values on both rendering quality and performance, especially in scenes with many instanced meshes.

#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:81

Scope: file

Source code excerpt:

float GLumenMeshCardsMergedMaxWorldSize = 10000.0f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergedMaxWorldSize(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize"),
	GLumenMeshCardsMergedMaxWorldSize,
	TEXT("Only merged bounds less than this size on any axis are considered, since Lumen Scene streaming relies on object granularity."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenMeshCardsMergedMaxWorldSize = 10000.0f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergedMaxWorldSize(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergedMaxWorldSize"),
	GLumenMeshCardsMergedMaxWorldSize,
	TEXT("Only merged bounds less than this size on any axis are considered, since Lumen Scene streaming relies on object granularity."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

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

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;

							for (int32 InstanceIndex = 0; InstanceIndex < NumInstances; ++InstanceIndex)
							{