r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale

r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale

#Overview

name: r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale is to control the scaling factor for the logarithmic Z distribution of the card grid in Lumen’s diffuse indirect lighting system. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically the diffuse indirect lighting component.

Based on the callsites, this setting variable is primarily used in the Renderer module, particularly in the Lumen subsystem. It’s referenced in the LumenDiffuseIndirect.cpp file, which suggests it’s closely tied to the diffuse indirect lighting calculations in Lumen.

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

This variable interacts closely with another variable named GCardGridDistributionLogZScale. They share the same value, which suggests that GCardGridDistributionLogZScale is the internal representation of the console variable r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale.

Developers should be aware that this variable affects the distribution of the card grid along the Z-axis in a logarithmic scale. Changing this value will impact the precision and performance of the diffuse indirect lighting calculations in Lumen. A smaller value will result in a more uniform distribution, while a larger value will concentrate more grid cells closer to the near plane.

Best practices when using this variable include:

  1. Only modify it if you fully understand its impact on the lighting system.
  2. Test thoroughly after making changes, as it can affect both visual quality and performance.
  3. Consider the relationship with other Lumen settings, particularly those related to the card grid and Z distribution.

Regarding the associated variable GCardGridDistributionLogZScale:

The purpose of GCardGridDistributionLogZScale is to store the actual value used in the Lumen diffuse indirect lighting calculations for the logarithmic Z scale of the card grid distribution.

This variable is used directly in the GetCardGridZParams function to calculate the grid size along the Z-axis and the Z parameters for the card grid. It’s multiplied with the difference between the far and near planes to determine the logarithmic distribution of the grid.

The value of GCardGridDistributionLogZScale is set by the console variable system through r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale.

It interacts with other variables in the GetCardGridZParams function, such as GCardGridDistributionLogZOffset and GCardGridDistributionZScale, to determine the final Z parameters for the card grid.

Developers should be aware that modifying GCardGridDistributionLogZScale directly in code is not recommended. Instead, they should use the console variable r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale to ensure consistency across the engine.

Best practices for GCardGridDistributionLogZScale include:

  1. Treat it as a read-only variable in code.
  2. Use the associated console variable for any runtime modifications.
  3. Consider its impact on the entire Lumen diffuse indirect lighting pipeline when making changes.

#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:128

Scope: file

Source code excerpt:

float GCardGridDistributionLogZScale = .01f;
FAutoConsoleVariableRef CCardGridDistributionLogZScale(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale"),
	GCardGridDistributionLogZScale,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionLogZOffset = 1.0f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GCardGridDistributionLogZScale = .01f;
FAutoConsoleVariableRef CCardGridDistributionLogZScale(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionLogZScale"),
	GCardGridDistributionLogZScale,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionLogZOffset = 1.0f;
FAutoConsoleVariableRef CCardGridDistributionLogZOffset(

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

Scope (from outer to inner):

file
function     void GetCardGridZParams

Source code excerpt:

	float NearPlane = FMath::Min(InFarPlane, InNearPlane);
	float FarPlane = FMath::Max(InFarPlane, InNearPlane);
	OutGridSizeZ = FMath::Max(FMath::TruncToInt(FMath::Log2((FarPlane - NearPlane) * GCardGridDistributionLogZScale) * GCardGridDistributionZScale), 0) + 1;
	OutZParams = FVector(GCardGridDistributionLogZScale, GCardGridDistributionLogZOffset, GCardGridDistributionZScale);
}

void CullForCardTracing(
	FRDGBuilder& GraphBuilder,
	const FScene* Scene,
	const FViewInfo& View,