r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio

r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio

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

• type: Var
• help: Only merge if the (combined box surface area) / (summed instance box surface area) < MaxSurfaceAreaRatio

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio is to control the merging of mesh instances in Lumen’s surface cache system, which is part of Unreal Engine 5’s global illumination and reflections rendering system.

This setting variable is primarily used by the Lumen rendering subsystem, specifically in the mesh cards generation and scene management modules.

The value of this variable is set to 1.7f by default, as seen in the source code. It can be modified at runtime through the console or configuration files.

The associated variable GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio directly interacts with it, sharing the same value. This variable is used in the actual logic for merging mesh instances.

Developers must be aware that this variable affects the performance and quality trade-off in Lumen’s surface cache. It determines when mesh instances should be merged based on their surface area ratios. A lower value will result in more aggressive merging, potentially improving performance at the cost of some accuracy.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your scene and target hardware.
2. Testing different values to find the optimal balance between performance and visual quality.
3. Considering it in conjunction with other Lumen settings for holistic optimization.

Regarding the associated variable GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio:

Its purpose is to store the actual value used in the mesh merging calculations within the Lumen system.

It is used directly in the Lumen scene update process, specifically in the UpdateLumenScenePrimitives function.

The value is set through the console variable r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio.

It interacts with other variables in the mesh merging process, such as GLumenMeshCardsMergedResolutionScale.

Developers should be aware that modifying this variable will directly affect the mesh merging behavior in Lumen, impacting both performance and rendering quality.

Best practices include monitoring its impact on frame rate and visual fidelity when adjusting it, and considering its interaction with other Lumen settings for optimal results.

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

Scope: file

Source code excerpt:

float GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio = 1.7f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio"),
	GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio,
	TEXT("Only merge if the (combined box surface area) / (summed instance box surface area) < MaxSurfaceAreaRatio"),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio = 1.7f;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeInstancesMaxSurfaceAreaRatio"),
	GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio,
	TEXT("Only merge if the (combined box surface area) / (summed instance box surface area) < MaxSurfaceAreaRatio"),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     void UpdateLumenScenePrimitives

Source code excerpt:

							const float SurfaceAreaRatio = BoundsSurfaceArea / TotalInstanceSurfaceArea;

							extern float GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio;
							extern float GLumenMeshCardsMergedResolutionScale;

							if (SurfaceAreaRatio < GLumenMeshCardsMergeInstancesMaxSurfaceAreaRatio)
							{
								const int32 PrimitiveGroupIndex = LumenSceneData->PrimitiveGroups.AddSpan(1);
								ScenePrimitiveInfo->LumenPrimitiveGroupIndices.Add(PrimitiveGroupIndex);
								LumenSceneData->PrimitiveGroupIndicesToUpdateInBuffer.Add(PrimitiveGroupIndex);

								FLumenPrimitiveGroup& PrimitiveGroup = LumenSceneData->PrimitiveGroups[PrimitiveGroupIndex];