r.LumenScene.PropagateGlobalLightingChange

r.LumenScene.PropagateGlobalLightingChange

#Overview

name: r.LumenScene.PropagateGlobalLightingChange

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

• type: Var
• help: Whether to detect big scene lighting changes and speedup Lumen update for those frames.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.PropagateGlobalLightingChange is to control whether Lumen, Unreal Engine 5’s global illumination system, should detect significant changes in scene lighting and accelerate its update process for those frames.

This setting variable is primarily used by the Lumen subsystem within the Unreal Engine 5 renderer. It is part of the global illumination and rendering pipeline, specifically affecting how Lumen responds to changes in the scene’s lighting conditions.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1 (enabled) in the C++ code, but can be modified at runtime through console commands or project settings.

The associated variable CVarLumenScenePropagateGlobalLightingChange directly interacts with r.LumenScene.PropagateGlobalLightingChange. They share the same value and purpose.

Developers should be aware that this variable can significantly impact the performance and visual quality of the Lumen global illumination system. When enabled (set to 1), it allows Lumen to quickly adapt to major lighting changes in the scene, potentially improving visual quality at the cost of some performance. When disabled (set to 0), Lumen may update more gradually in response to lighting changes, which could be less visually accurate but potentially more performance-friendly.

Best practices for using this variable include:

1. Keeping it enabled (1) for most scenarios to ensure responsive and accurate global illumination.
2. Consider disabling it (0) in performance-critical situations where lighting changes are infrequent or less important.
3. Testing the impact of this setting in your specific scene to find the right balance between visual quality and performance.
4. Using it in conjunction with other Lumen settings to fine-tune the global illumination system for your project’s needs.

Regarding the associated variable CVarLumenScenePropagateGlobalLightingChange:

This is the actual console variable that controls the r.LumenScene.PropagateGlobalLightingChange setting. It is defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime through the console or configuration files.

The variable is used in the UpdateGlobalLightingState function to determine whether to propagate global lighting changes. If the value is 0, bPropagateGlobalLightingChange is set to false, effectively disabling the feature.

Developers should use this variable name (CVarLumenScenePropagateGlobalLightingChange) when accessing or modifying the setting programmatically in C++ code. For example, they might use CVarLumenScenePropagateGlobalLightingChange.GetValueOnRenderThread() to read the current value or set it using console commands.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenScenePropagateGlobalLightingChange(
	TEXT("r.LumenScene.PropagateGlobalLightingChange"),
	1,
	TEXT("Whether to detect big scene lighting changes and speedup Lumen update for those frames."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneGPUDrivenUpdate(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarLumenScenePropagateGlobalLightingChange(
	TEXT("r.LumenScene.PropagateGlobalLightingChange"),
	1,
	TEXT("Whether to detect big scene lighting changes and speedup Lumen update for those frames."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool UpdateGlobalLightingState

Source code excerpt:

	}

	if (CVarLumenScenePropagateGlobalLightingChange.GetValueOnRenderThread() == 0)
	{
		bPropagateGlobalLightingChange = false;
	}

	return bPropagateGlobalLightingChange;
}