r.Lumen.DiffuseIndirect.CullGridDistributionZScale

r.Lumen.DiffuseIndirect.CullGridDistributionZScale

#Overview

name: r.Lumen.DiffuseIndirect.CullGridDistributionZScale

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.CullGridDistributionZScale is to control the Z-axis scaling of the card grid distribution in Lumen’s diffuse indirect lighting system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the diffuse indirect lighting component.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized 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 console variable system in Unreal Engine. It’s initialized with a default value of 4.0f and can be modified at runtime using console commands or through project settings.

The associated variable GCardGridDistributionZScale interacts directly with r.Lumen.DiffuseIndirect.CullGridDistributionZScale. They share the same value, with GCardGridDistributionZScale being the actual float variable used in the calculations, while r.Lumen.DiffuseIndirect.CullGridDistributionZScale is the console variable that allows for runtime modification.

Developers should be aware that this variable affects the precision and performance of the Lumen diffuse indirect lighting system. Changing this value will impact how the Z-axis of the card grid is distributed, which can affect the quality and performance of the global illumination.

Best practices when using this variable include:

  1. Carefully adjusting the value to balance between quality and performance.
  2. Testing changes thoroughly in various lighting scenarios to ensure desired results.
  3. Considering the impact on different hardware configurations, as this setting can affect performance.

Regarding the associated variable GCardGridDistributionZScale:

The purpose of GCardGridDistributionZScale is to store the actual float value used in calculations for the Z-axis scaling of the card grid distribution in Lumen’s diffuse indirect lighting system.

This variable is used directly in the GetCardGridZParams function within the Lumen diffuse indirect lighting implementation. It affects the calculation of the grid size in the Z-axis and the Z parameters used in card tracing.

The value of GCardGridDistributionZScale is set by the console variable r.Lumen.DiffuseIndirect.CullGridDistributionZScale, allowing for runtime modification.

Developers should be aware that modifying GCardGridDistributionZScale directly in code would not be reflected in the console variable, potentially leading to inconsistencies. Always use the console variable for modifications to ensure consistency.

Best practices for GCardGridDistributionZScale include:

  1. Avoiding direct modification in code; instead, use the console variable for changes.
  2. Considering the impact of this value on the overall Lumen lighting calculations when making adjustments.
  3. Documenting any non-default values used in production to aid in troubleshooting and optimization.

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

Scope: file

Source code excerpt:

float GCardGridDistributionZScale = 4.0f;
FAutoConsoleVariableRef CVarCardGridDistributionZScale(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionZScale"),
	GCardGridDistributionZScale,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenDiffuseIndirectAsyncCompute(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GCardGridDistributionZScale = 4.0f;
FAutoConsoleVariableRef CVarCardGridDistributionZScale(
	TEXT("r.Lumen.DiffuseIndirect.CullGridDistributionZScale"),
	GCardGridDistributionZScale,
	TEXT(""),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenDiffuseIndirectAsyncCompute(
	TEXT("r.Lumen.DiffuseIndirect.AsyncCompute"),

#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,