r.Forward.LightGridSizeZ

r.Forward.LightGridSizeZ

#Overview

name: r.Forward.LightGridSizeZ

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

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Forward.LightGridSizeZ is to control the number of Z slices in the light grid used for forward rendering in Unreal Engine 5. This setting variable is primarily related to the rendering system, specifically the forward rendering pipeline.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by the references in the LightGridInjection.cpp and VolumetricFog.cpp files.

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

This variable interacts closely with GLightGridSizeZ, which is the associated C++ variable that stores the actual value. They share the same value, with r.Forward.LightGridSizeZ being the console-accessible name and GLightGridSizeZ being the internal variable used in the code.

Developers should be aware that changing this variable affects the granularity of the light grid in the Z-axis. A higher value will provide more precise lighting calculations but may impact performance. The default value is set to 32, which is likely a balance between quality and performance.

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 visual quality and performance.
  3. Considering the relationship between this variable and other light grid settings (e.g., r.Forward.LightGridSizeXY).

Regarding the associated variable GLightGridSizeZ:

The purpose of GLightGridSizeZ is to store the number of Z slices in the light grid within the C++ code. It is used directly in various calculations related to light grid setup and rendering.

This variable is used in multiple places within the Renderer module, particularly in light grid calculations, forward lighting, and volumetric fog rendering.

The value of GLightGridSizeZ is set by the console variable r.Forward.LightGridSizeZ, allowing for runtime configuration.

GLightGridSizeZ interacts with other variables and calculations in the rendering pipeline, such as light culling, grid cell count, and Z-axis parameters for the light grid.

Developers should be aware that this variable directly affects memory usage and performance of the forward rendering pipeline. Changes to this value will impact the precision of light calculations along the Z-axis.

Best practices for using GLightGridSizeZ include:

  1. Ensuring that any modifications to r.Forward.LightGridSizeZ are reflected in the code that uses GLightGridSizeZ.
  2. Considering the impact on performance and memory usage when adjusting this value.
  3. Balancing the Z resolution with the XY resolution of the light grid for optimal results.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/Android/AndroidEngine.ini:83, section: [ConsoleVariables]

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GLightGridSizeZ = 32;
FAutoConsoleVariableRef CVarLightGridSizeZ(
	TEXT("r.Forward.LightGridSizeZ"),
	GLightGridSizeZ,
	TEXT("Number of Z slices in the light grid."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GForwardLightGridDebug = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLightGridSizeZ = 32;
FAutoConsoleVariableRef CVarLightGridSizeZ(
	TEXT("r.Forward.LightGridSizeZ"),
	GLightGridSizeZ,
	TEXT("Number of Z slices in the light grid."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GForwardLightGridDebug = 0;
FAutoConsoleVariableRef CVarLightGridDebug(

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

Scope (from outer to inner):

file
function     FVector GetLightGridZParams

Source code excerpt:

	double F = FarPlane;

	double O = (F - N * exp2((GLightGridSizeZ - 1) / S)) / (F - N);
	double B = (1 - O) / N;

	return FVector(B, O, S);
}

static uint32 PackRG16(float In0, float In1)

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

Scope: file

Source code excerpt:

		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;

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

Scope: file

Source code excerpt:

		const FIntPoint MaxLightGridSizeXY = FIntPoint::DivideAndRoundUp(View.GetSceneTexturesConfig().Extent, GLightGridPixelSize);

		const int32 MaxNumCells = MaxLightGridSizeXY.X * MaxLightGridSizeXY.Y * GLightGridSizeZ * NumCulledGridPrimitiveTypes;

		const FIntVector NumGroups = FIntVector::DivideAndRoundUp(FIntVector(LightGridSizeXY.X, LightGridSizeXY.Y, GLightGridSizeZ), LightGridInjectionGroupSize);

		{
			RDG_EVENT_SCOPE(GraphBuilder, "CullLights %ux%ux%u NumLights %u NumCaptures %u",
				ForwardLightData->CulledGridSize.X,
				ForwardLightData->CulledGridSize.Y,
				ForwardLightData->CulledGridSize.Z,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VolumetricFog.cpp:1143

Scope (from outer to inner):

file
function     BEGIN_SHADER_PARAMETER_STRUCT

Source code excerpt:

	// B = (1 - O) / N

	// f(F) = GLightGridSizeZ - 1 = log2(F*B + O) * S
	// exp2((GLightGridSizeZ - 1) / S) = F*B + O
	// exp2((GLightGridSizeZ - 1) / S) = F * (1 - O) / N + O
	// exp2((GLightGridSizeZ - 1) / S) = F / N - F / N * O + O
	// exp2((GLightGridSizeZ - 1) / S) = F / N + (-F / N + 1) * O
	// O = (exp2((GLightGridSizeZ - 1) / S) - F / N) / (-F / N + 1)

	return FVector(B, O, S);
}

static FIntVector GetVolumetricFogGridSize(const FIntPoint& TargetResolution, int32& OutVolumetricFogGridPixelSize)
{
	extern int32 GLightGridSizeZ;
	FIntPoint VolumetricFogGridSizeXY;
	int32 VolumetricFogGridPixelSize = GetVolumetricFogGridPixelSize();
	VolumetricFogGridSizeXY = FIntPoint::DivideAndRoundUp(TargetResolution, VolumetricFogGridPixelSize);
	if(VolumetricFogGridSizeXY.X > GMaxVolumeTextureDimensions || VolumetricFogGridSizeXY.Y > GMaxVolumeTextureDimensions) //clamp to max volume texture dimensions. only happens for extreme resolutions (~8x2k)
	{
		float PixelSizeX = (float)TargetResolution.X / GMaxVolumeTextureDimensions;