r.LightCulling.Quality

r.LightCulling.Quality

#Overview

name: r.LightCulling.Quality

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

• type: Var
• help: Whether to run compute light culling pass.\n 0: off \n 1: on (default)\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LightCulling.Quality is to control whether the compute light culling pass is enabled or disabled in Unreal Engine’s rendering system. This setting variable is used to optimize the rendering performance by determining if the engine should perform light culling computations.

The Unreal Engine’s rendering subsystem relies on this setting variable, particularly in the light grid injection module. It’s primarily used in the Renderer module, as evidenced by its location in the LightGridInjection.cpp file.

The value of this variable is set through the console variable system (CVarLightCullingQuality). It’s initialized with a default value of 1, which means the light culling pass is enabled by default.

The associated variable GLightCullingQuality directly interacts with r.LightCulling.Quality. They share the same value, and GLightCullingQuality is used in the actual code logic to determine if light culling should be performed.

Developers must be aware that this variable has a significant impact on rendering performance and visual quality. Setting it to 0 turns off the compute light culling pass, which might improve performance but could potentially reduce visual quality or accuracy of lighting calculations.

Best practices when using this variable include:

1. Keeping it enabled (value 1) for most scenarios to benefit from optimized light culling.
2. Only disabling it (value 0) if there’s a specific performance issue that needs to be addressed and the visual impact is acceptable.
3. Profiling the application with both settings to understand the performance implications in your specific use case.

Regarding the associated variable GLightCullingQuality:

• Its purpose is to provide a C++ accessible version of the r.LightCulling.Quality setting.
• It’s used directly in the rendering code to determine whether to perform light culling.
• The value is set by the console variable system, mirroring r.LightCulling.Quality.
• It interacts with various rendering systems, including forward shading, ray tracing, clustered deferred shading, and Lumen.
• Developers should be aware that changing GLightCullingQuality will have the same effect as changing r.LightCulling.Quality.
• Best practice is to use the console variable (r.LightCulling.Quality) to change this setting rather than modifying GLightCullingQuality directly in code, unless there’s a specific need for programmatic control.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

int32 GLightCullingQuality = 1;
FAutoConsoleVariableRef CVarLightCullingQuality(
	TEXT("r.LightCulling.Quality"),
	GLightCullingQuality,
	TEXT("Whether to run compute light culling pass.\n")
	TEXT(" 0: off \n")
	TEXT(" 1: on (default)\n"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLightCullingQuality = 1;
FAutoConsoleVariableRef CVarLightCullingQuality(
	TEXT("r.LightCulling.Quality"),
	GLightCullingQuality,
	TEXT("Whether to run compute light culling pass.\n")
	TEXT(" 0: off \n")
	TEXT(" 1: on (default)\n"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     FComputeLightGridOutput FDeferredShadingSceneRenderer::GatherLightsAndComputeLightGrid

Source code excerpt:

	}
	
	const bool bCullLightsToGrid = GLightCullingQuality 
		&& (IsForwardShadingEnabled(ShaderPlatform) || bAnyViewUsesForwardLighting || IsRayTracingEnabled() || ShouldUseClusteredDeferredShading() ||
			bAnyViewUsesLumen || ViewFamily.EngineShowFlags.VisualizeMeshDistanceFields || VirtualShadowMapArray.IsEnabled() || ManyLights::IsEnabled());

	// Store this flag if lights are injected in the grids, check with 'AreLightsInLightGrid()'
	bAreLightsInLightGrid = bCullLightsToGrid;