r.LumenScene.SurfaceCache.FreezeUpdateFrame

r.LumenScene.SurfaceCache.FreezeUpdateFrame

#Overview

name: r.LumenScene.SurfaceCache.FreezeUpdateFrame

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.FreezeUpdateFrame is to freeze the updating of a subset of the Lumen surface cache for debugging and profiling purposes in Unreal Engine’s rendering system.

This setting variable is primarily used by the Lumen global illumination system, which is part of Unreal Engine’s rendering module. It’s specifically related to the surface cache component of Lumen, which stores lighting information for the scene.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as an integer (int32) and can be modified at runtime using console commands.

The associated variable GLumenSurfaceCacheFreezeUpdateFrame directly interacts with this setting. They share the same value, and GLumenSurfaceCacheFreezeUpdateFrame is used in the actual code logic to control the freezing behavior.

Developers must be aware that this variable is intended for debugging and profiling purposes only. Enabling it in a production environment could lead to incorrect lighting updates and reduced visual quality. It’s also important to note that this setting is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it affects performance scaling and is safe to modify from the render thread.

Best practices when using this variable include:

  1. Only enable it temporarily for debugging or profiling specific issues related to the Lumen surface cache.
  2. Remember to disable it after debugging to ensure normal Lumen functionality.
  3. Use in conjunction with other Lumen debugging tools for comprehensive analysis.
  4. Be cautious when modifying it in a multiplayer environment, as it could lead to inconsistent visual results across different clients.

Regarding the associated variable GLumenSurfaceCacheFreezeUpdateFrame:

The purpose of GLumenSurfaceCacheFreezeUpdateFrame is to serve as the actual storage for the r.LumenScene.SurfaceCache.FreezeUpdateFrame setting within the C++ code.

This variable is used directly in the Lumen subsystem of the Unreal Engine’s rendering module. It’s checked in the IsSurfaceCacheUpdateFrameFrozen() function to determine if the surface cache update should be frozen.

The value of GLumenSurfaceCacheFreezeUpdateFrame is set automatically by the engine when r.LumenScene.SurfaceCache.FreezeUpdateFrame is modified through console commands.

It interacts with another variable, GLumenSurfaceCacheFreeze, in the IsSurfaceCacheUpdateFrameFrozen() function. The frame is considered frozen if either of these variables is non-zero.

Developers should be aware that modifying GLumenSurfaceCacheFreezeUpdateFrame directly in code is not recommended. Instead, they should use the r.LumenScene.SurfaceCache.FreezeUpdateFrame console variable to control this behavior.

Best practices for GLumenSurfaceCacheFreezeUpdateFrame include:

  1. Treat it as a read-only variable in most scenarios.
  2. Use the IsSurfaceCacheUpdateFrameFrozen() function to check its state rather than accessing it directly.
  3. If custom logic involving this variable is needed, consider the implications on the entire Lumen system and consult with the rendering team.

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

Scope: file

Source code excerpt:

int32 GLumenSurfaceCacheFreezeUpdateFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreezeUpdateFrame(
	TEXT("r.LumenScene.SurfaceCache.FreezeUpdateFrame"),
	GLumenSurfaceCacheFreezeUpdateFrame,
	TEXT("Keep updating the same subset of surface cache for debugging and profiling.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheReset = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSurfaceCacheFreezeUpdateFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreezeUpdateFrame(
	TEXT("r.LumenScene.SurfaceCache.FreezeUpdateFrame"),
	GLumenSurfaceCacheFreezeUpdateFrame,
	TEXT("Keep updating the same subset of surface cache for debugging and profiling.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSceneSurfaceCacheReset = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheReset(

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

Scope (from outer to inner):

file
function     bool Lumen::IsSurfaceCacheUpdateFrameFrozen

Source code excerpt:

bool Lumen::IsSurfaceCacheUpdateFrameFrozen()
{
	return GLumenSurfaceCacheFreeze != 0 || GLumenSurfaceCacheFreezeUpdateFrame != 0;
}

int32 GetCardMaxResolution()
{
	if (GLumenFastCameraMode)
	{