r.LumenScene.Lighting.ForceLightingUpdate

r.LumenScene.Lighting.ForceLightingUpdate

#Overview

name: r.LumenScene.Lighting.ForceLightingUpdate

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

• type: Var
• help: Force full Lumen Scene Lighting update every frame. Useful for debugging

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.Lighting.ForceLightingUpdate is to force a full Lumen Scene Lighting update every frame, which is primarily used for debugging purposes in the Lumen global illumination system of Unreal Engine 5.

This setting variable is primarily used in the Lumen rendering subsystem, specifically in the Lumen Scene Lighting module. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of 0, meaning the forced update is not enabled by default.

This variable interacts with the associated variable CVarLumenSceneLightingForceFullUpdate, which is the actual console variable object. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to a non-zero value) will force a full lighting update every frame, which can have a significant performance impact. It should only be used for debugging purposes and not in production builds.

Best practices when using this variable include:

1. Only enable it temporarily for debugging lighting issues.
2. Remember to disable it after debugging to avoid performance degradation.
3. Use it in conjunction with other Lumen debugging tools for comprehensive analysis.

Regarding the associated variable CVarLumenSceneLightingForceFullUpdate:

The purpose of CVarLumenSceneLightingForceFullUpdate is to provide a programmatic interface to control the r.LumenScene.Lighting.ForceLightingUpdate setting within the engine’s code.

This console variable is defined in the Lumen Scene Lighting module and is used to retrieve the current value of the setting in the render thread.

The value of this variable is set through the console variable system, just like r.LumenScene.Lighting.ForceLightingUpdate.

It directly interacts with the rendering code, specifically in the SetLightingUpdateAtlasSize function, where it’s used to determine if a full lighting update should be forced.

Developers should be aware that this variable is marked as render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed from the render thread.

Best practices for using this variable in code include:

1. Always access it using the GetValueOnRenderThread() method when in render thread code.
2. Consider the performance implications of enabling this feature in performance-critical sections of code.
3. Use it judiciously and only when necessary for debugging purposes.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:14

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenSceneLightingForceFullUpdate(
	TEXT("r.LumenScene.Lighting.ForceLightingUpdate"),
	0,
	TEXT("Force full Lumen Scene Lighting update every frame. Useful for debugging"),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneLightingFeedback = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:13

Scope: file

Source code excerpt:

#include "LumenRadiosity.h"

static TAutoConsoleVariable<int32> CVarLumenSceneLightingForceFullUpdate(
	TEXT("r.LumenScene.Lighting.ForceLightingUpdate"),
	0,
	TEXT("Force full Lumen Scene Lighting update every frame. Useful for debugging"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:89

Scope (from outer to inner):

file
function     void SetLightingUpdateAtlasSize

Source code excerpt:

	if (!Lumen::IsSurfaceCacheFrozen())
	{
		if (CVarLumenSceneLightingForceFullUpdate.GetValueOnRenderThread() != 0)
		{
			Context.UpdateFactor = 1;
		}

		const float MultPerComponent = 1.0f / FMath::Sqrt((float)Context.UpdateFactor);