r.LumenScene.GPUDrivenUpdate

r.LumenScene.GPUDrivenUpdate

#Overview

name: r.LumenScene.GPUDrivenUpdate

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.GPUDrivenUpdate is to control whether the GPU is used to update the Lumen Scene in Unreal Engine 5. Lumen is a dynamic global illumination and reflections system, and this setting specifically relates to how scene updates are processed.

This setting variable is primarily used in the rendering system, specifically within the Lumen subsystem of Unreal Engine 5. It’s referenced in the LumenSceneRendering.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0, meaning the GPU-driven update is disabled by default. Developers can change this value at runtime using console commands or through project settings.

The associated variable CVarLumenSceneGPUDrivenUpdate directly interacts with r.LumenScene.GPUDrivenUpdate. They share the same value and are used interchangeably in the code.

Developers must be aware that this feature is marked as “Work in progress” in the code comments. This suggests that the functionality may not be fully stable or optimized, and could potentially change in future engine versions.

When using this variable, best practices include:

  1. Testing thoroughly when enabling GPU-driven updates, as it may impact performance or visual quality.
  2. Being cautious about enabling it in production builds until it’s no longer marked as work in progress.
  3. Monitoring performance metrics when enabling this feature to ensure it doesn’t negatively impact frame rates.

Regarding the associated variable CVarLumenSceneGPUDrivenUpdate:

The purpose of CVarLumenSceneGPUDrivenUpdate is to provide a programmatic way to access and modify the r.LumenScene.GPUDrivenUpdate setting within C++ code.

This variable is used in the Lumen rendering system to determine whether to use GPU-driven updates for the Lumen scene. It’s checked in several places within the LumenSceneRendering.cpp file to conditionally execute GPU-driven update code.

The value of CVarLumenSceneGPUDrivenUpdate is set when the r.LumenScene.GPUDrivenUpdate console variable is modified. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access in the render thread.

CVarLumenSceneGPUDrivenUpdate directly interacts with r.LumenScene.GPUDrivenUpdate, as they represent the same setting.

Developers should be aware that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s a scalability option that’s safe to modify on the render thread.

Best practices for using CVarLumenSceneGPUDrivenUpdate include:

  1. Always accessing its value using GetValueOnRenderThread() when in render thread code.
  2. Being mindful of potential performance implications when enabling GPU-driven updates.
  3. Using this variable to implement dynamic quality settings that can adjust based on performance requirements.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenSceneGPUDrivenUpdate(
	TEXT("r.LumenScene.GPUDrivenUpdate"),
	0,
	TEXT("Whether to use GPU to update Lumen Scene. Work in progress."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#if ENABLE_LOW_LEVEL_MEM_TRACKER

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenSceneGPUDrivenUpdate(
	TEXT("r.LumenScene.GPUDrivenUpdate"),
	0,
	TEXT("Whether to use GPU to update Lumen Scene. Work in progress."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginUpdateLumenSceneTasks

Source code excerpt:

	const FLumenSceneReadback::FRemoveOp* SceneRemoveOpsReadbackData = nullptr;

	if (CVarLumenSceneGPUDrivenUpdate.GetValueOnRenderThread() != 0)
	{
		QUICK_SCOPE_CYCLE_COUNTER(LockSceneReadbackBuffer);

		FLumenSceneReadback::FBuffersRHI ReadbackBuffers = LumenSceneData.SceneReadback.GetLatestReadbackBuffers();

		FrameTemporaries.SceneAddOpsReadbackBuffer = ReadbackBuffers.AddOps;

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginUpdateLumenSceneTasks
lambda-function

Source code excerpt:

			TArray<FSurfaceCacheRequest, SceneRenderingAllocator> SurfaceCacheRequests;

			if (CVarLumenSceneGPUDrivenUpdate.GetValueOnRenderThread() != 0)
			{
				ProcessSceneRemoveOpsReadbackData(LumenSceneData, SceneRemoveOpsReadbackData);
				ProcessSceneAddOpsReadbackData(LumenSceneData, SceneAddOpsReadbackData);
			}
			else
			{

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::UpdateLumenScene

Source code excerpt:

		Lumen::UpdateCardSceneBuffer(GraphBuilder, FrameTemporaries, ViewFamily, Scene);

		if (CVarLumenSceneGPUDrivenUpdate.GetValueOnRenderThread() != 0)
		{
			LumenScene::GPUDrivenUpdate(GraphBuilder, Scene, Views, FrameTemporaries);
		}

		// Init transient render targets for capturing cards
		FCardCaptureAtlas CardCaptureAtlas;