r.LightFunctionAtlas.MaxLightCount

r.LightFunctionAtlas.MaxLightCount

#Overview

name: r.LightFunctionAtlas.MaxLightCount

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

• type: Var
• help: Experimental: Clamp the number of lights that can sample light function atlas. -1 means unlimited light count.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LightFunctionAtlas.MaxLightCount is to control the maximum number of lights that can sample the light function atlas in Unreal Engine’s rendering system. This setting is part of the experimental light function atlas feature, which is used to optimize the rendering of light functions.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the light function atlas system. Based on the callsites, it’s clear that this variable is utilized in the LightFunctionAtlas.cpp file, which is part of the rendering subsystem.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of -1, which means there’s no limit on the number of lights that can sample the light function atlas by default.

The associated variable CVarLightFunctionAtlasMaxLightCount directly interacts with r.LightFunctionAtlas.MaxLightCount. They share the same value and purpose, with CVarLightFunctionAtlasMaxLightCount being the actual console variable implementation.

Developers must be aware that this is an experimental feature, as indicated in the description. The variable allows clamping the number of lights that can sample the light function atlas, which can be useful for performance optimization or debugging purposes.

Best practices when using this variable include:

1. Use it cautiously, as it’s marked experimental.
2. Set it to -1 (default) for unlimited light count when not specifically needed.
3. When limiting the light count, choose a value that balances performance gains with visual quality.
4. Monitor performance and visual impact when adjusting this value.
5. Use it in conjunction with other light function atlas settings for optimal results.

Regarding CVarLightFunctionAtlasMaxLightCount:

This is the actual console variable implementation of r.LightFunctionAtlas.MaxLightCount. It’s defined using TAutoConsoleVariable, which allows it to be changed at runtime through console commands or configuration files.

The variable is used in the AllocateAtlasSlots function of the FLightFunctionAtlas class. Here, it’s queried using GetValueOnRenderThread() to determine the maximum number of lights that should be processed for the light function atlas.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag. This means that changes will be applied safely without causing rendering artifacts or crashes.

When working with CVarLightFunctionAtlasMaxLightCount, developers should follow the same best practices as with r.LightFunctionAtlas.MaxLightCount, ensuring that any modifications are made with consideration for both performance and visual quality.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightFunctionAtlas.cpp:70

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLightFunctionAtlasMaxLightCount(
	TEXT("r.LightFunctionAtlas.MaxLightCount"),
	-1,
	TEXT("Experimental: Clamp the number of lights that can sample light function atlas. -1 means unlimited light count."),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightFunctionAtlas.cpp:69

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarLightFunctionAtlasMaxLightCount(
	TEXT("r.LightFunctionAtlas.MaxLightCount"),
	-1,
	TEXT("Experimental: Clamp the number of lights that can sample light function atlas. -1 means unlimited light count."),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightFunctionAtlas.cpp:431

Scope (from outer to inner):

file
namespace    LightFunctionAtlas
function     void FLightFunctionAtlas::AllocateAtlasSlots

Source code excerpt:

	AddLightSlot(nullptr, 0);

	int32 MaxLightCount = CVarLightFunctionAtlasMaxLightCount.GetValueOnRenderThread();
	for (FSortedRegisteredLights& SortedRegisteredLight : SortedRegisteredLights)
	{
		FLightSceneInfo* LightSceneInfo = RegisteredLights[SortedRegisteredLight.RegisteredLightIndex];
		FLightSceneProxy* Proxy = LightSceneInfo->Proxy;

		if (MaxLightCount >= 0 && int32(LocalLightWithLightFunctionCount) >= MaxLightCount)