r.LumenScene.DirectLighting.MaxLightsPerTile

r.LumenScene.DirectLighting.MaxLightsPerTile

#Overview

name: r.LumenScene.DirectLighting.MaxLightsPerTile

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.MaxLightsPerTile is to control the maximum number of lights that can be processed per tile in Lumen’s direct lighting system. This setting is crucial for the rendering system, specifically for the Lumen global illumination solution in Unreal Engine 5.

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

The value of this variable is set through a console variable (CVarLumenDirectLightingMaxLightsPerTile) with a default value of 8. It can be changed at runtime through console commands or project settings.

The associated variable CVarLumenDirectLightingMaxLightsPerTile interacts directly with r.LumenScene.DirectLighting.MaxLightsPerTile. They essentially represent the same setting, with the CVar providing a programmatic interface to access and modify the value.

Developers must be aware of several important aspects when using this variable:

  1. Valid values are 4, 8, 16, or 32.
  2. Increasing this value will result in higher memory usage.
  3. Higher values will slow down the Lumen surface cache direct lighting pass.
  4. This setting affects performance scalability and is render thread safe.

Best practices when using this variable include:

  1. Start with the default value (8) and adjust only if necessary.
  2. Consider the trade-off between lighting quality and performance when increasing the value.
  3. Test thoroughly on target hardware to ensure acceptable performance.
  4. Use in conjunction with other Lumen settings for optimal results.

Regarding the associated variable CVarLumenDirectLightingMaxLightsPerTile:

The purpose of CVarLumenDirectLightingMaxLightsPerTile is to provide a programmatic interface to control the r.LumenScene.DirectLighting.MaxLightsPerTile setting. It’s used internally by the engine to access and modify the value of the setting.

This variable is part of the Lumen subsystem in the rendering module. It’s defined and used in the LumenSceneDirectLighting.cpp file.

The value of CVarLumenDirectLightingMaxLightsPerTile is set when the console variable is created, with a default value of 8. It can be modified at runtime using console commands.

CVarLumenDirectLightingMaxLightsPerTile directly interacts with r.LumenScene.DirectLighting.MaxLightsPerTile, as they represent the same setting.

Developers should be aware that this variable is used to retrieve the current value of the setting in the render thread (GetValueOnRenderThread()).

Best practices for using CVarLumenDirectLightingMaxLightsPerTile include:

  1. Use GetValueOnRenderThread() when accessing the value in render thread code.
  2. Be cautious when modifying this value, as it directly affects Lumen’s performance and memory usage.
  3. Consider using this variable for dynamic adjustments to the Lumen lighting system based on runtime conditions.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenDirectLightingMaxLightsPerTile(
	TEXT("r.LumenScene.DirectLighting.MaxLightsPerTile"),
	8,
	TEXT("Max number of lights to pick per tile based on their intenstiy and attenuation. Valid values are 4/8/16/32. Increasing this value will cause more memory usage and will slow down Lumen surface cache direct lighting pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GOffscreenShadowingTraceStepFactor = 5;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenDirectLightingMaxLightsPerTile(
	TEXT("r.LumenScene.DirectLighting.MaxLightsPerTile"),
	8,
	TEXT("Max number of lights to pick per tile based on their intenstiy and attenuation. Valid values are 4/8/16/32. Increasing this value will cause more memory usage and will slow down Lumen surface cache direct lighting pass."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     static void CullDirectLightingTiles

Source code excerpt:

	const uint32 MaxLightTiles = CardUpdateContext.MaxUpdateTiles;
	const uint32 NumLightsRoundedUp = FMath::RoundUpToPowerOfTwo(FMath::Max(GatheredLights.Num(), 1)) * Views.Num();
	const uint32 MaxLightsPerTile = FMath::RoundUpToPowerOfTwo(FMath::Clamp(CVarLumenDirectLightingMaxLightsPerTile.GetValueOnRenderThread(), 1, 32));
	const uint32 MaxCulledCardTiles = MaxLightsPerTile * MaxLightTiles;

	Lumen::SpliceCardPagesIntoTiles(GraphBuilder, GlobalShaderMap, CardUpdateContext, LumenCardSceneUniformBuffer, CardTileUpdateCotnext, ComputePassFlags);

	FRDGBufferRef CardTileAllocator = CardTileUpdateCotnext.CardTileAllocator;
	FRDGBufferRef CardTiles = CardTileUpdateCotnext.CardTiles;