r.RectLightAtlas.ForceUpdate

r.RectLightAtlas.ForceUpdate

#Overview

name: r.RectLightAtlas.ForceUpdate

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

• type: Var
• help: Force rect. light atlas update very frame.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RectLightAtlas.ForceUpdate is to control the update frequency of the rectangular light atlas in Unreal Engine 5’s rendering system. This setting variable is specifically designed for the lighting and rendering subsystems.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the RectLightTextureManager component. Based on the callsites, it’s evident that this variable is crucial for managing the rectangular light atlas updates.

The value of this variable is set through a console variable (CVarRectLighForceUpdate) with a default value of 0. It can be modified at runtime using console commands or through engine configuration files.

The associated variable CVarRectLighForceUpdate directly interacts with r.RectLightAtlas.ForceUpdate. They share the same value and purpose.

Developers must be aware that setting this variable to a value greater than 0 will force the rectangular light atlas to update every frame. This can have significant performance implications, especially in scenes with many rectangular lights or on less powerful hardware.

Best practices when using this variable include:

1. Keep it at the default value (0) for normal operation.
2. Only enable it (set to 1) when debugging lighting issues or when rapid updates to rectangular lights are absolutely necessary.
3. Be cautious about enabling this in shipping builds, as it can impact performance.
4. Use in conjunction with other lighting and rendering settings for comprehensive debugging.

Regarding the associated variable CVarRectLighForceUpdate:

The purpose of CVarRectLighForceUpdate is identical to r.RectLightAtlas.ForceUpdate. It’s the actual console variable implementation that controls the force update behavior of the rectangular light atlas.

This variable is used within the Renderer module, specifically in the RectLightTextureManager component. It’s queried in the UpdateAtlasTexture function to determine if a force update of the atlas is required.

The value of CVarRectLighForceUpdate is set when the console variable is created, with a default value of 0. It can be modified at runtime using console commands.

CVarRectLighForceUpdate interacts directly with other rendering variables, such as CVarRectLightTextureResolution, to determine when to force an update of the atlas layout.

Developers should be aware that this variable is checked on the render thread, which means changes to its value will take effect immediately in the rendering pipeline.

Best practices for using CVarRectLighForceUpdate include:

1. Use it in conjunction with other debugging tools when investigating lighting issues.
2. Remember to reset it to 0 after debugging to ensure optimal performance.
3. Consider the impact on performance when enabling this in development or shipping builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RectLightTextureManager.cpp:47

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarRectLighForceUpdate(
	TEXT("r.RectLightAtlas.ForceUpdate"),
	0,
	TEXT("Force rect. light atlas update very frame."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRectLighFilterQuality(
	TEXT("r.RectLightAtlas.FilterQuality"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RectLightTextureManager.cpp:46

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRectLighForceUpdate(
	TEXT("r.RectLightAtlas.ForceUpdate"),
	0,
	TEXT("Force rect. light atlas update very frame."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRectLighFilterQuality(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RectLightTextureManager.cpp:1538

Scope (from outer to inner):

file
namespace    RectLightAtlas
function     void UpdateAtlasTexture

Source code excerpt:

	// Force update by resetting the atlas layout
	static int32 CachedMaxAtlasResolution = CVarRectLightTextureResolution.GetValueOnRenderThread();
	const bool bForceUpdate = CVarRectLighForceUpdate.GetValueOnRenderThread() > 0 || CachedMaxAtlasResolution != CVarRectLightTextureResolution.GetValueOnRenderThread();
	if (bForceUpdate)
	{
		CachedMaxAtlasResolution = CVarRectLightTextureResolution.GetValueOnRenderThread();
		GRectLightTextureManager.bHasPendingAdds = true;
		GRectLightTextureManager.AtlasLayout = FAtlasLayout(FIntPoint(CachedMaxAtlasResolution, CachedMaxAtlasResolution));
		for (FAtlasSlot& Slot : GRectLightTextureManager.AtlasSlots)