r.Shadow.Scene.LightActiveFrameCount

r.Shadow.Scene.LightActiveFrameCount

#Overview

name: r.Shadow.Scene.LightActiveFrameCount

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

• type: Var
• help: Number of frames before a light that has been moving (updated or transform changed) goes to inactive state.\n This determines the number of frames that the MobilityFactor goes to zero over, and thus a higher number spreads invalidations out over a longer time.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Scene.LightActiveFrameCount is to control the number of frames before a moving light transitions to an inactive state in the shadow rendering system. This setting is used to manage the performance and visual quality of dynamic shadows in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the shadow rendering subsystem. It’s referenced in the ShadowScene.cpp file, which is part of the shadow rendering implementation.

The value of this variable is set through a console variable (CVarShadowSceneLightActiveFrameCount) with a default value of 10 frames. It can be adjusted at runtime using console commands or through configuration files.

The associated variable CVarShadowSceneLightActiveFrameCount directly interacts with r.Shadow.Scene.LightActiveFrameCount. They share the same value and purpose.

Developers should be aware that this variable affects the transition time for lights moving from an active to an inactive state. A higher value will result in a more gradual transition, spreading shadow invalidations over a longer period, which can help reduce sudden visual changes but may impact performance.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of the scene and target hardware capabilities.
2. Testing different values to find the optimal balance between visual quality and performance.
3. Considering the impact on both stationary and fully dynamic lights in the scene.
4. Monitoring performance metrics when modifying this value, especially in scenes with many dynamic lights.

Regarding the associated variable CVarShadowSceneLightActiveFrameCount:

• It’s an integer console variable that directly controls the r.Shadow.Scene.LightActiveFrameCount setting.
• It’s defined in the Renderer module and is used to retrieve the current value of the setting in the render thread.
• The value is clamped to a minimum of 1 frame to ensure proper functionality.
• It’s accessed in the UpdateForRenderedFrame function of the FShadowScene class, which is responsible for updating the shadow rendering state each frame.

Developers should use this console variable when they need to programmatically adjust the light active frame count setting, either for debugging purposes or to implement dynamic adjustments based on game conditions or performance requirements.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowScene.cpp:17

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarShadowSceneLightActiveFrameCount(
	TEXT("r.Shadow.Scene.LightActiveFrameCount"),
	10,
	TEXT("Number of frames before a light that has been moving (updated or transform changed) goes to inactive state.\n")
	TEXT("  This determines the number of frames that the MobilityFactor goes to zero over, and thus a higher number spreads invalidations out over a longer time."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowScene.cpp:16

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarShadowSceneLightActiveFrameCount(
	TEXT("r.Shadow.Scene.LightActiveFrameCount"),
	10,
	TEXT("Number of frames before a light that has been moving (updated or transform changed) goes to inactive state.\n")
	TEXT("  This determines the number of frames that the MobilityFactor goes to zero over, and thus a higher number spreads invalidations out over a longer time."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowScene.cpp:106

Scope (from outer to inner):

file
function     void FShadowScene::UpdateForRenderedFrame

Source code excerpt:

	SceneChangeUpdateTask.Wait();

	const int32 ActiveFrameCount = FMath::Max(1, CVarShadowSceneLightActiveFrameCount.GetValueOnRenderThread());
	
	// 1. FScene::FrameNumber is incremented before a call to render is being dispatched to the RT.
	int32 SceneFrameNumber = Scene.GetFrameNumberRenderThread();
	// Iterate the previously active lights and update
	for (TConstSetBitIterator<> BitIt(ActiveLights); BitIt; ++BitIt)
	{