r.LumenScene.SurfaceCache.MeshCardsMinSize

r.LumenScene.SurfaceCache.MeshCardsMinSize

#Overview

name: r.LumenScene.SurfaceCache.MeshCardsMinSize

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

• type: Var
• help: Minimum mesh cards world space size to be included in Lumen Scene.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.MeshCardsMinSize is to set the minimum world space size for mesh cards to be included in the Lumen Scene. This setting is part of Unreal Engine 5’s Lumen global illumination system, which is a key component of the rendering subsystem.

The Lumen rendering system relies on this setting variable to determine which mesh cards should be included in the Lumen Scene. It’s specifically used in the LumenMeshCards module, which is part of the Renderer subsystem.

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

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

Developers must be aware that changing this variable will trigger a recreation of render states for global components. This is evident from the FGlobalComponentRecreateRenderStateContext being created in the console variable delegate.

Best practices when using this variable include:

1. Carefully consider the performance implications of setting this value too low, as it could include many small mesh cards in the Lumen Scene, potentially impacting performance.
2. Be aware that changes to this variable will cause a recreation of render states, which could cause a momentary hitch in performance.
3. Use this in conjunction with other Lumen settings to fine-tune the balance between visual quality and performance.
4. When adjusting this value, test thoroughly across different scenes to ensure it doesn’t negatively impact visual quality or performance.

Regarding the associated variable CVarLumenMeshCardsMinSize:

This is the actual console variable object that stores and manages the r.LumenScene.SurfaceCache.MeshCardsMinSize setting. It’s used directly in the LumenMeshCards::GetCardMinSurfaceArea function to retrieve the current value of the setting.

When working with CVarLumenMeshCardsMinSize, developers should:

1. Use GetValueOnRenderThread() when accessing the value from render thread code.
2. Be aware that this variable can be changed at runtime, so code using it should be prepared to handle dynamic changes.
3. Consider caching the value if it’s used frequently in performance-critical code, but be sure to update the cached value when the CVar changes.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<float> CVarLumenMeshCardsMinSize(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMinSize"),
	10.0f,
	TEXT("Minimum mesh cards world space size to be included in Lumen Scene."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;
	}),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "InstanceDataSceneProxy.h"

TAutoConsoleVariable<float> CVarLumenMeshCardsMinSize(
	TEXT("r.LumenScene.SurfaceCache.MeshCardsMinSize"),
	10.0f,
	TEXT("Minimum mesh cards world space size to be included in Lumen Scene."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)
	{
		FGlobalComponentRecreateRenderStateContext Context;

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

Scope (from outer to inner):

file
function     float LumenMeshCards::GetCardMinSurfaceArea

Source code excerpt:

float LumenMeshCards::GetCardMinSurfaceArea(bool bEmissiveLightSource)
{
	const float MeshCardsMinSize = CVarLumenMeshCardsMinSize.GetValueOnRenderThread();
	return MeshCardsMinSize * MeshCardsMinSize * (bEmissiveLightSource ? 0.2f : 1.0f);
}

class FLumenCardGPUData
{
public: