r.Forward.LightLinkedListCulling

r.Forward.LightLinkedListCulling

#Overview

name: r.Forward.LightLinkedListCulling

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Forward.LightLinkedListCulling is to control the method of storing culled lights in the forward rendering pipeline. It uses a reverse linked list approach to store culled lights, which removes the fixed limit on how many lights can affect a cell and replaces it with a global limit instead.

This setting variable is primarily used in the rendering system, specifically in the forward rendering pipeline for light culling and grid injection. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime through console commands or configuration files.

The associated variable GLightLinkedListCulling interacts directly with r.Forward.LightLinkedListCulling. They share the same value, with GLightLinkedListCulling being the actual integer variable used in the C++ code.

Developers should be aware that:

  1. This variable affects the light culling process in forward rendering.
  2. It can impact performance and memory usage, as it changes how lights are stored and processed.
  3. The default value is 1, enabling the linked list culling method.

Best practices when using this variable include:

  1. Test performance with and without linked list culling enabled to determine the best setting for your specific use case.
  2. Consider the trade-off between flexibility in the number of lights per cell and potential performance impacts.
  3. Be cautious when modifying this setting in shipping builds, as it can affect both performance and visual quality.

Regarding the associated variable GLightLinkedListCulling:

The purpose of GLightLinkedListCulling is to serve as the actual integer storage for the r.Forward.LightLinkedListCulling console variable. It is used directly in the C++ code to control the behavior of the light culling system.

This variable is used in the Renderer module, specifically in the light grid injection process for forward rendering.

The value of GLightLinkedListCulling is set by the console variable system when r.Forward.LightLinkedListCulling is modified.

GLightLinkedListCulling interacts with various parts of the light culling system, including:

  1. Determining the maximum number of culled lights per cell.
  2. Controlling the permutation of the LightGridInjectionCS compute shader.
  3. Deciding whether to use linked list culling in the light grid injection process.

Developers should be aware that modifying GLightLinkedListCulling directly in code is not recommended, as it may be overwritten by the console variable system. Instead, they should use the r.Forward.LightLinkedListCulling console variable to control this setting.

Best practices for using GLightLinkedListCulling include:

  1. Treat it as a read-only variable in most cases, relying on the console variable system for modifications.
  2. Use it for conditional logic in rendering code where the linked list culling method needs to be considered.
  3. Be aware of its impact on shader permutations and adjust related code accordingly when making changes to the light culling system.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:316, section: [IOS DeviceProfile]

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:807, section: [Android DeviceProfile]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:72

Scope: file

Source code excerpt:

int32 GLightLinkedListCulling = 1;
FAutoConsoleVariableRef CVarLightLinkedListCulling(
	TEXT("r.Forward.LightLinkedListCulling"),
	GLightLinkedListCulling,
	TEXT("Uses a reverse linked list to store culled lights, removing the fixed limit on how many lights can affect a cell - it becomes a global limit instead."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLightCullingQuality = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLightLinkedListCulling = 1;
FAutoConsoleVariableRef CVarLightLinkedListCulling(
	TEXT("r.Forward.LightLinkedListCulling"),
	GLightLinkedListCulling,
	TEXT("Uses a reverse linked list to store culled lights, removing the fixed limit on how many lights can affect a cell - it becomes a global limit instead."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLightCullingQuality = 1;
FAutoConsoleVariableRef CVarLightCullingQuality(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:756

Scope: file

Source code excerpt:

		ForwardLightData->NumGridCells = LightGridSizeXY.X * LightGridSizeXY.Y * GLightGridSizeZ;
		ForwardLightData->CulledGridSize = FIntVector(LightGridSizeXY.X, LightGridSizeXY.Y, GLightGridSizeZ);
		ForwardLightData->MaxCulledLightsPerCell = GLightLinkedListCulling ? NumLocalLightsFinal: GMaxCulledLightsPerCell;
		ForwardLightData->LightGridPixelSizeShift = FMath::FloorLog2(GLightGridPixelSize);
		ForwardLightData->SimpleLightsEndIndex = SimpleLightsEnd;
		ForwardLightData->ClusteredDeferredSupportedEndIndex = ClusteredSupportedEnd;
		ForwardLightData->ManyLightsSupportedStartIndex = FMath::Min<int32>(ManyLightsSupportedStart, NumLocalLightsFinal);
		ForwardLightData->DirectLightingShowFlag = ViewFamily.EngineShowFlags.DirectLighting ? 1 : 0;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightGridInjection.cpp:885

Scope: file

Source code excerpt:


			FLightGridInjectionCS::FPermutationDomain PermutationVector;
			PermutationVector.Set<FLightGridInjectionCS::FUseLinkedListDim>(GLightLinkedListCulling != 0);
			TShaderMapRef<FLightGridInjectionCS> ComputeShader(View.ShaderMap, PermutationVector);

			if (GLightLinkedListCulling != 0)
			{
				AddClearUAVPass(GraphBuilder, PassParameters->RWStartOffsetGrid, 0xFFFFFFFF);
				AddClearUAVPass(GraphBuilder, PassParameters->RWNextCulledLightLink, 0);
				AddClearUAVPass(GraphBuilder, NextCulledLightDataUAV, 0);
				AddClearUAVPass(GraphBuilder, NumCulledLightsGridUAV, 0);
				FComputeShaderUtils::AddPass(GraphBuilder, RDG_EVENT_NAME("LightGridInject:LinkedList"), ComputeShader, PassParameters, NumGroups);