r.LumenScene.DirectLighting.UpdateFactor

r.LumenScene.DirectLighting.UpdateFactor

#Overview

name: r.LumenScene.DirectLighting.UpdateFactor

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.UpdateFactor is to control the rate at which direct lighting is updated in the Lumen global illumination system within Unreal Engine 5’s rendering pipeline. This setting variable is specifically used for managing the performance and quality trade-off in the Lumen Scene’s direct lighting calculations.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine 5’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenSceneLighting.cpp file, which is part of the Renderer’s private implementation for Lumen.

The value of this variable is set through the Unreal Engine’s console variable system. It’s initialized with a default value of 32 and can be modified at runtime using console commands or through configuration files.

The r.LumenScene.DirectLighting.UpdateFactor interacts directly with the GLumenDirectLightingUpdateFactor variable. They share the same value, with GLumenDirectLightingUpdateFactor being the actual integer variable used in the C++ code.

Developers must be aware that this variable affects the performance-quality balance of Lumen’s direct lighting calculations. A lower value will result in more frequent updates to direct lighting, potentially improving quality at the cost of performance, while a higher value will reduce the update frequency, possibly improving performance at the cost of lighting accuracy.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of the scene and target hardware.
  2. Testing different values to find the optimal balance between performance and visual quality.
  3. Considering it in conjunction with other Lumen settings for holistic optimization.

Regarding the associated variable GLumenDirectLightingUpdateFactor:

The purpose of GLumenDirectLightingUpdateFactor is to serve as the actual integer value used in the C++ code for controlling the direct lighting update rate in Lumen.

This variable is used directly in the Lumen scene lighting system, specifically in the BuildCardUpdateContext function within the Lumen namespace.

The value of GLumenDirectLightingUpdateFactor is set by the r.LumenScene.DirectLighting.UpdateFactor console variable.

It interacts with the LumenSceneLightingUpdateSpeed variable in calculations determining the size of the lighting update atlas.

Developers should be aware that modifying GLumenDirectLightingUpdateFactor directly in the code is not recommended, as it’s intended to be controlled via the console variable system.

Best practices for GLumenDirectLightingUpdateFactor include:

  1. Avoiding direct modification in code unless absolutely necessary.
  2. Using the r.LumenScene.DirectLighting.UpdateFactor console variable for adjustments instead.
  3. Considering its impact on both the direct lighting update rate and the size of the lighting update atlas when optimizing Lumen performance.

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

Scope: file

Source code excerpt:

int32 GLumenDirectLightingUpdateFactor = 32;
FAutoConsoleVariableRef CVarLumenSceneDirectLightingUpdateFactor(
	TEXT("r.LumenScene.DirectLighting.UpdateFactor"),
	GLumenDirectLightingUpdateFactor,
	TEXT("Controls for how many texels direct lighting will be updated every frame. Texels = SurfaceCacheTexels / Factor."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenRadiosityUpdateFactor = 64;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenDirectLightingUpdateFactor = 32;
FAutoConsoleVariableRef CVarLumenSceneDirectLightingUpdateFactor(
	TEXT("r.LumenScene.DirectLighting.UpdateFactor"),
	GLumenDirectLightingUpdateFactor,
	TEXT("Controls for how many texels direct lighting will be updated every frame. Texels = SurfaceCacheTexels / Factor."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenRadiosityUpdateFactor = 64;
FAutoConsoleVariableRef CVarLumenSceneRadiosityUpdateFactor(

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

Scope (from outer to inner):

file
function     void Lumen::BuildCardUpdateContext

Source code excerpt:

	const float FirstClipmapWorldExtentRcp = 1.0f / Lumen::GetGlobalDFClipmapExtent(0);

	SetLightingUpdateAtlasSize(LumenSceneData.GetPhysicalAtlasSize(), FMath::RoundToInt(GLumenDirectLightingUpdateFactor / LumenSceneLightingUpdateSpeed), DirectLightingCardUpdateContext);
	SetLightingUpdateAtlasSize(LumenSceneData.GetPhysicalAtlasSize(), FMath::RoundToInt(GLumenRadiosityUpdateFactor / LumenSceneLightingUpdateSpeed), IndirectLightingCardUpdateContext);

	DirectLightingCardUpdateContext.CardPageIndexAllocator = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(uint32), 1), TEXT("Lumen.DirectLightingCardPageIndexAllocator"));
	DirectLightingCardUpdateContext.CardPageIndexData = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateStructuredDesc(sizeof(uint32), FMath::RoundUpToPowerOfTwo(NumCardPages)), TEXT("Lumen.DirectLightingCardPageIndexData"));
	DirectLightingCardUpdateContext.DrawCardPageIndicesIndirectArgs = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateIndirectDesc<FRHIDrawIndirectParameters>(1), TEXT("Lumen.DirectLighting.DrawCardPageIndicesIndirectArgs"));
	DirectLightingCardUpdateContext.DispatchCardPageIndicesIndirectArgs = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateIndirectDesc<FRHIDispatchIndirectParameters>(FLumenCardUpdateContext::MAX), TEXT("Lumen.DirectLighting.DispatchCardPageIndicesIndirectArgs"));