r.LumenScene.SurfaceCache.CardCaptureMargin

r.LumenScene.SurfaceCache.CardCaptureMargin

#Overview

name: r.LumenScene.SurfaceCache.CardCaptureMargin

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

• type: Var
• help: How far from Lumen scene range start to capture cards.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.CardCaptureMargin is to control the distance from the Lumen scene range start at which cards are captured in the Lumen scene surface cache system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically related to scene management and rendering optimization.

The Lumen Scene module within the Renderer subsystem relies on this setting variable. It’s used in the GPU-driven update process for Lumen scenes, as evident from its presence in the LumenSceneGPUDrivenUpdate.cpp file.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0.0f, but can be modified at runtime or through configuration files.

This variable interacts directly with its associated variable CVarLumenSceneCardCaptureMargin. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the performance and quality trade-off in Lumen’s global illumination system. Increasing the margin will capture cards further from the scene range start, potentially improving quality at the cost of performance.

Best practices when using this variable include:

1. Carefully balancing performance and visual quality.
2. Testing different values to find the optimal setting for specific scenes.
3. Considering the impact on memory usage, as capturing cards over a larger area may increase memory consumption.

Regarding the associated variable CVarLumenSceneCardCaptureMargin:

The purpose of CVarLumenSceneCardCaptureMargin is to provide a programmatic interface to the r.LumenScene.SurfaceCache.CardCaptureMargin setting. It allows the engine to read and potentially modify this value during runtime.

This variable is used within the LumenScene class, specifically in the GetCardMaxDistance function. It’s added to the MaxCardDistanceFromCamera to determine the final maximum distance for card capture.

The value of this variable is set through the CVar system and can be accessed using the GetValueOnRenderThread() method, ensuring thread-safe access in render thread contexts.

Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate depending on the current state of rendering.

Best practices for using CVarLumenSceneCardCaptureMargin include:

1. Accessing the value using GetValueOnRenderThread() when in render thread contexts.
2. Considering the performance implications of frequently changing this value.
3. Using this variable in conjunction with other Lumen settings for comprehensive control over the global illumination system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:34

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarLumenSceneCardCaptureMargin(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureMargin"),
	0.0f,
	TEXT("How far from Lumen scene range start to capture cards."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneStats(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:33

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarLumenSceneCardCaptureMargin(
	TEXT("r.LumenScene.SurfaceCache.CardCaptureMargin"),
	0.0f,
	TEXT("How far from Lumen scene range start to capture cards."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:76

Scope (from outer to inner):

file
function     float LumenScene::GetCardMaxDistance

Source code excerpt:

#endif

	return MaxCardDistanceFromCamera + CVarLumenSceneCardCaptureMargin.GetValueOnRenderThread();
}

float LumenScene::GetCardTexelDensity()
{
	return CVarLumenSceneCardTexelDensityScale.GetValueOnRenderThread() * (GLumenFastCameraMode ? .2f : 1.0f);
}