r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset

r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset

#Overview

name: r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset

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.CullGridDistributionLogZOffset is to control the logarithmic Z-offset in the card grid distribution for Lumen’s diffuse indirect lighting system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically affecting the culling process for card tracing in diffuse indirect lighting calculations.

The Lumen subsystem within Unreal Engine’s rendering module relies on this setting variable. It’s used in the LumenDiffuseIndirect.cpp file, which is part of the Renderer module.

The value of this variable is set through the Unreal Engine console variable system. It’s declared as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

This variable interacts directly with GCardGridDistributionLogZOffset. They share the same value, with GCardGridDistributionLogZOffset being the actual float variable used in the code, while r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset is the console variable name used to set its value.

Developers must be aware that this variable affects the Z-distribution of the card grid used in Lumen’s diffuse indirect lighting calculations. Changing this value will impact how the engine culls and distributes cards in the Z-axis for lighting calculations, potentially affecting performance and visual quality.

Best practices when using this variable include:

  1. Only adjust it if you fully understand its impact on the Lumen lighting system.
  2. Test thoroughly after making changes, as it can affect both performance and visual quality.
  3. Consider the interaction with other Lumen settings, as they may need to be adjusted in tandem.

Regarding the associated variable GCardGridDistributionLogZOffset:

The purpose of GCardGridDistributionLogZOffset is to store the actual float value used in the Lumen diffuse indirect lighting calculations for the logarithmic Z-offset in the card grid distribution.

This variable is used directly in the GetCardGridZParams function within the LumenDiffuseIndirect.cpp file. It’s part of the calculation that determines the Z parameters for the card grid used in Lumen’s lighting system.

The value of GCardGridDistributionLogZOffset is set through the r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset console variable.

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

Developers should be aware that modifying GCardGridDistributionLogZOffset directly in the code is not recommended. Instead, they should use the console variable r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset to adjust its value.

Best practices for using GCardGridDistributionLogZOffset include:

  1. Treat it as a read-only variable in code, and modify its value only through the console variable system.
  2. Consider its impact on the entire Lumen lighting pipeline when adjusting its value.
  3. Document any non-default values used in production to ensure consistency across different development environments.

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

Scope: file

Source code excerpt:

float GCardGridDistributionLogZOffset = 1.0f;
FAutoConsoleVariableRef CCardGridDistributionLogZOffset(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset"),
	GCardGridDistributionLogZOffset,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionZScale = 4.0f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GCardGridDistributionLogZOffset = 1.0f;
FAutoConsoleVariableRef CCardGridDistributionLogZOffset(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionLogZOffset"),
	GCardGridDistributionLogZOffset,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GCardGridDistributionZScale = 4.0f;
FAutoConsoleVariableRef CVarCardGridDistributionZScale(

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

Scope (from outer to inner):

file
function     void GetCardGridZParams

Source code excerpt:

	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,