r.LumenScene.PrimitivesPerTask

r.LumenScene.PrimitivesPerTask

#Overview

name: r.LumenScene.PrimitivesPerTask

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.PrimitivesPerTask is to control the number of primitives processed per single surface cache update task in the Lumen scene rendering system. This setting is part of Unreal Engine 5’s Lumen global illumination system, which is a key component of the rendering pipeline.

This setting variable is primarily used by the Lumen scene rendering subsystem within the Renderer module of Unreal Engine 5. It’s specifically utilized in the surface cache update process, which is crucial for maintaining an up-to-date representation of the scene for global illumination calculations.

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 adjusted at runtime through console commands or configuration files. The default value is set to 128 primitives per task.

The associated variable GLumenScenePrimitivesPerTask directly interacts with r.LumenScene.PrimitivesPerTask. They share the same value, with GLumenScenePrimitivesPerTask being the actual integer variable used in the C++ code to control the number of primitives per task.

Developers should be aware that this variable affects the granularity of surface cache update tasks. A higher value means more primitives are processed in a single task, which could potentially improve performance by reducing task overhead, but might also lead to longer individual task durations. Conversely, a lower value could provide more fine-grained control and potentially better load balancing, but with increased task management overhead.

Best practices when using this variable include:

  1. Experimentation to find the optimal value for specific scenes and hardware configurations.
  2. Considering the complexity and number of primitives in the scene when adjusting this value.
  3. Monitoring performance metrics to ensure that changes to this value are beneficial.
  4. Being cautious when drastically changing the value, as it could impact frame rates and overall rendering performance.

Regarding the associated variable GLumenScenePrimitivesPerTask:

The purpose of GLumenScenePrimitivesPerTask is to store the actual integer value used in the C++ code for controlling the number of primitives per surface cache update task. It’s directly linked to the r.LumenScene.PrimitivesPerTask console variable.

This variable is used within the Lumen scene rendering system, specifically in the UpdateSurfaceCachePrimitives function. It determines how many primitives are grouped into a single task when updating the surface cache.

The value of GLumenScenePrimitivesPerTask is set by the r.LumenScene.PrimitivesPerTask console variable. Any changes to the console variable will directly affect this C++ variable.

Developers should be aware that this variable is used in calculations to determine the number of tasks needed for surface cache updates. It’s crucial for balancing workload distribution in the Lumen rendering pipeline.

Best practices for GLumenScenePrimitivesPerTask include ensuring it’s always a positive value (the code includes a FMath::Max check to ensure this) and considering its impact on task distribution and overall rendering performance when modifying the associated console variable.

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

Scope: file

Source code excerpt:

int32 GLumenScenePrimitivesPerTask = 128;
FAutoConsoleVariableRef CVarLumenScenePrimitivePerTask(
	TEXT("r.LumenScene.PrimitivesPerTask"),
	GLumenScenePrimitivesPerTask,
	TEXT("How many primitives to process per single surface cache update task."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneMeshCardsPerTask = 128;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScenePrimitivesPerTask = 128;
FAutoConsoleVariableRef CVarLumenScenePrimitivePerTask(
	TEXT("r.LumenScene.PrimitivesPerTask"),
	GLumenScenePrimitivesPerTask,
	TEXT("How many primitives to process per single surface cache update task."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneMeshCardsPerTask = 128;
FAutoConsoleVariableRef CVarLumenSceneMeshCardsPerTask(

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

Scope (from outer to inner):

file
function     void UpdateSurfaceCachePrimitives

Source code excerpt:


	{
		const int32 NumPrimitivesPerTask = FMath::Max(GLumenScenePrimitivesPerTask, 1);
		const int32 NumTasks = FMath::DivideAndRoundUp(LumenSceneData.PrimitiveGroups.Num(), GLumenScenePrimitivesPerTask);

		TArray<FLumenSurfaceCacheUpdatePrimitivesTask, SceneRenderingAllocator> Tasks;
		Tasks.Reserve(NumTasks);

		for (int32 TaskIndex = 0; TaskIndex < NumTasks; ++TaskIndex)
		{