r.LumenScene.Stats

r.LumenScene.Stats

#Overview

name: r.LumenScene.Stats

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

• type: Var
• help: Display various Lumen GPU Scene stats for debugging.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.Stats is to enable the display of various Lumen GPU Scene statistics for debugging purposes. This setting is part of the Lumen rendering system in Unreal Engine 5, which is responsible for real-time global illumination.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the Lumen subsystem. Based on the callsites, it’s clear that this variable is utilized in the LumenSceneGPUDrivenUpdate.cpp file, which is part of the Lumen scene rendering process.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning the stats display is disabled by default.

The associated variable CVarLumenSceneStats directly interacts with r.LumenScene.Stats. They share the same value and purpose, with CVarLumenSceneStats being the C++ representation of the console variable.

Developers should be aware that enabling this variable (setting it to a non-zero value) will cause the engine to display debug statistics related to the Lumen GPU Scene. This can be useful for performance analysis and debugging but may impact performance when enabled.

Best practices for using this variable include:

1. Only enable it when necessary for debugging or performance analysis.
2. Be mindful of potential performance impact when enabled in production builds.
3. Use in conjunction with other Lumen debugging tools for comprehensive analysis.

Regarding the associated variable CVarLumenSceneStats:

The purpose of CVarLumenSceneStats is to provide programmatic access to the r.LumenScene.Stats setting within the C++ code. It allows developers to check and react to the current state of the stats display setting in the rendering code.

This variable is used in the Renderer module, specifically in the Lumen scene update process. It’s checked in the GPUDrivenUpdate function to determine whether to enable shader printing and set up parameters for the Lumen scene stats computation.

The value of CVarLumenSceneStats is set automatically by the console variable system when r.LumenScene.Stats is modified.

Developers should be aware that checking the value of CVarLumenSceneStats (using GetValueOnRenderThread()) is done on the render thread, ensuring thread-safe access to the variable’s value.

Best practices for using CVarLumenSceneStats include:

1. Always access its value using GetValueOnRenderThread() when in render thread code.
2. Use it to conditionally execute debug or stats-related code, ensuring minimal impact on performance when stats are disabled.
3. Consider the performance implications of frequently checking this value in performance-critical sections of code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:41

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenSceneStats(
	TEXT("r.LumenScene.Stats"),
	0,
	TEXT("Display various Lumen GPU Scene stats for debugging."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneVisualizePrimitiveGroups(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:40

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenSceneStats(
	TEXT("r.LumenScene.Stats"),
	0,
	TEXT("Display various Lumen GPU Scene stats for debugging."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneGPUDrivenUpdate.cpp:374

Scope (from outer to inner):

file
function     void LumenScene::GPUDrivenUpdate

Source code excerpt:

	}

	if (CVarLumenSceneStats.GetValueOnRenderThread() != 0)
	{
		ShaderPrint::SetEnabled(true);

		FLumenSceneStatsCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FLumenSceneStatsCS::FParameters>();
		ShaderPrint::SetParameters(GraphBuilder, Views[0].ShaderPrintData, PassParameters->ShaderPrintUniformBuffer);
		PassParameters->View = Views[0].ViewUniformBuffer;