r.LumenScene.SurfaceCache.Freeze

r.LumenScene.SurfaceCache.Freeze

#Overview

name: r.LumenScene.SurfaceCache.Freeze

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.Freeze is to freeze surface cache updates in the Lumen rendering system for debugging purposes. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, which is a core component of the rendering subsystem.

The Lumen rendering system, specifically the surface cache component, relies on this setting variable. It is used within the Renderer module of Unreal Engine 5.

The value of this variable is set through the console variable system, as evidenced by the FAutoConsoleVariableRef declaration. It can be modified at runtime using console commands or through configuration files.

This variable interacts directly with the GLumenSurfaceCacheFreeze variable, which shares the same value. It’s also used in conjunction with GLumenSurfaceCacheFreezeUpdateFrame to determine if the surface cache update frame is frozen.

Developers must be aware that this variable is intended for debugging purposes only. Freezing the surface cache updates can significantly impact the visual quality and performance of the Lumen global illumination system. It should not be used in production builds or during normal gameplay.

Best practices when using this variable include:

  1. Only enable it temporarily for debugging specific issues related to the Lumen surface cache.
  2. Remember to disable it after debugging to restore normal Lumen functionality.
  3. Use it in conjunction with other Lumen debugging tools and variables for comprehensive analysis.
  4. Be cautious when modifying this variable in a shipping build, as it may negatively affect performance and visual quality.

Regarding the associated variable GLumenSurfaceCacheFreeze:

The purpose of GLumenSurfaceCacheFreeze is to store the actual value of the r.LumenScene.SurfaceCache.Freeze console variable. It is an integer variable that determines whether the Lumen surface cache updates are frozen.

This variable is used within the Renderer module, specifically in the Lumen rendering system. It’s directly accessed in the IsSurfaceCacheFrozen() and IsSurfaceCacheUpdateFrameFrozen() functions, which are likely used throughout the Lumen rendering code to determine if updates should be processed.

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

GLumenSurfaceCacheFreeze interacts with GLumenSurfaceCacheFreezeUpdateFrame in the IsSurfaceCacheUpdateFrameFrozen() function to determine if the update frame is frozen.

Developers should be aware that this variable directly affects the behavior of the Lumen surface cache. A non-zero value will freeze updates, which can be useful for debugging but should not be left enabled during normal operation.

Best practices for using GLumenSurfaceCacheFreeze include:

  1. Avoid modifying this variable directly; instead, use the r.LumenScene.SurfaceCache.Freeze console variable.
  2. When reading this variable in code, consider using the provided Lumen::IsSurfaceCacheFrozen() function for consistency and potential future-proofing.
  3. Be mindful of its impact on performance and visual quality when enabled.

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

Scope: file

Source code excerpt:

int32 GLumenSurfaceCacheFreeze = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreeze(
	TEXT("r.LumenScene.SurfaceCache.Freeze"),
	GLumenSurfaceCacheFreeze,
	TEXT("Freeze surface cache updates for debugging.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSurfaceCacheFreezeUpdateFrame = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSurfaceCacheFreeze = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreeze(
	TEXT("r.LumenScene.SurfaceCache.Freeze"),
	GLumenSurfaceCacheFreeze,
	TEXT("Freeze surface cache updates for debugging.\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenSurfaceCacheFreezeUpdateFrame = 0;
FAutoConsoleVariableRef CVarLumenSceneSurfaceCacheFreezeUpdateFrame(

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

Scope (from outer to inner):

file
function     bool Lumen::IsSurfaceCacheFrozen

Source code excerpt:

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

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

int32 GetCardMaxResolution()
{
	if (GLumenFastCameraMode)
	{