r.LumenScene.SurfaceCache.Compress

r.LumenScene.SurfaceCache.Compress

#Overview

name: r.LumenScene.SurfaceCache.Compress

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

• type: Var
• help: Whether to use run time compression for surface cache.\n0 - Disabled\n1 - Compress using UAV aliasing if supported\n2 - Compress using CopyTexture (may be very slow on some RHIs)\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.Compress is to control the compression method used for the Lumen surface cache in Unreal Engine 5’s rendering system. This setting variable is part of the Lumen global illumination system, which is a key feature of UE5’s rendering capabilities.

The Lumen rendering subsystem relies on this setting variable to determine how to compress the surface cache, which is an important data structure for storing and accessing lighting information.

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

The associated variable GLumenSurfaceCacheCompress interacts directly with r.LumenScene.SurfaceCache.Compress. They share the same value, with GLumenSurfaceCacheCompress being the actual integer variable used in the code.

Developers must be aware that this variable has three possible values: 0 - Disabled (no compression) 1 - Compress using UAV aliasing if supported 2 - Compress using CopyTexture (which may be very slow on some RHIs)

Best practices when using this variable include:

1. Consider the performance implications of each setting, especially on different hardware.
2. Test thoroughly when changing this value, as it can affect both performance and visual quality.
3. Be cautious when using value 2 (CopyTexture), as it may cause significant performance issues on some render hardware interfaces (RHIs).

Regarding GLumenSurfaceCacheCompress: This is the actual integer variable that stores the compression setting. It’s used in the FLumenSceneData::UpdateAtlasSize function to determine the compression method for the surface cache. The function checks the value of GLumenSurfaceCacheCompress and the capabilities of the rendering hardware (GRHISupportsUAVFormatAliasing) to decide on the appropriate compression method.

Developers should be aware that changes to GLumenSurfaceCacheCompress will directly affect the behavior of the Lumen surface cache compression. It’s important to ensure that any code modifying this variable does so in a thread-safe manner, as it’s accessed in rendering-related functions.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSurfaceCache.cpp:12

Scope: file

Source code excerpt:

int32 GLumenSurfaceCacheCompress = 1;
FAutoConsoleVariableRef CVarLumenSurfaceCacheCompress(
	TEXT("r.LumenScene.SurfaceCache.Compress"),
	GLumenSurfaceCacheCompress,
	TEXT("Whether to use run time compression for surface cache.\n")
	TEXT("0 - Disabled\n")
	TEXT("1 - Compress using UAV aliasing if supported\n")
	TEXT("2 - Compress using CopyTexture (may be very slow on some RHIs)\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:1142

Scope (from outer to inner):

file
function     bool FLumenSceneData::UpdateAtlasSize

Source code excerpt:

bool FLumenSceneData::UpdateAtlasSize()
{
	extern int32 GLumenSurfaceCacheCompress;

	ESurfaceCacheCompression NewCompression = ESurfaceCacheCompression::Disabled;
	if (GLumenSurfaceCacheCompress == 1 && GRHISupportsUAVFormatAliasing)
	{
		NewCompression = ESurfaceCacheCompression::UAVAliasing;
	}
	else if (GLumenSurfaceCacheCompress == 2)
	{
		NewCompression = ESurfaceCacheCompression::CopyTextureRegion;
	}

	if (PhysicalAtlasSize != GetDesiredPhysicalAtlasSize(SurfaceCacheResolution) || PhysicalAtlasCompression != NewCompression)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSurfaceCache.cpp:10

Scope: file

Source code excerpt:

#include "LumenRadiosity.h"

int32 GLumenSurfaceCacheCompress = 1;
FAutoConsoleVariableRef CVarLumenSurfaceCacheCompress(
	TEXT("r.LumenScene.SurfaceCache.Compress"),
	GLumenSurfaceCacheCompress,
	TEXT("Whether to use run time compression for surface cache.\n")
	TEXT("0 - Disabled\n")
	TEXT("1 - Compress using UAV aliasing if supported\n")
	TEXT("2 - Compress using CopyTexture (may be very slow on some RHIs)\n"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);