r.LumenScene.SurfaceCache.MeshCardsMergeComponents

r.LumenScene.SurfaceCache.MeshCardsMergeComponents

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMergeComponents

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

• type: Var
• help: Whether to merge all components with the same RayTracingGroupId 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.MeshCardsMergeComponents is to control whether Lumen should merge all components with the same RayTracingGroupId into a single MeshCards. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically related to the surface cache and mesh cards optimization.

This setting variable is primarily used by the Lumen rendering subsystem within Unreal Engine 5. It’s referenced in the Renderer module, particularly in the Lumen-related source files.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime using console commands or through project settings.

The associated variable GLumenMeshCardsMergeComponents directly interacts with this setting. They share the same value, with GLumenMeshCardsMergeComponents being the actual integer variable used in the C++ code to control the behavior.

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

Best practices when using this variable include:

1. Consider performance implications: Merging components can potentially improve rendering performance, but it might also have drawbacks in certain scenarios.
2. Test thoroughly: Changing this setting may affect visual quality or performance, so extensive testing is recommended.
3. Use in conjunction with other Lumen settings: This setting works as part of the broader Lumen system, so consider its interactions with other Lumen-related settings.
4. Be cautious when changing at runtime: While it’s possible to change this setting during gameplay, be aware that it will trigger a potentially expensive render state recreation.

Regarding the associated variable GLumenMeshCardsMergeComponents:

The purpose of GLumenMeshCardsMergeComponents is to serve as the actual integer variable that controls the merging behavior within the C++ code of the Lumen system.

This variable is used directly in the Lumen scene update logic, specifically in the UpdateLumenScenePrimitives function. It determines whether the system should attempt to merge components based on their RayTracingGroupId.

The value of GLumenMeshCardsMergeComponents is set by the console variable system, mirroring the value of r.LumenScene.SurfaceCache.MeshCardsMergeComponents.

When using this variable, developers should be aware that it affects how primitives are grouped and processed in the Lumen scene. It’s particularly relevant for opaque or masked primitives that are not emissive light sources.

Best practices include:

1. Understand the performance trade-offs: Merging components can reduce draw calls but might increase memory usage.
2. Profile your specific use case: The optimal setting may vary depending on your scene composition and target hardware.
3. Consider scalability: This setting is marked with ECVF_Scalability, indicating it’s intended to be adjusted for different quality levels or hardware capabilities.

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

Scope: file

Source code excerpt:

int32 GLumenMeshCardsMergeComponents = 1;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeComponents(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeComponents"),
	GLumenMeshCardsMergeComponents,
	TEXT("Whether to merge all components with the same RayTracingGroupId into a single MeshCards."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenMeshCardsMergeComponents = 1;
FAutoConsoleVariableRef CVarLumenMeshCardsMergeComponents(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMergeComponents"),
	GLumenMeshCardsMergeComponents,
	TEXT("Whether to merge all components with the same RayTracingGroupId into a single MeshCards."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),
	ECVF_Scalability | ECVF_RenderThreadSafe

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

Scope (from outer to inner):

file
function     void UpdateLumenScenePrimitives

Source code excerpt:

			{
				// First try to merge components
				extern int32 GLumenMeshCardsMergeComponents;
				if (GLumenMeshCardsMergeComponents != 0 
					&& SceneProxy->GetRayTracingGroupId() != FPrimitiveSceneProxy::InvalidRayTracingGroupId
					&& !SceneProxy->IsEmissiveLightSource()
					&& SceneProxy->IsOpaqueOrMasked())
				{
					const Experimental::FHashElementId RayTracingGroupMapElementId = LumenSceneData->RayTracingGroups.FindOrAddId(SceneProxy->GetRayTracingGroupId(), -1);
					int32& PrimitiveGroupIndex = LumenSceneData->RayTracingGroups.GetByElementId(RayTracingGroupMapElementId).Value;