r.Shadow.Virtual.DebugSkipMergePhysical

r.Shadow.Virtual.DebugSkipMergePhysical

#Overview

name: r.Shadow.Virtual.DebugSkipMergePhysical

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.DebugSkipMergePhysical is to control the merging of static Virtual Shadow Map (VSM) cache into the dynamic one in Unreal Engine 5’s rendering system. This setting is specifically designed for debugging and testing purposes within the Virtual Shadow Map implementation.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5, specifically in the Virtual Shadow Map module. It is defined and used in the VirtualShadowMapArray.cpp file, which is part of the Renderer module.

The value of this variable is set through the console variable system in Unreal Engine. It is initialized with a default value of 0, meaning the merging is not skipped by default.

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

Developers must be aware that enabling this variable (setting it to a non-zero value) will skip the merging of the static VSM cache into the dynamic one. This will create obvious visual artifacts, as mentioned in the variable’s description. Therefore, this setting should only be used for debugging purposes and not in production builds.

Best practices when using this variable include:

  1. Only enable it temporarily for debugging specific shadow-related issues.
  2. Always disable it (set to 0) before creating production builds.
  3. Be prepared for visual artifacts when this setting is enabled.
  4. Use in conjunction with other shadow debugging tools for comprehensive shadow system analysis.

Regarding the associated variable CVarDebugSkipMergePhysical:

The purpose of CVarDebugSkipMergePhysical is identical to r.Shadow.Virtual.DebugSkipMergePhysical. It’s an internal representation of the console variable within the C++ code.

This variable is used in the rendering subsystem, specifically in the Virtual Shadow Map implementation within the Renderer module.

The value of CVarDebugSkipMergePhysical is set through the TAutoConsoleVariable template, which links it to the r.Shadow.Virtual.DebugSkipMergePhysical console command.

CVarDebugSkipMergePhysical directly interacts with r.Shadow.Virtual.DebugSkipMergePhysical, as they represent the same setting.

Developers should be aware that this variable is checked in the MergeStaticPhysicalPages function of the FVirtualShadowMapArray class. When enabled, it causes this function to return early, skipping the merging process.

Best practices for using CVarDebugSkipMergePhysical include:

  1. Use GetValueOnRenderThread() to access its value safely in render thread code.
  2. Be cautious when modifying the behavior controlled by this variable, as it can significantly impact shadow rendering.
  3. Consider wrapping usage of this variable with #if !UE_BUILD_SHIPPING to ensure it’s not accidentally used in shipping builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:283

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarDebugSkipMergePhysical(
	TEXT("r.Shadow.Virtual.DebugSkipMergePhysical"),
	0,
	TEXT("Skip the merging of the static VSM cache into the dynamic one. This will create obvious visual artifacts when disabled."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarDebugSkipDynamicPageInvalidation(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:282

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarDebugSkipMergePhysical(
	TEXT("r.Shadow.Virtual.DebugSkipMergePhysical"),
	0,
	TEXT("Skip the merging of the static VSM cache into the dynamic one. This will create obvious visual artifacts when disabled."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:974

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::MergeStaticPhysicalPages

Source code excerpt:


#if !UE_BUILD_SHIPPING
	if (CVarDebugSkipMergePhysical.GetValueOnRenderThread() != 0)
	{
		return;
	}
#endif

	RDG_EVENT_SCOPE(GraphBuilder, "FVirtualShadowMapArray::MergeStaticPhysicalPages");