r.Shadow.Virtual.ForceOnlyVirtualShadowMaps

r.Shadow.Virtual.ForceOnlyVirtualShadowMaps

#Overview

name: r.Shadow.Virtual.ForceOnlyVirtualShadowMaps

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.ForceOnlyVirtualShadowMaps is to control the creation of shadow maps in Unreal Engine 5’s rendering system. Specifically, it determines whether to allow or disallow the creation of conventional non-virtual shadow maps for lights that are eligible for virtual shadow maps.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, particularly in the shadow rendering module. Based on the callsites, it’s utilized in the ShadowSetup.cpp file, which is responsible for setting up shadow rendering.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s initialized with a default value of 1, meaning it’s enabled by default.

This variable interacts closely with the virtual shadow map system. When enabled, it forces the engine to use only virtual shadow maps for eligible lights, potentially improving performance and saving memory.

Developers must be aware that enabling this variable can have significant implications:

  1. It can improve performance and save memory by reducing the number of conventional shadow maps.
  2. However, any geometric primitives that cannot be rendered into the virtual shadow map will not cast shadows, which could affect the visual quality of the scene.

Best practices when using this variable include:

  1. Testing thoroughly to ensure that the visual quality of shadows meets the project’s requirements when enabled.
  2. Considering the trade-off between performance/memory savings and shadow quality.
  3. Being aware of any objects in the scene that might not be compatible with virtual shadow maps and how they will be affected.

The associated variable CVarForceOnlyVirtualShadowMaps is the actual console variable that controls this setting. It’s defined as an integer with the same name as the setting (“r.Shadow.Virtual.ForceOnlyVirtualShadowMaps”). This variable is used directly in the code to check whether only virtual shadow maps should be used.

The purpose of CVarForceOnlyVirtualShadowMaps is to provide a runtime-configurable way to enable or disable the “force only virtual shadow maps” feature. It’s used in the shadow setup process to determine whether to create conventional shadow maps for lights that are eligible for virtual shadow maps.

This variable is crucial for the shadow rendering system and is checked during the creation of whole scene projected shadows and view-dependent whole scene shadows. Developers should be aware that changing this variable at runtime will immediately affect shadow rendering behavior.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarForceOnlyVirtualShadowMaps(
	TEXT("r.Shadow.Virtual.ForceOnlyVirtualShadowMaps"),
	1,
	TEXT("If enabled, disallow creation of conventional non-virtual shadow maps for any lights that get a virtual shadow map.\n")
	TEXT("This can improve performance and save memory, but any geometric primitives that cannot be rendered into the virtual shadow map will not cast shadows."),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarForceOnlyVirtualShadowMaps(
	TEXT("r.Shadow.Virtual.ForceOnlyVirtualShadowMaps"),
	1,
	TEXT("If enabled, disallow creation of conventional non-virtual shadow maps for any lights that get a virtual shadow map.\n")
	TEXT("This can improve performance and save memory, but any geometric primitives that cannot be rendered into the virtual shadow map will not cast shadows."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void FSceneRenderer::CreateWholeSceneProjectedShadow

Source code excerpt:

				
				// If using *only* virtual shadow maps via forced CVar, skip creation of the non-virtual shadow map
				if (!bNeedsVirtualShadowMap || CVarForceOnlyVirtualShadowMaps.GetValueOnRenderThread() == 0)
				{
					for (int32 CacheModeIndex = 0; CacheModeIndex < NumShadowMaps; CacheModeIndex++)
					{
						// Create the projected shadow info.
						FProjectedShadowInfo* ProjectedShadowInfo = Allocator.Create<FProjectedShadowInfo>();

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

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;