r.Lumen.Visualize.CardPlacementIndex

r.Lumen.Visualize.CardPlacementIndex

#Overview

name: r.Lumen.Visualize.CardPlacementIndex

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

• type: Var
• help: Visualize only a single card per mesh.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Visualize.CardPlacementIndex is to provide a debugging and visualization tool for Lumen’s card placement system in Unreal Engine 5. It allows developers to isolate and visualize a single card per mesh in the Lumen global illumination system.

This setting variable is primarily used by the Lumen subsystem within the Rendering module of Unreal Engine 5. It’s specifically utilized in the visualization and debugging processes for Lumen’s card placement.

The value of this variable is set through the Unreal Engine console or configuration files. It’s defined as an FAutoConsoleVariableRef, which means it can be changed at runtime.

The variable interacts directly with GVisualizeLumenCardPlacementIndex, which is the associated C++ variable that stores the actual value. It also indirectly interacts with GVisualizeLumenCardPlacementDirection, as they are often used together for more precise visualization control.

Developers must be aware that this variable is intended for debugging and visualization purposes only. It should not be used in production code or relied upon for gameplay functionality. When set to a value >= 0, it will cause only a single card per mesh to be visualized, which can significantly alter the visual output of the Lumen system.

Best practices for using this variable include:

1. Use it temporarily for debugging card placement issues.
2. Reset it to -1 (default value) after debugging to visualize all cards.
3. Combine it with other Lumen visualization tools for comprehensive debugging.
4. Be cautious when using it in a shipping build, as it may impact performance or visual quality.

Regarding the associated variable GVisualizeLumenCardPlacementIndex:

The purpose of GVisualizeLumenCardPlacementIndex is to store the actual value of the card index to be visualized. It directly corresponds to r.Lumen.Visualize.CardPlacementIndex.

This variable is used within the Lumen visualization system in the Rendering module. It’s referenced in the VisualizeCardPlacement function and other parts of the LumenVisualize.cpp file.

The value of GVisualizeLumenCardPlacementIndex is set by the FAutoConsoleVariableRef mechanism, which binds it to the r.Lumen.Visualize.CardPlacementIndex console variable.

It interacts closely with the Card.IndexInMeshCards property of Lumen cards and is often used in conjunction with GVisualizeLumenCardPlacementDirection for more granular control over card visualization.

Developers should be aware that this variable directly controls which card is visualized when the visualization system is active. A value of -1 means all cards are visualized, while a value >= 0 will isolate a specific card.

Best practices include using this variable judiciously for debugging, ensuring it’s reset to -1 after use, and being mindful of its performance impact when active in development builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:226

Scope: file

Source code excerpt:

int32 GVisualizeLumenCardPlacementIndex = -1;
FAutoConsoleVariableRef CVarVisualizeLumenSceneCardPlacementIndex(
	TEXT("r.Lumen.Visualize.CardPlacementIndex"),
	GVisualizeLumenCardPlacementIndex,
	TEXT("Visualize only a single card per mesh."),
	ECVF_RenderThreadSafe
);

int32 GVisualizeLumenCardPlacementDirection = -1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:224

Scope: file

Source code excerpt:

);

int32 GVisualizeLumenCardPlacementIndex = -1;
FAutoConsoleVariableRef CVarVisualizeLumenSceneCardPlacementIndex(
	TEXT("r.Lumen.Visualize.CardPlacementIndex"),
	GVisualizeLumenCardPlacementIndex,
	TEXT("Visualize only a single card per mesh."),
	ECVF_RenderThreadSafe
);

int32 GVisualizeLumenCardPlacementDirection = -1;
FAutoConsoleVariableRef CVarVisualizeLumenSceneCardPlacementDirection(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:1178

Scope (from outer to inner):

file
function     void VisualizeCardPlacement

Source code excerpt:

				bVisible = Card.bVisible;

				if (GVisualizeLumenCardPlacementIndex >= 0 && Card.IndexInMeshCards != GVisualizeLumenCardPlacementIndex)
				{
					bVisible = false;
				}

				if (bVisible)
				{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:1291

Scope: file

Source code excerpt:

								if (Card.bVisible
									&& (Card.IndexInMeshCards == GVisualizeLumenCardPlacementIndex || GVisualizeLumenCardPlacementIndex < 0)
									&& (Card.AxisAlignedDirectionIndex == GVisualizeLumenCardPlacementDirection || GVisualizeLumenCardPlacementDirection < 0)
									&& Card.IndexInBuildData < DebugData.Clusters.Num())
								{
									const FLumenCardBuildDebugData::FSurfelCluster& Cluster = DebugData.Clusters[Card.IndexInBuildData];

									uint32 CardHash = HashCombine(GetTypeHash(Card.LocalOBB.Origin), GetTypeHash(Card.LocalOBB.Extent));