r.LumenScene.SurfaceCache.ForceEvictHiResPages

r.LumenScene.SurfaceCache.ForceEvictHiResPages

#Overview

name: r.LumenScene.SurfaceCache.ForceEvictHiResPages

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.ForceEvictHiResPages is to control the eviction of high-resolution surface cache pages 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 pipeline.

This setting variable is primarily used in the Lumen scene rendering subsystem, which is part of the Renderer module in Unreal Engine 5. It specifically affects the surface cache management within the Lumen scene.

The value of this variable is set through the Unreal Engine console variable system, as evidenced by the FAutoConsoleVariableRef declaration. It can be changed at runtime using console commands or through code.

The associated variable GLumenSceneForceEvictHiResPages directly interacts with r.LumenScene.SurfaceCache.ForceEvictHiResPages. They share the same value, and GLumenSceneForceEvictHiResPages is used in the actual code logic to determine when to evict the surface cache pages.

Developers must be aware that setting this variable to a non-zero value will trigger the eviction of all optional high-resolution surface cache pages in the Lumen scene. This can have a significant impact on rendering performance and quality, as it forces the system to rebuild these cache pages.

Best practices when using this variable include:

  1. Use it sparingly, primarily for debugging or testing purposes.
  2. Be aware of the performance implications when enabling it.
  3. Reset the value to 0 after use, as the code automatically does in the BeginUpdateLumenSceneTasks function.
  4. Consider the impact on visual quality when evicting high-resolution cache pages.

Regarding the associated variable GLumenSceneForceEvictHiResPages:

The purpose of GLumenSceneForceEvictHiResPages is to serve as the internal representation of the r.LumenScene.SurfaceCache.ForceEvictHiResPages console variable within the C++ code.

This variable is used directly in the Lumen scene rendering system, specifically in the BeginUpdateLumenSceneTasks function of the FDeferredShadingSceneRenderer class.

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

It interacts with the LumenSceneData object, triggering the ForceEvictEntireCache() method when set to a non-zero value.

Developers should be aware that this variable is automatically reset to 0 after triggering the cache eviction, ensuring that the eviction only occurs once per setting.

Best practices for using GLumenSceneForceEvictHiResPages include:

  1. Avoid modifying it directly in code; instead, use the console variable system to change its value.
  2. Be mindful of its performance impact when set to a non-zero value.
  3. Use it in conjunction with other Lumen scene debugging tools for comprehensive analysis.

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

Scope: file

Source code excerpt:

int32 GLumenSceneForceEvictHiResPages = 0;
FAutoConsoleVariableRef CVarLumenSceneForceEvictHiResPages(
	TEXT("r.LumenScene.SurfaceCache.ForceEvictHiResPages"),
	GLumenSceneForceEvictHiResPages,
	TEXT("Evict all optional hi-res surface cache pages."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneRecaptureLumenSceneEveryFrame = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneForceEvictHiResPages = 0;
FAutoConsoleVariableRef CVarLumenSceneForceEvictHiResPages(
	TEXT("r.LumenScene.SurfaceCache.ForceEvictHiResPages"),
	GLumenSceneForceEvictHiResPages,
	TEXT("Evict all optional hi-res surface cache pages."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneRecaptureLumenSceneEveryFrame = 0;
FAutoConsoleVariableRef CVarLumenGIRecaptureLumenSceneEveryFrame(

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginUpdateLumenSceneTasks
lambda-function

Source code excerpt:

		}

		if (GLumenSceneForceEvictHiResPages != 0)
		{
			LumenSceneData.ForceEvictEntireCache();
			GLumenSceneForceEvictHiResPages = 0;
		}

		LumenSceneData.NumMeshCardsToAdd = 0;
		LumenSceneData.NumLockedCardsToUpdate = 0;
		LumenSceneData.NumHiResPagesToAdd = 0;