r.LumenScene.DirectLighting.BatchShadows

r.LumenScene.DirectLighting.BatchShadows

#Overview

name: r.LumenScene.DirectLighting.BatchShadows

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.DirectLighting.BatchShadows is to control the batching of Lumen light shadow passes in the rendering system. This setting variable is primarily used for debugging purposes within the Lumen Scene Direct Lighting subsystem of Unreal Engine 5.

This setting variable is relied upon by the Renderer module, specifically within the Lumen subsystem for direct lighting calculations. It is used in the LumenSceneDirectLighting.cpp file, which is part of the core rendering pipeline for Lumen, Unreal Engine 5’s global illumination system.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1, meaning batching is enabled by default. Developers can modify this value at runtime using console commands or through project settings.

This variable interacts directly with its associated variable CVarLumenDirectLightingBatchShadows. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable primarily exists for debugging purposes. Changing its value may impact the performance and visual quality of Lumen’s direct lighting calculations, particularly in how shadow passes are processed.

Best practices when using this variable include:

  1. Keeping it enabled (set to 1) for optimal performance in most scenarios.
  2. Only disabling it (set to 0) when debugging specific issues related to Lumen’s direct lighting shadow passes.
  3. Monitoring performance metrics when modifying this value, as it can affect rendering efficiency.

Regarding the associated variable CVarLumenDirectLightingBatchShadows:

The purpose of CVarLumenDirectLightingBatchShadows is to provide a programmatic interface for the r.LumenScene.DirectLighting.BatchShadows setting. It allows C++ code to directly access and modify the batching behavior of Lumen light shadow passes.

This variable is used within the Renderer module, specifically in the LumenSceneDirectLighting class. It’s accessed in the BeginGatherLumenLights function to determine whether batched shadows should be used for Lumen direct lighting calculations.

The value of CVarLumenDirectLightingBatchShadows is set through the TAutoConsoleVariable template, which ties it to the r.LumenScene.DirectLighting.BatchShadows console variable.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread. This is important for maintaining thread safety in the rendering pipeline.

Best practices for using CVarLumenDirectLightingBatchShadows include:

  1. Accessing its value using the GetValueOnAnyThread() method when determining whether to use batched shadows.
  2. Avoiding frequent changes to this variable during runtime, as it may impact rendering consistency.
  3. Using this variable in conjunction with other Lumen-related settings for comprehensive debugging and optimization of the direct lighting system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:80

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenDirectLightingBatchShadows(
	TEXT("r.LumenScene.DirectLighting.BatchShadows"),
	1,
	TEXT("Whether to enable batching lumen light shadow passes. This cvar mainly exists for debugging."),
	ECVF_RenderThreadSafe);

float LumenSceneDirectLighting::GetMeshSDFShadowRayBias()
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:79

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenDirectLightingBatchShadows(
	TEXT("r.LumenScene.DirectLighting.BatchShadows"),
	1,
	TEXT("Whether to enable batching lumen light shadow passes. This cvar mainly exists for debugging."),
	ECVF_RenderThreadSafe);

float LumenSceneDirectLighting::GetMeshSDFShadowRayBias()

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenSceneDirectLighting.cpp:1681

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginGatherLumenLights
lambda-function

Source code excerpt:


		const bool bUseHardwareRayTracing = Lumen::UseHardwareRayTracedDirectLighting(ViewFamily);
		const bool bUseBatchedShadows = CVarLumenDirectLightingBatchShadows.GetValueOnAnyThread() != 0;
		constexpr int32 NumLightTypes = (int32)ELumenLightType::MAX;
		int32 BatchedLightCounts[NumLightTypes] = {};

		for (auto LightIt = Scene->Lights.CreateConstIterator(); LightIt; ++LightIt)
		{
			const FLightSceneInfoCompact& LightSceneInfoCompact = *LightIt;