r.LumenScene.DirectLighting

r.LumenScene.DirectLighting

#Overview

name: r.LumenScene.DirectLighting

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.DirectLighting is to control whether direct lighting is computed for the Lumen surface cache in Unreal Engine 5’s rendering system. This setting variable is primarily used in the Lumen scene rendering subsystem, which is part of UE5’s global illumination solution.

This setting variable is relied upon by the Lumen rendering module, specifically in the direct lighting calculations for the Lumen scene. It’s used in the file LumenSceneDirectLighting.cpp, which is part of the Renderer module.

The value of this variable is set using a console variable (CVarLumenLumenSceneDirectLighting) with a default value of 1 (enabled). It can be changed at runtime through the console or through project settings.

The associated variable CVarLumenLumenSceneDirectLighting directly interacts with r.LumenScene.DirectLighting. They share the same value and purpose.

Developers must be aware that:

  1. This variable significantly affects the visual quality and performance of the Lumen global illumination system.
  2. Disabling this (setting to 0) will skip direct lighting computations for the Lumen surface cache, which could result in less accurate lighting but potentially better performance.
  3. This setting is marked with ECVF_Scalability, indicating it’s intended to be used for adjusting performance vs. quality tradeoffs.

Best practices when using this variable include:

  1. Keep it enabled (set to 1) for the most accurate lighting results in production builds.
  2. Consider disabling it temporarily during development or on lower-end hardware if performance is a concern.
  3. Test your scenes with both enabled and disabled states to understand the visual and performance impact in your specific use case.

Regarding the associated variable CVarLumenLumenSceneDirectLighting: Its purpose is the same as r.LumenScene.DirectLighting - to control direct lighting computation for the Lumen surface cache. It’s used in the same Lumen rendering subsystem and is set in the same file. The value is read on the render thread in multiple locations to determine whether to perform direct lighting calculations or skip them. Developers should treat this variable identically to r.LumenScene.DirectLighting, as they are effectively the same setting exposed through the console variable 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:15

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenLumenSceneDirectLighting(
	TEXT("r.LumenScene.DirectLighting"),
	1,
	TEXT("Whether to compute direct ligshting for surface cache."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GLumenDirectLightingOffscreenShadowingTraceMeshSDFs = 1;
FAutoConsoleVariableRef CVarLumenDirectLightingOffscreenShadowingTraceMeshSDFs(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

using namespace LightFunctionAtlas;

static TAutoConsoleVariable<int32> CVarLumenLumenSceneDirectLighting(
	TEXT("r.LumenScene.DirectLighting"),
	1,
	TEXT("Whether to compute direct ligshting for surface cache."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

int32 GLumenDirectLightingOffscreenShadowingTraceMeshSDFs = 1;

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::BeginGatherLumenLights

Source code excerpt:

	}

	if (!bAnyLumenActive || CVarLumenLumenSceneDirectLighting.GetValueOnRenderThread() == 0)
	{
		return;
	}

	TaskData = Allocator.Create<FLumenDirectLightingTaskData>();

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderDirectLightingForLumenScene

Source code excerpt:

	LLM_SCOPE_BYTAG(Lumen);

	if (CVarLumenLumenSceneDirectLighting.GetValueOnRenderThread() != 0 && CardUpdateContext.MaxUpdateTiles > 0)
	{
		RDG_EVENT_SCOPE(GraphBuilder, "DirectLighting");
		QUICK_SCOPE_CYCLE_COUNTER(RenderDirectLightingForLumenScene);

		check(LightingTaskData);
		LightingTaskData->Task.Wait();

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

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderDirectLightingForLumenScene

Source code excerpt:

			ComputePassFlags);
	}
	else if (CVarLumenLumenSceneDirectLighting.GetValueOnRenderThread() == 0)
	{
		AddClearRenderTargetPass(GraphBuilder, FrameTemporaries.DirectLightingAtlas);
	}
}