r.LumenScene.SurfaceCache.CardCaptureRefreshFraction

r.LumenScene.SurfaceCache.CardCaptureRefreshFraction

#Overview

name: r.LumenScene.SurfaceCache.CardCaptureRefreshFraction

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

• type: Var
• help: Fraction of card capture budget allowed to be spent on re-capturing existing pages in order to refresh surface cache materials.\n0 disables card refresh.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.CardCaptureRefreshFraction is to control the fraction of card capture budget allowed for re-capturing existing pages to refresh surface cache materials in the Lumen Scene rendering system.

This setting variable is primarily used in the Lumen Scene rendering subsystem of Unreal Engine 5. It’s part of the global illumination and lighting system, specifically related to the Surface Cache functionality in Lumen.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 0.125f (12.5%) in the C++ code.

The associated variable CVarLumenSceneCardCaptureRefreshFraction interacts directly with this setting. It’s used to retrieve the value of the setting in the render thread.

Developers must be aware that:

1. This variable affects performance and visual quality of the Lumen global illumination system.
2. Setting it to 0 disables card refresh completely.
3. The value is clamped between 0 and 1 when used.

Best practices when using this variable include:

1. Adjust it carefully based on the specific needs of your scene and performance requirements.
2. Monitor its impact on frame rate and visual quality when modifying it.
3. Consider lowering it on less powerful hardware for better performance.

Regarding the associated variable CVarLumenSceneCardCaptureRefreshFraction:

• It’s used to access the value of r.LumenScene.SurfaceCache.CardCaptureRefreshFraction in the render thread.
• It’s used in the FLumenSceneData class to calculate the number of texels and pages for card capture refresh.
• When using this variable, always use GetValueOnRenderThread() to ensure thread-safe access.
• The value is typically clamped between 0 and 1 before use, as seen in the GetCardCaptureRefreshNumTexels and GetCardCaptureRefreshNumPages functions.

Developers should be cautious when modifying this value, as it directly impacts the balance between visual quality and performance in the Lumen lighting system.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<float> CVarLumenSceneCardCaptureRefreshFraction(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureRefreshFraction"),
	0.125f,
	TEXT("Fraction of card capture budget allowed to be spent on re-capturing existing pages in order to refresh surface cache materials.\n")
	TEXT("0 disables card refresh."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<float> CVarLumenSceneCardCaptureRefreshFraction(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureRefreshFraction"),
	0.125f,
	TEXT("Fraction of card capture budget allowed to be spent on re-capturing existing pages in order to refresh surface cache materials.\n")
	TEXT("0 disables card refresh."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

uint32 FLumenSceneData::GetCardCaptureRefreshNumTexels() const
{
	const float CardCaptureRefreshFraction = FMath::Clamp(CVarLumenSceneCardCaptureRefreshFraction.GetValueOnRenderThread(), 0.0f, 1.0f);
	if (CardCaptureRefreshFraction > 0.0f)
	{
		// Allow to capture at least 1 full physical page
		FIntPoint CardCaptureAtlasSize = GetCardCaptureAtlasSize();
		return FMath::Max(CardCaptureAtlasSize.X * CardCaptureAtlasSize.Y * CardCaptureRefreshFraction, Lumen::PhysicalPageSize * Lumen::PhysicalPageSize);
	}

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

Scope (from outer to inner):

file
function     uint32 FLumenSceneData::GetCardCaptureRefreshNumPages

Source code excerpt:

uint32 FLumenSceneData::GetCardCaptureRefreshNumPages() const
{
	const float CardCaptureRefreshFraction = FMath::Clamp(CVarLumenSceneCardCaptureRefreshFraction.GetValueOnRenderThread(), 0.0f, 1.0f);
	if (CardCaptureRefreshFraction > 0.0f)
	{
		// Allow to capture at least 1 full physical page
		return FMath::Clamp(GetMaxTileCapturesPerFrame() * CardCaptureRefreshFraction, 1, GetMaxTileCapturesPerFrame());
	}