r.Shadow.Virtual.DistantLightMode

r.Shadow.Virtual.DistantLightMode

#Overview

name: r.Shadow.Virtual.DistantLightMode

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.DistantLightMode is to control the distant light mode for local lights in the virtual shadow mapping system. This setting is part of Unreal Engine 5’s rendering system, specifically the shadow rendering subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the shadow rendering component. This can be seen from the file location where the variable is defined: ‘Engine/Source/Runtime/Renderer/Private/Shadows/ShadowSceneRenderer.cpp’.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, but can be changed at runtime through console commands or project settings.

This variable interacts with another variable named CVarDistantLightMode, which is the actual TAutoConsoleVariable that stores and manages the value. They essentially represent the same setting.

Developers must be aware that this variable has three possible values: 0 - Distant light mode is off 1 - Distant light mode is on (default) 2 - Force all lights to be treated as distant

When enabled, lights with a pixel footprint below a certain threshold are marked as distant. This affects how these lights are updated and rendered, potentially improving performance.

Best practices when using this variable include:

  1. Leave it at the default value (1) unless specific optimization is needed.
  2. If performance issues are observed with many small lights, consider enabling it (if it’s not already).
  3. Use the “Force All” option (2) cautiously, as it might affect visual quality for nearby lights.
  4. Monitor the performance impact when changing this setting, as its effect can vary depending on the scene composition.

Regarding the associated variable CVarDistantLightMode: This is the actual console variable that stores the value of r.Shadow.Virtual.DistantLightMode. It’s used in the code to retrieve the current setting value, as seen in the provided code excerpts. The value is typically accessed using CVarDistantLightMode.GetValueOnRenderThread().

Developers should note that changes to this variable are considered render thread safe (ECVF_RenderThreadSafe), meaning they can be applied without causing rendering artifacts or crashes. However, changing this value frequently during runtime is not recommended, as it could impact performance due to the need for shadow recalculations.

#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:32

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarDistantLightMode(
	TEXT("r.Shadow.Virtual.DistantLightMode"),
	1,
	TEXT("Control whether distant light mode is enabled for local lights.\n0 == Off, \n1 == On (default), \n2 == Force All.\n")
	TEXT("When on, lights with a pixel footprint below the threshold are marked as distant. Updates to distant lights are throttled (force-cached), they use simpler page-table logic and the memory cost is lower."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarDistantLightMode(
	TEXT("r.Shadow.Virtual.DistantLightMode"),
	1,
	TEXT("Control whether distant light mode is enabled for local lights.\n0 == Off, \n1 == On (default), \n2 == Force All.\n")
	TEXT("When on, lights with a pixel footprint below the threshold are marked as distant. Updates to distant lights are throttled (force-cached), they use simpler page-table logic and the memory cost is lower."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     TSharedPtr<FVirtualShadowMapPerLightCacheEntry> FShadowSceneRenderer::AddLocalLightShadow

Source code excerpt:

	//       Of course this creates jumps if visibility changes, which may or may not create unsolvable artifacts.	
	const float BiasedFootprintThreshold = float(FVirtualShadowMap::PageSize) * FMath::Exp2(ResolutionLODBiasLocal);
	const bool bIsDistantLight = CVarDistantLightMode.GetValueOnRenderThread() != 0
		&& (MaxScreenRadius <= BiasedFootprintThreshold || CVarDistantLightMode.GetValueOnRenderThread() == 2);

	const int32 NumMaps = ProjectedShadowInitializer.bOnePassPointLightShadow ? 6 : 1;
	TSharedPtr<FVirtualShadowMapPerLightCacheEntry> PerLightCacheEntry = CacheManager->FindCreateLightCacheEntry(LightSceneInfo->Id, 0, NumMaps);
			
	const float DistantLightForceCacheFootprintFraction = FMath::Clamp(CVarDistantLightForceCacheFootprintFraction.GetValueOnRenderThread(), 0.0f, 1.0f);
	bool bShouldForceTimeSliceDistantUpdate = (bIsDistantLight && MaxScreenRadius <= BiasedFootprintThreshold * DistantLightForceCacheFootprintFraction);