r.LumenScene.SurfaceCache.RecaptureEveryFrame

r.LumenScene.SurfaceCache.RecaptureEveryFrame

#Overview

name: r.LumenScene.SurfaceCache.RecaptureEveryFrame

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

• type: Var
• help: ``

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.RecaptureEveryFrame is to control the recapture behavior of the Lumen Scene Surface Cache in Unreal Engine 5’s rendering system. Specifically, it’s used in the Lumen Global Illumination (GI) system, which is part of UE5’s advanced lighting and rendering features.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s referenced in files related to Lumen scene rendering and radiosity calculations.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It’s defined and initialized in the LumenSceneRendering.cpp file.

The associated variable GLumenSceneRecaptureLumenSceneEveryFrame interacts directly with this setting. They share the same value, and GLumenSceneRecaptureLumenSceneEveryFrame is used in the actual code logic.

Developers should be aware that:

1. Setting this variable to a non-zero value will force the Lumen Scene to be recaptured every frame, which can have significant performance implications.
2. It’s used to control debug behavior, as seen in the BeginUpdateLumenSceneTasks function where it sets a debug flag to clear all cached state.
3. When enabled, it overrides the normal tile capture limit, setting it to INT32_MAX in the GetMaxTileCapturesPerFrame function.

Best practices for using this variable include:

1. Use it primarily for debugging or diagnostics, not in production builds.
2. Be cautious of performance impacts when enabling it, especially in complex scenes.
3. Use in conjunction with other Lumen debug tools and settings for comprehensive analysis.

Regarding the associated variable GLumenSceneRecaptureLumenSceneEveryFrame:

Its purpose is to serve as the actual int32 variable that controls the behavior within the C++ code. It’s used in the same way as r.LumenScene.SurfaceCache.RecaptureEveryFrame, but it’s the internal representation that the code checks against.

This variable is used in the Lumen rendering system, specifically in scene rendering and radiosity calculations.

Its value is set by the console variable system, mirroring r.LumenScene.SurfaceCache.RecaptureEveryFrame.

It directly interacts with the logic controlling Lumen Scene recapture and influences debug behavior and tile capture limits.

Developers should be aware that this is the actual variable checked in conditional statements throughout the Lumen rendering code.

Best practices include using this variable for fine-grained control in custom rendering code if needed, but generally, it’s preferable to use the console variable for configuration.

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

Scope: file

Source code excerpt:

int32 GLumenSceneRecaptureLumenSceneEveryFrame = 0;
FAutoConsoleVariableRef CVarLumenGIRecaptureLumenSceneEveryFrame(
	TEXT("r.LumenScene.SurfaceCache.RecaptureEveryFrame"),
	GLumenSceneRecaptureLumenSceneEveryFrame,
	TEXT(""),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheLogUpdates = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadiosity.cpp:998

Scope: file

Source code excerpt:

	FLumenSceneData& LumenSceneData = *Scene->GetLumenSceneData(Views[0]);

	extern int32 GLumenSceneRecaptureLumenSceneEveryFrame;

	if (LumenRadiosity::IsEnabled(ViewFamily)
		&& LumenSceneData.bFinalLightingAtlasContentsValid
		&& CardUpdateContext.MaxUpdateTiles > 0)
	{
		RDG_EVENT_SCOPE(GraphBuilder, "Radiosity");

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneRecaptureLumenSceneEveryFrame = 0;
FAutoConsoleVariableRef CVarLumenGIRecaptureLumenSceneEveryFrame(
	TEXT("r.LumenScene.SurfaceCache.RecaptureEveryFrame"),
	GLumenSceneRecaptureLumenSceneEveryFrame,
	TEXT(""),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheLogUpdates = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheLogUpdates(

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

Scope (from outer to inner):

file
function     int32 GetMaxTileCapturesPerFrame

Source code excerpt:

	}

	if (GLumenSceneRecaptureLumenSceneEveryFrame != 0)
	{
		return INT32_MAX;
	}

	return GetMaxLumenSceneCardCapturesPerFrame();
}

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginUpdateLumenSceneTasks

Source code excerpt:

	FLumenSceneData& LumenSceneData = *Scene->GetLumenSceneData(Views[0]);
	LumenSceneData.bDebugClearAllCachedState = GLumenSceneRecaptureLumenSceneEveryFrame != 0;
	FrameTemporaries.bReallocateAtlas = LumenSceneData.UpdateAtlasSize();

	FLumenSceneData::FFeedbackData SurfaceCacheFeedbackData;
	{
		extern int32 GLumenSurfaceCacheFeedback;
		if (GLumenSurfaceCacheFeedback != 0)