r.Lumen.DiffuseIndirect.CullGridPixelSize

r.Lumen.DiffuseIndirect.CullGridPixelSize

#Overview

name: r.Lumen.DiffuseIndirect.CullGridPixelSize

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

• type: Var
• help: Size of a cell in the card grid, in pixels.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.DiffuseIndirect.CullGridPixelSize is to control the size of cells in the card grid used for Lumen’s diffuse indirect lighting calculations. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for the diffuse indirect lighting component.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s referenced in the LumenDiffuseIndirect.cpp file, which is part of the renderer’s implementation of Lumen’s diffuse indirect lighting.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files.

The variable interacts directly with GCardFroxelGridPixelSize, which is the internal representation of this setting. They share the same value, with GCardFroxelGridPixelSize being used in the actual rendering calculations.

Developers should be aware that this variable affects the performance and quality trade-off of Lumen’s diffuse indirect lighting. A larger pixel size will result in a coarser grid, which may be faster to compute but could lead to less accurate lighting. Conversely, a smaller pixel size will provide more detailed lighting at the cost of increased computation time.

Best practices when using this variable include:

1. Adjusting it based on the scene complexity and desired performance targets.
2. Testing different values to find the optimal balance between quality and performance for your specific project.
3. Considering its impact on different hardware configurations, as it may affect performance differently on various GPUs.

Regarding the associated variable GCardFroxelGridPixelSize:

The purpose of GCardFroxelGridPixelSize is to store the actual value used in the rendering calculations for the card grid cell size. It’s an internal representation of the r.Lumen.DiffuseIndirect.CullGridPixelSize console variable.

This variable is used directly in the Lumen diffuse indirect lighting calculations, specifically in the card tracing and culling processes. It’s referenced in the CullForCardTracing function, where it’s used to determine the size of the card grid and to set up parameters for mesh SDF (Signed Distance Field) culling.

The value of GCardFroxelGridPixelSize is set by the r.Lumen.DiffuseIndirect.CullGridPixelSize console variable. Any changes to the console variable will directly affect this internal variable.

GCardFroxelGridPixelSize interacts with various other variables and calculations in the Lumen system, including the card grid size calculations and mesh SDF parameters.

Developers should be aware that modifying GCardFroxelGridPixelSize directly is not recommended. Instead, they should use the r.Lumen.DiffuseIndirect.CullGridPixelSize console variable to adjust this setting.

Best practices for GCardFroxelGridPixelSize include:

1. Treating it as a read-only variable in custom code.
2. Using it consistently with other Lumen parameters when extending or modifying the Lumen system.
3. Being aware of its performance implications when used in rendering calculations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:120

Scope: file

Source code excerpt:

int32 GCardFroxelGridPixelSize = 64;
FAutoConsoleVariableRef CVarLumenDiffuseFroxelGridPixelSize(
	TEXT("r.Lumen.DiffuseIndirect.CullGridPixelSize"),
	GCardFroxelGridPixelSize,
	TEXT("Size of a cell in the card grid, in pixels."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionLogZScale = .01f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:118

Scope: file

Source code excerpt:

);

int32 GCardFroxelGridPixelSize = 64;
FAutoConsoleVariableRef CVarLumenDiffuseFroxelGridPixelSize(
	TEXT("r.Lumen.DiffuseIndirect.CullGridPixelSize"),
	GCardFroxelGridPixelSize,
	TEXT("Size of a cell in the card grid, in pixels."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionLogZScale = .01f;
FAutoConsoleVariableRef CCardGridDistributionLogZScale(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:365

Scope (from outer to inner):

file
function     void CullForCardTracing

Source code excerpt:

	GetCardGridZParams(View.NearClippingDistance, IndirectTracingParameters.CardTraceEndDistanceFromCamera, ZParams, CardGridSizeZ);

	MeshSDFGridParameters.CardGridPixelSizeShift = FMath::FloorLog2(GCardFroxelGridPixelSize);
	MeshSDFGridParameters.CardGridZParams = (FVector3f)ZParams; // LWC_TODO: Precision Loss

	const FIntPoint CardGridSizeXY = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), GCardFroxelGridPixelSize);
	const FIntVector CullGridSize(CardGridSizeXY.X, CardGridSizeXY.Y, CardGridSizeZ);
	MeshSDFGridParameters.CullGridSize = CullGridSize;

	CullMeshObjectsToViewGrid(
		View,
		Scene,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:378

Scope (from outer to inner):

file
function     void CullForCardTracing

Source code excerpt:

		IndirectTracingParameters.MaxMeshSDFTraceDistance,
		IndirectTracingParameters.CardTraceEndDistanceFromCamera,
		GCardFroxelGridPixelSize,
		CardGridSizeZ,
		ZParams,
		GraphBuilder,
		MeshSDFGridParameters,
		ComputePassFlags);
}