r.Shadow.Virtual.MaxDistantUpdatePerFrame

r.Shadow.Virtual.MaxDistantUpdatePerFrame

#Overview

name: r.Shadow.Virtual.MaxDistantUpdatePerFrame

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

• type: Var
• help: Maximum number of distant lights to update each frame. Invalidated lights that were missed may be updated in a later frame (round-robin).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.MaxDistantUpdatePerFrame is to control the maximum number of distant lights that can be updated each frame in the virtual shadow mapping system. This setting is part of Unreal Engine 5’s rendering system, specifically focusing on shadow rendering optimization.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the shadow rendering subsystem. Based on the callsites, it’s clear that this variable is utilized in the ShadowSceneRenderer.cpp file, which is responsible for managing shadow rendering in the scene.

The value of this variable is set through a console variable (CVarMaxDistantLightsPerFrame) with a default value of 1. It can be modified at runtime using console commands or through engine configuration files.

The associated variable CVarMaxDistantLightsPerFrame directly interacts with r.Shadow.Virtual.MaxDistantUpdatePerFrame. They share the same value and purpose.

Developers must be aware of several important aspects when using this variable:

1. Setting this value too high might impact performance, as more distant lights will be updated each frame.
2. Setting it too low might result in less frequent updates for distant lights, potentially causing visual inconsistencies.
3. A value of 0 disables distant light updates entirely.
4. Negative values are treated as INT32_MAX, effectively removing the update limit.

Best practices when using this variable include:

1. Adjust the value based on the scene complexity and performance requirements.
2. Monitor performance impact when modifying this value.
3. Consider the trade-off between shadow quality and performance when adjusting this setting.
4. Use in conjunction with other shadow-related settings for optimal results.

Regarding the associated variable CVarMaxDistantLightsPerFrame:

The purpose of CVarMaxDistantLightsPerFrame is identical to r.Shadow.Virtual.MaxDistantUpdatePerFrame, as they share the same value and functionality. It’s an internal representation of the console variable used in the C++ code.

This variable is used directly in the FShadowSceneRenderer::BeginRender function to determine the maximum number of distant lights to update. It’s retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access to the current value.

Developers should be aware that modifying CVarMaxDistantLightsPerFrame directly in code will have the same effect as changing r.Shadow.Virtual.MaxDistantUpdatePerFrame through console commands or configuration files.

Best practices for CVarMaxDistantLightsPerFrame align with those of r.Shadow.Virtual.MaxDistantUpdatePerFrame, as they are essentially the same setting represented in different ways within the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:25

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarMaxDistantLightsPerFrame(
	TEXT("r.Shadow.Virtual.MaxDistantUpdatePerFrame"),
	1,
	TEXT("Maximum number of distant lights to update each frame. Invalidated lights that were missed may be updated in a later frame (round-robin)."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarDistantLightMode(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:24

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarMaxDistantLightsPerFrame(
	TEXT("r.Shadow.Virtual.MaxDistantUpdatePerFrame"),
	1,
	TEXT("Maximum number of distant lights to update each frame. Invalidated lights that were missed may be updated in a later frame (round-robin)."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp:126

Scope (from outer to inner):

file
function     void FShadowSceneRenderer::BeginRender

Source code excerpt:

	// Priority queue of distant lights to update.
	const int32 MaxToUpdate = CVarMaxDistantLightsPerFrame.GetValueOnRenderThread() < 0 ? INT32_MAX : CVarMaxDistantLightsPerFrame.GetValueOnRenderThread();

	if (MaxToUpdate == 0 || !VirtualShadowMapArray.IsEnabled() || !VirtualShadowMapArray.CacheManager->IsCacheEnabled())
	{
		return;
	}