r.LumenScene.Lighting.Stats

r.LumenScene.Lighting.Stats

#Overview

name: r.LumenScene.Lighting.Stats

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

• type: Var
• help: GPU print out Lumen lighting update stats.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.Lighting.Stats is to control the output of GPU-based Lumen lighting update statistics. This setting variable is part of the Lumen lighting system in Unreal Engine 5’s rendering subsystem.

The Lumen rendering module relies on this setting variable, specifically within the scene lighting component of Lumen. It is used in the LumenSceneLighting.cpp file, which is part of the Renderer module in Unreal Engine.

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

This variable interacts directly with GLumenLightingStats, which is an integer variable that shares the same value. GLumenLightingStats is used in the actual code logic to determine whether to output lighting stats and what type of stats to output.

Developers must be aware that enabling this variable (setting it to a non-zero value) will impact performance, as it enables additional GPU computations for statistics gathering. It should primarily be used for debugging and performance analysis, not in shipping builds.

Best practices when using this variable include:

1. Only enable it when necessary for debugging or performance analysis.
2. Be mindful of the performance impact when enabled.
3. Use different non-zero values to potentially output different levels or types of statistics, as indicated by the LightingStatMode parameter.

Regarding the associated variable GLumenLightingStats:

The purpose of GLumenLightingStats is to store the actual value of the r.LumenScene.Lighting.Stats setting. It’s an integer variable that determines whether and how to output Lumen lighting update statistics.

This variable is used directly in the Lumen scene lighting code to control the behavior of statistics output. It’s checked in the BuildCardUpdateContext function to determine if shader printing should be enabled and what type of lighting stats should be computed.

The value of GLumenLightingStats is set through the r.LumenScene.Lighting.Stats console variable.

Developers should be aware that changing GLumenLightingStats directly in code won’t have the desired effect, as its value is controlled by the console variable system. Always use the r.LumenScene.Lighting.Stats console variable to modify this setting.

Best practices for GLumenLightingStats include:

1. Treat it as a read-only variable in most code contexts.
2. Use it for conditional logic related to stats output in Lumen lighting code.
3. Remember that non-zero values enable stats output, potentially with different modes based on the specific value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:46

Scope: file

Source code excerpt:

int32 GLumenLightingStats = 0;
FAutoConsoleVariableRef CVarLumenSceneLightingStats(
	TEXT("r.LumenScene.Lighting.Stats"),
	GLumenLightingStats,
	TEXT("GPU print out Lumen lighting update stats."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneLightingAsyncCompute(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:44

Scope: file

Source code excerpt:

);

int32 GLumenLightingStats = 0;
FAutoConsoleVariableRef CVarLumenSceneLightingStats(
	TEXT("r.LumenScene.Lighting.Stats"),
	GLumenLightingStats,
	TEXT("GPU print out Lumen lighting update stats."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneLightingAsyncCompute(
	TEXT("r.LumenScene.Lighting.AsyncCompute"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:712

Scope (from outer to inner):

file
function     void Lumen::BuildCardUpdateContext

Source code excerpt:

	}

	if (GLumenLightingStats != 0)
	{
		ShaderPrint::SetEnabled(true);

		FLumenSceneLightingStatsCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FLumenSceneLightingStatsCS::FParameters>();
		ShaderPrint::SetParameters(GraphBuilder, Views[0].ShaderPrintData, PassParameters->ShaderPrintUniformBuffer);
		PassParameters->LumenCardScene = FrameTemporaries.LumenCardSceneUniformBuffer;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneLighting.cpp:725

Scope (from outer to inner):

file
function     void Lumen::BuildCardUpdateContext

Source code excerpt:

		PassParameters->CardPageTileAllocator = GraphBuilder.CreateSRV(CardPageTileAllocator);
		PassParameters->CardPageNum = LumenSceneData.GetNumCardPages();
		PassParameters->LightingStatMode = GLumenLightingStats;

		auto ComputeShader = Views[0].ShaderMap->GetShader<FLumenSceneLightingStatsCS>();

		FComputeShaderUtils::AddPass(
			GraphBuilder,
			RDG_EVENT_NAME("SceneLightingStats"),