r.LumenScene.SurfaceCache.ResetEveryNthFrame

r.LumenScene.SurfaceCache.ResetEveryNthFrame

#Overview

name: r.LumenScene.SurfaceCache.ResetEveryNthFrame

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

• type: Var
• help: Continuously reset all atlases and captured cards every N-th frame.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.ResetEveryNthFrame is to control the periodic resetting of Lumen scene surface caches in Unreal Engine 5’s rendering system. This setting is specifically related to the Lumen global illumination system, which is part of UE5’s advanced rendering capabilities.

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

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files.

The associated C++ variable GLumenSceneSurfaceCacheResetEveryNthFrame directly interacts with this setting. They share the same value, and the C++ variable is used in the actual rendering code to determine when to reset the surface cache.

Developers must be aware that this variable is intended for debugging and optimization purposes. Setting a non-zero value will cause the Lumen system to reset all atlases and captured cards periodically, which can impact performance and visual consistency.

Best practices when using this variable include:

1. Keeping it set to 0 (disabled) for normal operation and final builds.
2. Using it judiciously during development for debugging rendering issues or optimizing Lumen performance.
3. Being aware that frequent resets can impact frame rate and visual stability.

Regarding the associated variable GLumenSceneSurfaceCacheResetEveryNthFrame:

The purpose of GLumenSceneSurfaceCacheResetEveryNthFrame is to provide a C++ accessible counterpart to the console variable. It’s used directly in the rendering code to implement the periodic reset functionality.

This variable is used within the Renderer module, specifically in the Lumen scene rendering process. It’s checked in the BeginUpdateLumenSceneTasks function to determine if a reset should occur on the current frame.

The value of this variable is set by the console variable system when r.LumenScene.SurfaceCache.ResetEveryNthFrame is modified.

It interacts directly with the ViewFamily.FrameNumber to determine when to trigger a reset, and it influences the LumenSceneData.bDebugClearAllCachedState flag.

Developers should be aware that modifying this variable directly in C++ code is not recommended, as it may get overwritten by the console variable system. Instead, they should use the console variable for configuration.

Best practices include using this variable only for reading its value in the rendering code, and relying on the console variable system for setting and modifying its value during development and debugging.

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

Scope: file

Source code excerpt:

int32 GLumenSceneSurfaceCacheResetEveryNthFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheResetEveryNthFrame(
	TEXT("r.LumenScene.SurfaceCache.ResetEveryNthFrame"),
	GLumenSceneSurfaceCacheResetEveryNthFrame,
	TEXT("Continuously reset all atlases and captured cards every N-th frame.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneCardCapturesPerFrame = 300;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneSurfaceCacheResetEveryNthFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheResetEveryNthFrame(
	TEXT("r.LumenScene.SurfaceCache.ResetEveryNthFrame"),
	GLumenSceneSurfaceCacheResetEveryNthFrame,
	TEXT("Continuously reset all atlases and captured cards every N-th frame.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneCardCapturesPerFrame = 300;
FAutoConsoleVariableRef CVarLumenSceneCardCapturesPerFrame(

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginUpdateLumenSceneTasks
lambda-function

Source code excerpt:

		// Surface cache reset for debugging
		if ((GLumenSceneSurfaceCacheReset != 0)
			|| (GLumenSceneSurfaceCacheResetEveryNthFrame > 0 && (ViewFamily.FrameNumber % (uint32)GLumenSceneSurfaceCacheResetEveryNthFrame == 0)))
		{
			LumenSceneData.bDebugClearAllCachedState = true;
			GLumenSceneSurfaceCacheReset = 0;
		}

		if (GLumenSceneForceEvictHiResPages != 0)