r.Forward.LightGridPixelSize

r.Forward.LightGridPixelSize

#Overview

name: r.Forward.LightGridPixelSize

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.Forward.LightGridPixelSize is to control the size of cells in the light grid used for forward rendering in Unreal Engine 5. This setting is primarily used in the rendering system, specifically for managing light culling and grid-based lighting calculations.

This setting variable is relied upon by the Renderer module of Unreal Engine 5, particularly in the forward rendering pipeline. It’s used in both LightGridInjection.cpp and MobileLocalLightsBuffer.cpp, indicating its relevance to both desktop and mobile rendering paths.

The value of this variable is set through the console variable system. It’s initialized with a default value of 64 pixels and can be modified at runtime using console commands or through project settings.

The r.Forward.LightGridPixelSize variable directly interacts with GLightGridPixelSize. They share the same value, with GLightGridPixelSize being the internal C++ variable that stores the actual value used in calculations.

Developers must be aware that changing this value affects the granularity of light culling. A smaller value will result in more precise light culling but at the cost of increased memory usage and potentially lower performance. Conversely, a larger value will be more performant but may result in over-estimation of lighting in some areas.

Best practices when using this variable include:

  1. Balancing between performance and visual quality.
  2. Testing different values to find the optimal setting for your specific scene and target hardware.
  3. Considering scaling this value based on the target platform or quality settings.

Regarding the associated variable GLightGridPixelSize:

The purpose of GLightGridPixelSize is to serve as the internal representation of the light grid cell size. It’s used directly in calculations throughout the rendering code.

This variable is used in the Renderer module, specifically in light grid calculations and forward rendering processes.

Its value is set by the r.Forward.LightGridPixelSize console variable, ensuring that changes to the console variable are reflected in the internal workings of the engine.

GLightGridPixelSize interacts directly with r.Forward.LightGridPixelSize and is used in calculations involving light grid dimensions and culling.

Developers should be aware that this variable is used in performance-critical rendering code, so any modifications to its value (via r.Forward.LightGridPixelSize) can have significant impacts on rendering performance and quality.

Best practices include avoiding direct manipulation of GLightGridPixelSize and instead using the r.Forward.LightGridPixelSize console variable to make changes, ensuring that all parts of the engine remain in sync.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GLightGridPixelSize = 64;
FAutoConsoleVariableRef CVarLightGridPixelSize(
	TEXT("r.Forward.LightGridPixelSize"),
	GLightGridPixelSize,
	TEXT("Size of a cell in the light grid, in pixels."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLightGridSizeZ = 32;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MobileLocalLightsBuffer.cpp:210

Scope: file

Source code excerpt:

	QUICK_SCOPE_CYCLE_COUNTER(STAT_RenderMobileLocalLightsBuffer);

	static const auto LightGridPixelSizeCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Forward.LightGridPixelSize"));
	check(LightGridPixelSizeCVar != nullptr);
	int32 LightGridPixelSize = LightGridPixelSizeCVar->GetInt();

	for (int32 ViewIndex = 0; ViewIndex < Views.Num(); ViewIndex++)
	{
		FViewInfo& View = Views[ViewIndex];

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "ManyLights/ManyLights.h"

int32 GLightGridPixelSize = 64;
FAutoConsoleVariableRef CVarLightGridPixelSize(
	TEXT("r.Forward.LightGridPixelSize"),
	GLightGridPixelSize,
	TEXT("Size of a cell in the light grid, in pixels."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLightGridSizeZ = 32;
FAutoConsoleVariableRef CVarLightGridSizeZ(

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

Scope: file

Source code excerpt:

		View.ForwardLightingResources.LocalLightVisibleLightInfosIndex = LocalLightVisibleLightInfosIndex;

		const FIntPoint LightGridSizeXY = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), GLightGridPixelSize);
		ForwardLightData->ForwardLocalLightBuffer = GraphBuilder.CreateSRV(FRDGBufferSRVDesc(ForwardLocalLightBuffer));
		ForwardLightData->NumLocalLights = NumLocalLightsFinal;
		ForwardLightData->NumReflectionCaptures = View.NumBoxReflectionCaptures + View.NumSphereReflectionCaptures;
		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;

		// Clamp far plane to something reasonable

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

Scope: file

Source code excerpt:

		FForwardLightData* ForwardLightData = ForwardLightDataPerView[ViewIndex];

		const FIntPoint LightGridSizeXY = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), GLightGridPixelSize);

#endif // ENABLE_LIGHT_CULLING_VIEW_SPACE_BUILD_DATA

		// Allocate buffers using the scene render targets size so we won't reallocate every frame with dynamic resolution
		const FIntPoint MaxLightGridSizeXY = FIntPoint::DivideAndRoundUp(View.GetSceneTexturesConfig().Extent, GLightGridPixelSize);