r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages

r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages

#Overview

name: r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages

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

• type: Var
• help: Num frames to keep unused pages in surface cache.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages is to control the number of frames that unused pages in the Lumen scene surface cache are kept before being evicted. This setting is part of the Lumen global illumination system in Unreal Engine 5’s rendering pipeline.

The Unreal Engine subsystem that relies on this setting variable is the Lumen rendering system, specifically the surface cache component of Lumen scene rendering. This can be inferred from the file location (LumenSceneRendering.cpp) and the variable name itself.

The value of this variable is set through the Unreal Engine’s console variable system. It’s initialized with a default value of 256 frames and can be modified at runtime using the console command system.

This variable interacts directly with its associated C++ variable GSurfaceCacheNumFramesToKeepUnusedPages. They share the same value, with the console variable acting as an interface for runtime modification.

Developers must be aware that this variable affects memory usage and rendering performance. A higher value will keep unused pages in memory longer, potentially increasing memory usage but reducing the need for re-rendering those pages if they become needed again. Conversely, a lower value will free up memory more quickly but might lead to more frequent re-rendering of pages.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of the game or application.
2. Monitoring memory usage and rendering performance when modifying this value.
3. Finding a balance between memory usage and rendering performance.

Regarding the associated variable GSurfaceCacheNumFramesToKeepUnusedPages:

The purpose of GSurfaceCacheNumFramesToKeepUnusedPages is to store the actual value used by the rendering system for determining how long to keep unused pages in the surface cache.

This variable is used directly in the Lumen scene rendering system, specifically in the FLumenSceneData::ProcessLumenSurfaceCacheRequests function.

The value of this variable is set by the console variable r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages.

It interacts with the EvictOldestAllocation function, which uses this value to determine which allocations in the surface cache should be evicted.

Developers should be aware that modifying this variable directly in code (rather than through the console variable) may lead to inconsistencies with the console variable value.

Best practices for this variable include:

1. Avoiding direct modification in code, instead using the console variable for changes.
2. Using it in conjunction with other Lumen scene rendering parameters for optimal performance.
3. Considering its impact on memory usage and rendering performance when optimizing the Lumen system.

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

Scope: file

Source code excerpt:

int32 GSurfaceCacheNumFramesToKeepUnusedPages = 256;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheNumFramesToKeepUnusedPages(
	TEXT("r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages"),
	GSurfaceCacheNumFramesToKeepUnusedPages,
	TEXT("Num frames to keep unused pages in surface cache."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneForceEvictHiResPages = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GSurfaceCacheNumFramesToKeepUnusedPages = 256;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheNumFramesToKeepUnusedPages(
	TEXT("r.LumenScene.SurfaceCache.NumFramesToKeepUnusedPages"),
	GSurfaceCacheNumFramesToKeepUnusedPages,
	TEXT("Num frames to keep unused pages in surface cache."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneForceEvictHiResPages = 0;
FAutoConsoleVariableRef CVarLumenSceneForceEvictHiResPages(

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

Scope (from outer to inner):

file
function     void FLumenSceneData::ProcessLumenSurfaceCacheRequests

Source code excerpt:

	if (!Lumen::IsSurfaceCacheFrozen())
	{
		uint32 MaxFramesSinceLastUsed = FMath::Max(GSurfaceCacheNumFramesToKeepUnusedPages, 0);
		while (EvictOldestAllocation(MaxFramesSinceLastUsed, DirtyCards))
		{
		}
	}

	for (int32 CardIndex : DirtyCards.Array)