r.LumenScene.ParallelUpdate

r.LumenScene.ParallelUpdate

#Overview

name: r.LumenScene.ParallelUpdate

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.ParallelUpdate is to control whether the Lumen Scene update is executed in parallel. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, which is a key component of the rendering subsystem.

The Lumen Scene rendering module relies on this setting variable, as evidenced by its use in the LumenSceneRendering.cpp file. This file is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1, indicating that parallel updates are enabled by default. Developers can modify this value at runtime using console commands or through project settings.

This variable interacts closely with its associated variable GLumenSceneParallelUpdate. They share the same value, with GLumenSceneParallelUpdate being the actual integer variable used in the code logic.

Developers must be aware that this variable affects the performance and scalability of the Lumen Scene update process. When enabled (set to non-zero), it allows the engine to utilize multiple threads for updating the Lumen Scene, potentially improving performance on multi-core systems.

Best practices when using this variable include:

  1. Keeping it enabled (default value of 1) for most scenarios to benefit from parallel processing.
  2. Testing the performance impact on your specific project, as the benefits may vary depending on scene complexity and hardware capabilities.
  3. Considering disabling it (setting to 0) if you encounter any threading-related issues or if you need to debug the Lumen Scene update process.

Regarding the associated variable GLumenSceneParallelUpdate:

The purpose of GLumenSceneParallelUpdate is to serve as the actual integer variable that controls the parallel execution of the Lumen Scene update within the C++ code.

This variable is used directly in the rendering code to determine whether to execute certain tasks in parallel. It’s checked in functions like UpdateSurfaceCachePrimitives and UpdateSurfaceCacheMeshCards to decide whether to use parallel execution.

The value of GLumenSceneParallelUpdate is set through the console variable system, linked to the r.LumenScene.ParallelUpdate setting.

It interacts closely with FApp::ShouldUseThreadingForPerformance() to make the final decision on whether to use parallel execution.

Developers should be aware that this variable is used in conjunction with the engine’s threading capabilities. It’s important to ensure that any custom code interacting with Lumen Scene updates respects this setting.

Best practices include:

  1. Not modifying GLumenSceneParallelUpdate directly in code, but rather using the console variable system to change its value.
  2. Being cautious when introducing new parallel tasks in the Lumen Scene update process, ensuring they respect this setting.
  3. Considering this variable when profiling or optimizing Lumen Scene-related code.

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

Scope: file

Source code excerpt:

int32 GLumenSceneParallelUpdate = 1;
FAutoConsoleVariableRef CVarLumenSceneParallelUpdate(
	TEXT("r.LumenScene.ParallelUpdate"),
	GLumenSceneParallelUpdate,
	TEXT("Whether to run the Lumen Scene update in parallel."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScenePrimitivesPerTask = 128;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneParallelUpdate = 1;
FAutoConsoleVariableRef CVarLumenSceneParallelUpdate(
	TEXT("r.LumenScene.ParallelUpdate"),
	GLumenSceneParallelUpdate,
	TEXT("Whether to run the Lumen Scene update in parallel."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScenePrimitivesPerTask = 128;
FAutoConsoleVariableRef CVarLumenScenePrimitivePerTask(

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

Scope (from outer to inner):

file
function     void UpdateSurfaceCachePrimitives

Source code excerpt:

		}

		const bool bExecuteInParallel = FApp::ShouldUseThreadingForPerformance() && GLumenSceneParallelUpdate != 0;

		ParallelFor(Tasks.Num(),
			[&Tasks](int32 Index)
			{
				Tasks[Index].AnyThreadTask();
			},

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

Scope (from outer to inner):

file
function     void UpdateSurfaceCacheMeshCards

Source code excerpt:

	}

	const bool bExecuteInParallel = FApp::ShouldUseThreadingForPerformance() && GLumenSceneParallelUpdate != 0;

	ParallelFor(Tasks.Num(),
		[&Tasks](int32 Index)
		{
			Tasks[Index].AnyThreadTask();
		},