r.LumenScene.MeshCardsPerTask

r.LumenScene.MeshCardsPerTask

#Overview

name: r.LumenScene.MeshCardsPerTask

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

• type: Var
• help: How many mesh cards to process per single surface cache update task.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.MeshCardsPerTask is to control the number of mesh cards processed per single surface cache update task in the Lumen global illumination system of Unreal Engine 5.

This setting variable is primarily used in the Lumen rendering subsystem, which is part of Unreal Engine’s advanced lighting and global illumination features. Specifically, it’s utilized in the LumenSceneRendering module.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 128 and can be changed at runtime using console commands or through configuration files.

The associated variable GLumenSceneMeshCardsPerTask directly interacts with r.LumenScene.MeshCardsPerTask. They share the same value, with GLumenSceneMeshCardsPerTask being the actual integer variable used in the C++ code.

Developers should be aware that this variable affects the granularity of surface cache update tasks in Lumen. A higher value will process more mesh cards per task, potentially improving performance but at the cost of larger individual task sizes. Conversely, a lower value will create more tasks with fewer mesh cards each, which might provide better load balancing but could introduce more overhead.

Best practices when using this variable include:

1. Adjusting it based on the complexity and number of mesh cards in your scene.
2. Balancing it with other Lumen settings for optimal performance.
3. Testing different values to find the sweet spot for your specific use case.
4. Considering the target hardware capabilities when setting this value.

Regarding the associated variable GLumenSceneMeshCardsPerTask:

• Its purpose is to store the actual integer value used in the C++ code for the number of mesh cards per task.
• It’s used directly in the UpdateSurfaceCacheMeshCards function to calculate the number of tasks needed for processing mesh cards.
• The value is clamped to a minimum of 1 to ensure at least one mesh card is processed per task.
• Developers should be aware that this variable is used in performance-critical code and its value directly affects how work is divided in the Lumen system.
• Best practices include monitoring its impact on performance and adjusting it in conjunction 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/LumenSceneRendering.cpp:52

Scope: file

Source code excerpt:

int32 GLumenSceneMeshCardsPerTask = 128;
FAutoConsoleVariableRef CVarLumenSceneMeshCardsPerTask(
	TEXT("r.LumenScene.MeshCardsPerTask"),
	GLumenSceneMeshCardsPerTask,
	TEXT("How many mesh cards to process per single surface cache update task."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSurfaceCacheFreeze = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneRendering.cpp:50

Scope: file

Source code excerpt:

);

int32 GLumenSceneMeshCardsPerTask = 128;
FAutoConsoleVariableRef CVarLumenSceneMeshCardsPerTask(
	TEXT("r.LumenScene.MeshCardsPerTask"),
	GLumenSceneMeshCardsPerTask,
	TEXT("How many mesh cards to process per single surface cache update task."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSurfaceCacheFreeze = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreeze(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneRendering.cpp:1119

Scope (from outer to inner):

file
function     void UpdateSurfaceCacheMeshCards

Source code excerpt:

	QUICK_SCOPE_CYCLE_COUNTER(UpdateMeshCards);

	const int32 NumMeshCardsPerTask = FMath::Max(GLumenSceneMeshCardsPerTask, 1);
	const int32 NumTasks = FMath::DivideAndRoundUp(LumenSceneData.MeshCards.Num(), NumMeshCardsPerTask);
	if (NumTasks == 0)
	{
		return;
	}