r.LightCulling.MaxDistanceOverrideKilometers

r.LightCulling.MaxDistanceOverrideKilometers

#Overview

name: r.LightCulling.MaxDistanceOverrideKilometers

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

• type: Var
• help: Used to override the maximum far distance at which we can store data in the light grid.\n If this is increase, you might want to update r.Forward.LightGridSizeZ to a reasonable value according to your use case light count and distribution. <=0: off \n >0: the far distance in kilometers.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LightCulling.MaxDistanceOverrideKilometers is to override the maximum far distance at which data can be stored in the light grid for light culling in Unreal Engine’s rendering system.

This setting variable is primarily used by the Renderer module of Unreal Engine, specifically in the light culling and light grid injection subsystems. It directly affects how far the engine will consider lights for culling and grid storage.

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.

The associated variable GLightCullingMaxDistanceOverrideKilometers interacts directly with r.LightCulling.MaxDistanceOverrideKilometers. They share the same value, with GLightCullingMaxDistanceOverrideKilometers being the C++ variable that stores the actual value used in the code.

Developers must be aware of several things when using this variable:

1. The value is in kilometers.
2. A value <= 0 turns off the override.
3. Increasing this value may require adjusting r.Forward.LightGridSizeZ for optimal performance.
4. It affects the far plane calculation for light culling, which can impact rendering performance and visual quality.

Best practices when using this variable include:

1. Only override when necessary, as the default behavior is usually sufficient.
2. When increasing the value, consider the impact on performance and adjust related settings like r.Forward.LightGridSizeZ.
3. Use in conjunction with profiling tools to ensure optimal performance.
4. Be cautious of setting extremely large values, as it may lead to precision issues or unnecessary performance overhead.

Regarding the associated variable GLightCullingMaxDistanceOverrideKilometers:

• Its purpose is to store the actual value of the maximum light culling distance override in the C++ code.
• It’s used directly in the light grid injection code to calculate the far plane for light culling.
• The value is set by the console variable system and can be modified at runtime.
• It interacts with other rendering calculations, particularly in determining the LightCullingMaxDistance.
• Developers should be aware that this variable is used in centimeter calculations (multiplied by 100000 to convert from kilometers).
• Best practices include using this variable for debug purposes or fine-tuning rendering in specific scenarios, but generally relying on the console variable for configuration.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

float GLightCullingMaxDistanceOverrideKilometers = -1.0f;
FAutoConsoleVariableRef CVarLightCullingMaxDistanceOverride(
	TEXT("r.LightCulling.MaxDistanceOverrideKilometers"),
	GLightCullingMaxDistanceOverrideKilometers,
	TEXT("Used to override the maximum far distance at which we can store data in the light grid.\n If this is increase, you might want to update r.Forward.LightGridSizeZ to a reasonable value according to your use case light count and distribution.")
	TEXT(" <=0: off \n")
	TEXT(" >0: the far distance in kilometers.\n"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLightCullingMaxDistanceOverrideKilometers = -1.0f;
FAutoConsoleVariableRef CVarLightCullingMaxDistanceOverride(
	TEXT("r.LightCulling.MaxDistanceOverrideKilometers"),
	GLightCullingMaxDistanceOverrideKilometers,
	TEXT("Used to override the maximum far distance at which we can store data in the light grid.\n If this is increase, you might want to update r.Forward.LightGridSizeZ to a reasonable value according to your use case light count and distribution.")
	TEXT(" <=0: off \n")
	TEXT(" >0: the far distance in kilometers.\n"),
	ECVF_RenderThreadSafe
);

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

Scope: file

Source code excerpt:

		// Clamp far plane to something reasonable
		const float KilometersToCentimeters = 100000.0f;
		const float LightCullingMaxDistance = GLightCullingMaxDistanceOverrideKilometers <= 0.0f ? (float)UE_OLD_HALF_WORLD_MAX / 5.0f : GLightCullingMaxDistanceOverrideKilometers * KilometersToCentimeters;
		float FarPlane = FMath::Min(FMath::Max(FurthestLight, View.FurthestReflectionCaptureDistance), LightCullingMaxDistance);
		FVector ZParams = GetLightGridZParams(View.NearClippingDistance, FarPlane + 10.f);
		ForwardLightData->LightGridZParams = (FVector3f)ZParams;

		const uint64 NumIndexableLights = !bLightGridUses16BitBuffers ? (1llu << (sizeof(FLightIndexType32) * 8llu)) : (1llu << (sizeof(FLightIndexType) * 8llu));