r.Shadow.Virtual.UseFarShadowCulling

r.Shadow.Virtual.UseFarShadowCulling

#Overview

name: r.Shadow.Virtual.UseFarShadowCulling

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

• type: Var
• help: Switch between implementing the far shadow culling logic for VSMs.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.UseFarShadowCulling is to control the implementation of far shadow culling logic for Virtual Shadow Maps (VSMs) in Unreal Engine 5’s rendering system.

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

The value of this variable is set through a console variable (CVarVsmUseFarShadowRules) with a default value of 1, meaning the far shadow culling logic for VSMs is enabled by default. Developers can modify this value at runtime using console commands.

This variable interacts closely with other shadow-related variables, particularly those concerning Virtual Shadow Maps. It’s used in conjunction with CVarForceOnlyVirtualShadowMaps to determine the shadow mapping approach.

Developers should be aware that this variable affects the culling behavior of Virtual Shadow Maps. When enabled (set to 1), it implements far shadow culling logic for VSMs, which can potentially improve performance by reducing the number of shadows that need to be rendered.

Best practices when using this variable include:

1. Testing performance with and without far shadow culling to determine the optimal setting for your specific use case.
2. Considering the visual impact of far shadow culling on your scenes, especially for distant objects.
3. Using this in conjunction with other shadow-related settings to achieve the best balance between performance and visual quality.

Regarding the associated variable CVarVsmUseFarShadowRules:

This is the actual console variable that controls the r.Shadow.Virtual.UseFarShadowCulling setting. It’s defined in the same file (ShadowSetup.cpp) and is used to retrieve the current value of the setting in the render thread.

The purpose of CVarVsmUseFarShadowRules is to provide a runtime-modifiable interface for the r.Shadow.Virtual.UseFarShadowCulling setting. It’s used in the shadow setup process to determine whether to apply far shadow culling rules to Virtual Shadow Maps.

Developers should be aware that changes to this console variable will take effect on the render thread, which means the changes may not be immediate but will be applied in the next frame or render pass.

When using this variable, it’s best to modify it through the appropriate Unreal Engine console commands or configuration files, rather than directly in code, to ensure proper synchronization across the engine’s subsystems.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:308

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarVsmUseFarShadowRules(
	TEXT("r.Shadow.Virtual.UseFarShadowCulling"),
	1,
	TEXT("Switch between implementing the far shadow culling logic for VSMs."),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarClipmapUseConservativeCulling(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:307

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarVsmUseFarShadowRules(
	TEXT("r.Shadow.Virtual.UseFarShadowCulling"),
	1,
	TEXT("Switch between implementing the far shadow culling logic for VSMs."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:5410

Scope (from outer to inner):

file
function     void FSceneRenderer::AddViewDependentWholeSceneShadowsForView

Source code excerpt:

			bool bForceOnlyVirtualShadowMaps = CVarForceOnlyVirtualShadowMaps.GetValueOnRenderThread() != 0;
			bool bVsmUseFarShadowRules = CVarVsmUseFarShadowRules.GetValueOnRenderThread() != 0;
			if (!bNeedsVirtualShadowMap || !bForceOnlyVirtualShadowMaps || bVsmUseFarShadowRules)
			{
				for (int32 Index = 0; Index < ProjectionCount; Index++)
				{
					FWholeSceneProjectedShadowInitializer ProjectedShadowInitializer;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:5605

Scope (from outer to inner):

file
function     void FSceneRenderer::AddViewDependentWholeSceneShadowsForView

Source code excerpt:

					// Create the projected shadow info to make sure that culling happens.
					FProjectedShadowInfo* ProjectedShadowInfo = Allocator.Create<FProjectedShadowInfo>();
					ProjectedShadowInfo->SetupClipmapProjection(&LightSceneInfo, &View, VirtualShadowMapClipmap, CVarVsmUseFarShadowRules.GetValueOnRenderThread() != 0 ? MaxNonFarCascadeDistance : -1.0f);
					VisibleLightInfo.AllProjectedShadows.Add(ProjectedShadowInfo);
					ShadowInfosThatNeedCulling.Add(ProjectedShadowInfo);

					ProjectedShadowInfo->VirtualShadowMapPerLightCacheEntry = VirtualShadowMapClipmap->GetCacheEntry();

					// TODO: disentangle from legacy setup alltogether