r.LumenScene.SurfaceCache.Reset

r.LumenScene.SurfaceCache.Reset

#Overview

name: r.LumenScene.SurfaceCache.Reset

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.Reset is to reset all atlases and captured cards in the Lumen scene rendering system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, which is a key component of the rendering subsystem.

The Lumen scene rendering module relies on this setting variable, as evident from its usage in the LumenSceneRendering.cpp file. This variable is primarily used for debugging and development purposes.

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

The associated variable GLumenSceneSurfaceCacheReset interacts directly with r.LumenScene.SurfaceCache.Reset. They share the same value, and changes to one will affect the other.

Developers must be aware that this variable is intended for debugging purposes. Setting it to a non-zero value will trigger a reset of all atlases and captured cards in the Lumen scene, which can have a significant impact on rendering performance and visual quality during development and testing.

Best practices when using this variable include:

  1. Use it sparingly and only when necessary for debugging or development purposes.
  2. Be aware that resetting the surface cache can cause temporary visual artifacts as the cache rebuilds.
  3. Consider using it in conjunction with GLumenSceneSurfaceCacheResetEveryNthFrame for periodic resets during testing.

Regarding the associated variable GLumenSceneSurfaceCacheReset:

The purpose of GLumenSceneSurfaceCacheReset is to serve as the internal representation of the r.LumenScene.SurfaceCache.Reset console variable within the engine’s C++ code.

This variable is used directly in the Lumen scene rendering module, specifically in the DebugResetSurfaceCache() function and in the BeginUpdateLumenSceneTasks function of the FDeferredShadingSceneRenderer class.

The value of GLumenSceneSurfaceCacheReset is set either through the console variable system or directly in code, as seen in the DebugResetSurfaceCache() function where it’s set to 1.

It interacts with GLumenSceneSurfaceCacheResetEveryNthFrame to determine when to reset the surface cache, either immediately or on a periodic basis.

Developers should be aware that this variable is reset to 0 after triggering a surface cache reset, as seen in the BeginUpdateLumenSceneTasks function.

Best practices for using GLumenSceneSurfaceCacheReset include:

  1. Use it in conjunction with the console variable system for easier debugging and testing.
  2. Be cautious when setting it directly in code, as it can have immediate effects on the rendering system.
  3. Always consider the performance implications of resetting the surface cache, especially in performance-critical sections of your game.

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

Scope: file

Source code excerpt:

int32 GLumenSceneSurfaceCacheReset = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheReset(
	TEXT("r.LumenScene.SurfaceCache.Reset"),
	GLumenSceneSurfaceCacheReset,
	TEXT("Reset all atlases and captured cards.\n"),	
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheResetEveryNthFrame = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneSurfaceCacheReset = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheReset(
	TEXT("r.LumenScene.SurfaceCache.Reset"),
	GLumenSceneSurfaceCacheReset,
	TEXT("Reset all atlases and captured cards.\n"),	
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheResetEveryNthFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheResetEveryNthFrame(

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

Scope (from outer to inner):

file
function     void Lumen::DebugResetSurfaceCache

Source code excerpt:

void Lumen::DebugResetSurfaceCache()
{
	GLumenSceneSurfaceCacheReset = 1;
}

bool Lumen::IsSurfaceCacheFrozen()
{
	return GLumenSurfaceCacheFreeze != 0;
}

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

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)
		{
			LumenSceneData.ForceEvictEntireCache();
			GLumenSceneForceEvictHiResPages = 0;