r.Lumen.Visualize.CardPlacementDirection

r.Lumen.Visualize.CardPlacementDirection

#Overview

name: r.Lumen.Visualize.CardPlacementDirection

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

• type: Var
• help: Visualize only a single card direction.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Visualize.CardPlacementDirection is to provide a visualization tool for Lumen’s card placement system in Unreal Engine 5. This setting variable is primarily used for debugging and development purposes within the Lumen global illumination system.

This setting variable is part of the Renderer module, specifically within the Lumen subsystem of Unreal Engine 5. It is used in the visualization and debugging features of Lumen’s card placement system.

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 through console commands.

This variable interacts directly with GVisualizeLumenCardPlacementDirection. They share the same value, with GVisualizeLumenCardPlacementDirection being the actual integer variable used in the code, while r.Lumen.Visualize.CardPlacementDirection is the console command to set its value.

Developers must be aware that this variable is intended for visualization purposes only. Setting it to a value other than -1 will cause the engine to visualize only cards in a single direction, which may not represent the full Lumen scene.

Best practices when using this variable include:

1. Use it primarily for debugging and development purposes.
2. Remember to reset it to -1 (the default value) when not actively debugging to ensure normal visualization of all card directions.
3. Use in conjunction with other Lumen visualization tools for a comprehensive understanding of the card placement system.

Regarding the associated variable GVisualizeLumenCardPlacementDirection:

The purpose of GVisualizeLumenCardPlacementDirection is to store the actual value used by the engine for visualizing Lumen card placement direction. It’s the internal representation of the r.Lumen.Visualize.CardPlacementDirection setting.

This variable is used directly in the Renderer module, specifically in the Lumen visualization code. It’s checked when determining which cards to visualize based on their axis-aligned direction index.

The value of this variable is set indirectly through the r.Lumen.Visualize.CardPlacementDirection console command.

It interacts primarily with the r.Lumen.Visualize.CardPlacementDirection setting, as well as with the card visualization logic in the Lumen system.

Developers should be aware that this variable directly affects the visualization output. A value of -1 means all directions are visualized, while any other value will filter the visualization to show only cards in that specific direction.

Best practices for using this variable include:

1. Access it only through the r.Lumen.Visualize.CardPlacementDirection console command in most cases.
2. Be cautious about modifying it directly in code, as it’s intended to be controlled via the console variable system.
3. Always consider the performance implications of visualization features in production 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:234

Scope: file

Source code excerpt:

int32 GVisualizeLumenCardPlacementDirection = -1;
FAutoConsoleVariableRef CVarVisualizeLumenSceneCardPlacementDirection(
	TEXT("r.Lumen.Visualize.CardPlacementDirection"),
	GVisualizeLumenCardPlacementDirection,
	TEXT("Visualize only a single card direction."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneDumpStats = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GVisualizeLumenCardPlacementDirection = -1;
FAutoConsoleVariableRef CVarVisualizeLumenSceneCardPlacementDirection(
	TEXT("r.Lumen.Visualize.CardPlacementDirection"),
	GVisualizeLumenCardPlacementDirection,
	TEXT("Visualize only a single card direction."),
	ECVF_RenderThreadSafe
);

int32 GLumenSceneDumpStats = 0;
FAutoConsoleVariableRef CVarLumenSceneDumpStats(

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

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));
									CardHash = HashCombine(CardHash, GetTypeHash(Card.IndexInBuildData));