r.Lumen.Visualize

r.Lumen.Visualize

#Overview

name: r.Lumen.Visualize

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

• type: Var
• help: Lumen scene visualization mode.\n0 - Disable\n1 - Overview\n2 - Performance Overview\n3 - Lumen Scene\n4 - Reflection View\n5 - Surface Cache Coverage\n6 - Geometry normals\n7 - Dedicated Reflection Rays\n8 - Albedo\n9 - Normals\n10 - Emissive\n11 - Opacity (disable alpha masking)\n12 - Card weights\n13 - Direct lighting\n14 - Indirect lighting\n15 - Local Position (hardware ray-tracing only)\n16 - Velocity (hardware ray-tracing only)\n17 - Direct lighting updates\n18 - Indirect lighting updates\n19 - Last used pages\n20 - Last used high res pages

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.Visualize is to control the visualization mode for Lumen, Unreal Engine’s global illumination and reflections system. It allows developers to debug and analyze various aspects of Lumen’s performance and functionality.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenVisualize.cpp and LumenVisualizationData.cpp files, which are part of the Renderer and Engine modules respectively.

The value of this variable is set through the console variable system in Unreal Engine. It can be modified at runtime using console commands or through project settings.

The associated variable GLumenVisualize interacts directly with r.Lumen.Visualize. They share the same value, with GLumenVisualize being the actual integer variable that stores the visualization mode.

Developers should be aware that this variable offers multiple visualization modes, each providing different insights into Lumen’s operation: 0 - Disable 1 - Overview 2 - Performance Overview 3 - Lumen Scene 4 - Reflection View 5 - Surface Cache 6 - Geometry Normals

When using this variable, best practices include:

1. Use it primarily for debugging and performance analysis, not in shipping builds.
2. Be aware that enabling visualization modes may impact performance.
3. Combine with other Lumen-related console variables for comprehensive debugging.
4. Use in conjunction with Unreal Engine’s visualization tools and performance profilers.

Regarding the associated variable GLumenVisualize:

• Its purpose is to store the actual integer value of the visualization mode.
• It’s used internally by the Lumen system to determine which visualization mode is active.
• The value is set through the r.Lumen.Visualize console variable.
• It interacts directly with the ShouldVisualizeScene and GetLumenVisualizeMode functions.
• Developers should not modify GLumenVisualize directly, but instead use the r.Lumen.Visualize console variable.
• Best practice is to treat GLumenVisualize as a read-only variable within the codebase, relying on the console variable system for modifications.

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

Scope: file

Source code excerpt:

int32 GLumenVisualize = 0;
FAutoConsoleVariableRef CVarLumenVisualize(
	TEXT("r.Lumen.Visualize"),
	GLumenVisualize,
	TEXT("Lumen scene visualization mode.\n")
	TEXT("0 - Disable\n")
	TEXT("1 - Overview\n")
	TEXT("2 - Performance Overview\n")
	TEXT("3 - Lumen Scene\n")

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LumenVisualizationData.cpp:8

Scope: file

Source code excerpt:

static FLumenVisualizationData GLumenVisualizationData;

// Must match appropriate values in r.Lumen.Visualize
#define LUMEN_VISUALIZE_OVERVIEW					1
#define LUMEN_VISUALIZE_PERFORMANCE_OVERVIEW		2
#define LUMEN_VISUALIZE_LUMEN_SCENE					3
#define LUMEN_VISUALIZE_REFLECTION_VIEW				4
#define LUMEN_VISUALIZE_SURFACE_CACHE				5
#define LUMEN_VISUALIZE_MODE_GEOMETRY_NORMALS		6

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

// Must be in sync with VISUALIZE_MODE_* in LumenVisualize.h
int32 GLumenVisualize = 0;
FAutoConsoleVariableRef CVarLumenVisualize(
	TEXT("r.Lumen.Visualize"),
	GLumenVisualize,
	TEXT("Lumen scene visualization mode.\n")
	TEXT("0 - Disable\n")
	TEXT("1 - Overview\n")
	TEXT("2 - Performance Overview\n")
	TEXT("3 - Lumen Scene\n")
	TEXT("4 - Reflection View\n")

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

Scope (from outer to inner):

file
function     bool Lumen::ShouldVisualizeScene

Source code excerpt:

bool Lumen::ShouldVisualizeScene(const FEngineShowFlags& ShowFlags)
{
	return ShowFlags.VisualizeLumen || GLumenVisualize > 0;
}

bool LumenVisualize::UseSurfaceCacheFeedback(const FEngineShowFlags& ShowFlags)
{
	return CVarVisualizeLumenSceneSurfaceCacheFeedback.GetValueOnRenderThread() != 0
		&& Lumen::ShouldVisualizeScene(ShowFlags);

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

Scope (from outer to inner):

file
function     int32 GetLumenVisualizeMode

Source code excerpt:

{
	const FLumenVisualizationData& VisualizationData = GetLumenVisualizationData();
	const int32 VisualizeMode = GLumenVisualize > 0 ? GLumenVisualize : VisualizationData.GetModeID(View.CurrentLumenVisualizationMode);
	return VisualizeMode;
}

FScreenPassTexture AddVisualizeLumenScenePass(FRDGBuilder& GraphBuilder, const FViewInfo& View, bool bAnyLumenActive, bool bLumenGIEnabled, const FVisualizeLumenSceneInputs& Inputs, FLumenSceneFrameTemporaries& FrameTemporaries)
{
	check(Inputs.SceneColor.IsValid());