r.Lumen.SurfaceCache.HeightfieldCaptureMargin

r.Lumen.SurfaceCache.HeightfieldCaptureMargin

#Overview

name: r.Lumen.SurfaceCache.HeightfieldCaptureMargin

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

• type: Var
• help: Amount to expand heightfield component bbox for card capture purposes.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.SurfaceCache.HeightfieldCaptureMargin is to control the expansion of the heightfield component bounding box for card capture purposes in Unreal Engine’s Lumen global illumination system.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Specifically, it’s utilized in the mesh card generation process for heightfields, which is a part of Lumen’s surface cache mechanism.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 100.0f, but can be changed at runtime through console commands or project settings.

The associated variable CVarLumenSurfaceCacheHeightfieldCaptureMargin directly interacts with r.Lumen.SurfaceCache.HeightfieldCaptureMargin. They share the same value and purpose.

Developers must be aware that this variable affects the size of the capture area for heightfield components in Lumen’s surface cache. A larger value will expand the capture area, potentially improving lighting quality at the cost of performance and memory usage.

Best practices when using this variable include:

1. Adjusting it based on the scale and detail of your heightfield landscapes.
2. Balancing between lighting quality and performance impact.
3. Testing different values to find the optimal setting for your specific scene.

Regarding the associated variable CVarLumenSurfaceCacheHeightfieldCaptureMargin:

It’s an auto console variable of type float, created to provide runtime access to the r.Lumen.SurfaceCache.HeightfieldCaptureMargin setting. It’s defined in the Lumen mesh cards system and is used directly in the BuildMeshCardsDataForHeightfield function to calculate the bounds margin for heightfield components.

The value of CVarLumenSurfaceCacheHeightfieldCaptureMargin is retrieved on the render thread, indicating that it can be safely modified in real-time without causing thread safety issues.

When working with this variable, developers should consider its impact on the Lumen surface cache system and adjust it in conjunction with other Lumen settings for optimal results.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:116

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarLumenSurfaceCacheHeightfieldCaptureMargin(
	TEXT("r.Lumen.SurfaceCache.HeightfieldCaptureMargin"),
	100.0f,
	TEXT("Amount to expand heightfield component bbox for card capture purposes."),
	ECVF_RenderThreadSafe
);

extern int32 GLumenSceneUploadEveryFrame;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:115

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarLumenSurfaceCacheHeightfieldCaptureMargin(
	TEXT("r.Lumen.SurfaceCache.HeightfieldCaptureMargin"),
	100.0f,
	TEXT("Amount to expand heightfield component bbox for card capture purposes."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenMeshCards.cpp:614

Scope (from outer to inner):

file
function     void BuildMeshCardsDataForHeightfield

Source code excerpt:

	// Make sure that the card isn't placed directly on the geometry
	const FVector BoundsMargin = FVector(CVarLumenSurfaceCacheHeightfieldCaptureMargin.GetValueOnRenderThread()) / MeshCardsLocalToWorld.GetScaleVector();

	MeshCardsBuildData.Bounds = Proxy->GetLocalBounds().GetBox().ExpandBy(BoundsMargin);

	// Add a single top down card
	MeshCardsBuildData.CardBuildData.SetNum(1);
	{