r.AllowClearLightSceneExtentsOnly

r.AllowClearLightSceneExtentsOnly

#Overview

name: r.AllowClearLightSceneExtentsOnly

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

• type: Var
• help: ``

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AllowClearLightSceneExtentsOnly is to control the optimization of light attenuation clearing for local lights in the rendering system. This setting variable is part of Unreal Engine 5’s rendering subsystem.

The Unreal Engine rendering module relies on this setting variable, specifically in the deferred shading scene renderer. It is used within the light rendering process to determine how to clear light attenuation for local lights.

The value of this variable is set as a console variable (CVar) with a default value of 1 (enabled). It is defined in the LightRendering.cpp file of the Renderer module.

This variable interacts with the light rendering process, particularly affecting how the renderer clears light attenuation for local lights. It is used in conjunction with other lighting-related variables and systems within the renderer.

Developers must be aware that this variable affects rendering performance and visual quality. When enabled (set to 1), it allows for a more optimized clearing of light attenuation by using a quad covering only the light’s extents, rather than clearing the entire screen.

Best practices when using this variable include:

1. Keeping it enabled (default value of 1) for better performance in most scenarios.
2. Testing the impact on performance and visual quality in specific use cases, especially for scenes with many local lights.
3. Considering disabling it if any visual artifacts are observed related to light attenuation.

Regarding the associated variable CVarAllowClearLightSceneExtentsOnly:

This is the actual console variable that stores the value of r.AllowClearLightSceneExtentsOnly. It is defined as a TAutoConsoleVariable in the same file (LightRendering.cpp).

The purpose of CVarAllowClearLightSceneExtentsOnly is to provide a runtime-accessible interface for the r.AllowClearLightSceneExtentsOnly setting. It allows the value to be changed during runtime through the console or configuration files.

This variable is used directly in the rendering code to determine whether to use the optimized clearing method for local lights. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

Developers should be aware that changes to this CVar will take effect immediately on the render thread. They should use this variable when they need to programmatically check or modify the r.AllowClearLightSceneExtentsOnly setting during runtime.

Best practices for using CVarAllowClearLightSceneExtentsOnly include:

1. Using it for debug purposes or performance testing.
2. Ensuring any modifications are done in a thread-safe manner, preferably using engine-provided methods for changing CVars.
3. Considering the impact on performance and visual quality when modifying this value during runtime.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:105

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAllowClearLightSceneExtentsOnly(
	TEXT("r.AllowClearLightSceneExtentsOnly"), 1,
	TEXT(""),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRayTracingShadowsDirectionalLight(
	TEXT("r.RayTracing.Shadows.Lights.Directional"),
	1,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:104

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarAllowClearLightSceneExtentsOnly(
	TEXT("r.AllowClearLightSceneExtentsOnly"), 1,
	TEXT(""),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarRayTracingShadowsDirectionalLight(
	TEXT("r.RayTracing.Shadows.Lights.Directional"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:1984

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderLights
lambda-function

Source code excerpt:

						{
							// Clear light attenuation for local lights with a quad covering their extents
							const bool bClearLightScreenExtentsOnly = CVarAllowClearLightSceneExtentsOnly.GetValueOnRenderThread() && SortedLightInfo.SortKey.Fields.LightType != LightType_Directional;

							if (bClearLightScreenExtentsOnly)
							{
								FRenderTargetParameters* PassParameters = GraphBuilder.AllocParameters<FRenderTargetParameters>();
								PassParameters->RenderTargets[0] = FRenderTargetBinding(InScreenShadowMaskTexture, ERenderTargetLoadAction::ENoAction);