r.LumenScene.SurfaceCache.CardCaptureFactor

r.LumenScene.SurfaceCache.CardCaptureFactor

#Overview

name: r.LumenScene.SurfaceCache.CardCaptureFactor

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.CardCaptureFactor is to control the number of texels that can be captured per frame in the Lumen Scene Surface Cache system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically for managing the surface cache used in real-time lighting calculations.

The Lumen Scene rendering subsystem relies on this setting variable. It is primarily used in the LumenSceneRendering module, which is responsible for handling the Lumen global illumination system’s scene rendering tasks.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of 64 and can be modified at runtime using console commands or through engine configuration files.

This variable interacts closely with its associated variable GLumenSceneCardCaptureFactor. They share the same value, with GLumenSceneCardCaptureFactor being the actual integer variable used in the C++ code to store and access the value.

Developers must be aware that this variable affects performance and quality trade-offs in the Lumen system. A lower value will allow more texels to be captured per frame, potentially improving lighting quality but at the cost of performance. Conversely, a higher value will limit the number of texels captured, which may improve performance but could reduce lighting quality or update speed.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your project and target hardware capabilities.
  2. Testing different values to find the optimal balance between lighting quality and performance.
  3. Considering it in conjunction with other Lumen settings for a holistic approach to global illumination quality and performance.

Regarding the associated variable GLumenSceneCardCaptureFactor:

The purpose of GLumenSceneCardCaptureFactor is to store the actual integer value used in the Lumen Scene rendering calculations. It directly corresponds to the r.LumenScene.SurfaceCache.CardCaptureFactor console variable.

This variable is used within the Lumen Scene rendering subsystem, particularly in the LumenSceneRendering module.

Its value is set by the console variable system and is directly manipulated when r.LumenScene.SurfaceCache.CardCaptureFactor is changed.

GLumenSceneCardCaptureFactor interacts with various parts of the Lumen Scene rendering code, such as in the GetCardCaptureAtlasSizeInPages function, where it’s used to calculate the size of the capture atlas.

Developers should be aware that modifying GLumenSceneCardCaptureFactor directly in code is not recommended, as it should be controlled through the console variable system to ensure consistency.

Best practices include:

  1. Always use the console variable (r.LumenScene.SurfaceCache.CardCaptureFactor) to modify this value rather than changing GLumenSceneCardCaptureFactor directly.
  2. Consider the impact on performance and quality when adjusting this value, as it directly affects the Lumen Scene surface cache behavior.

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

Scope: file

Source code excerpt:

int32 GLumenSceneCardCaptureFactor = 64;
FAutoConsoleVariableRef CVarLumenSceneCardCaptureFactor(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureFactor"),
	GLumenSceneCardCaptureFactor,
	TEXT("Controls how many texels can be captured per frame. Texels = SurfaceCacheTexels / Factor."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarLumenSceneSurfaceCacheRemovesPerFrame(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenSceneCardCaptureFactor = 64;
FAutoConsoleVariableRef CVarLumenSceneCardCaptureFactor(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureFactor"),
	GLumenSceneCardCaptureFactor,
	TEXT("Controls how many texels can be captured per frame. Texels = SurfaceCacheTexels / Factor."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarLumenSceneSurfaceCacheRemovesPerFrame(
	TEXT("r.LumenScene.SurfaceCache.RemovesPerFrame"),

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

Scope: file

Source code excerpt:

FIntPoint FLumenSceneData::GetCardCaptureAtlasSizeInPages() const
{
	const float MultPerComponent = 1.0f / FMath::Sqrt(FMath::Clamp(GLumenSceneCardCaptureFactor, 1.0f, 1024.0f));

	FIntPoint CaptureAtlasSizeInPages;
	CaptureAtlasSizeInPages.X = FMath::DivideAndRoundUp<uint32>(PhysicalAtlasSize.X * MultPerComponent + 0.5f, Lumen::PhysicalPageSize);
	CaptureAtlasSizeInPages.Y = FMath::DivideAndRoundUp<uint32>(PhysicalAtlasSize.Y * MultPerComponent + 0.5f, Lumen::PhysicalPageSize);
	return CaptureAtlasSizeInPages;
}