ShowFlag.DebugDrawDistantVirtualSMLights

ShowFlag.DebugDrawDistantVirtualSMLights

#Overview

name: ShowFlag.DebugDrawDistantVirtualSMLights

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 ShowFlag.DebugDrawDistantVirtualSMLights is to enable debug drawing of distant virtual shadow map (VSM) lights in the Unreal Engine 5 rendering system. This setting is primarily used for debugging and visualizing the behavior of virtual shadow maps for lights that are far from the camera.

This setting variable is primarily used in the rendering system of Unreal Engine 5, specifically in the shadow rendering subsystem. Based on the callsites, it’s clear that this flag is part of the ShowFlags system, which is used to toggle various debug visualization features in the engine.

The value of this variable is set through the ShowFlags system. It is defined in the ShowFlagsValues.inl file, which suggests that it can be toggled through the engine’s debug menu or console commands.

The associated variable DebugDrawDistantVirtualSMLights interacts directly with this ShowFlag. They share the same value and are used interchangeably in the code.

Developers should be aware that this is a debug feature and is not intended for use in shipping builds. This is evident from the SHOWFLAG_FIXED_IN_SHIPPING macro, which sets the default value to 0 (disabled) for shipping builds.

Best practices when using this variable include:

  1. Only enable it when specifically debugging virtual shadow map issues related to distant lights.
  2. Be aware that enabling this flag may impact performance, as it’s designed for debugging rather than optimized rendering.
  3. Use it in conjunction with other shadow-related debug tools to get a comprehensive understanding of the shadow rendering system.
  4. Remember to disable it when not actively debugging to avoid any potential performance impact.

Regarding the associated variable DebugDrawDistantVirtualSMLights:

This variable is used directly in the shadow scene rendering code, specifically in the FShadowSceneRenderer::PostSetupDebugRender function. When enabled and virtual shadow maps are active, it triggers the debug drawing of distant virtual shadow map lights.

Developers should note that this debug feature is only available in non-shipping and non-test builds, as indicated by the #if !(UE_BUILD_SHIPPING || UE_BUILD_TEST) conditional compilation directive. This reinforces that it’s a development-only tool and should not be relied upon in final product builds.

When using this variable, developers can expect to see visual debug information about distant virtual shadow map lights, which can be useful for identifying issues with shadow rendering at a distance or optimizing the virtual shadow map system for large-scale environments.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:422

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(1, VirtualShadowMapPersistentData, SFG_Developer, NSLOCTEXT("UnrealEd", "VirtualShadowMapPersistentData", "Virtual Shadow Map Persistent Data"))

SHOWFLAG_FIXED_IN_SHIPPING(0, DebugDrawDistantVirtualSMLights, SFG_Advanced, NSLOCTEXT("UnrealEd", "DebugDrawDistantVirtualSMLightsSF", "Debug Draw Distant VSM Lights"))

/** Debug the Virtual Texture System */
SHOWFLAG_FIXED_IN_SHIPPING(0, VirtualTextureResidency, SFG_Hidden, NSLOCTEXT("UnrealEd", "VirtualTextureResidency", "Virtual Texture Residency"))

/** Input Debug Visualizer */
SHOWFLAG_FIXED_IN_SHIPPING(0, InputDebugVisualizer, SFG_Hidden, NSLOCTEXT("UnrealEd", "InputDebugVisualizer", "Input Debug Visualizer"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/ShowFlagsValues.inl:422

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(1, VirtualShadowMapPersistentData, SFG_Developer, NSLOCTEXT("UnrealEd", "VirtualShadowMapPersistentData", "Virtual Shadow Map Persistent Data"))

SHOWFLAG_FIXED_IN_SHIPPING(0, DebugDrawDistantVirtualSMLights, SFG_Advanced, NSLOCTEXT("UnrealEd", "DebugDrawDistantVirtualSMLightsSF", "Debug Draw Distant VSM Lights"))

/** Debug the Virtual Texture System */
SHOWFLAG_FIXED_IN_SHIPPING(0, VirtualTextureResidency, SFG_Hidden, NSLOCTEXT("UnrealEd", "VirtualTextureResidency", "Virtual Texture Residency"))

/** Input Debug Visualizer */
SHOWFLAG_FIXED_IN_SHIPPING(0, InputDebugVisualizer, SFG_Hidden, NSLOCTEXT("UnrealEd", "InputDebugVisualizer", "Input Debug Visualizer"))

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

Scope (from outer to inner):

file
function     void FShadowSceneRenderer::PostSetupDebugRender

Source code excerpt:

{
#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
	if ((SceneRenderer.ViewFamily.EngineShowFlags.DebugDrawDistantVirtualSMLights) && VirtualShadowMapArray.IsEnabled())
	{
		int32 NumFullyCached = 0;
		int32 NumDistant = 0;
		for (FViewInfo& View : SceneRenderer.Views)
		{
			FViewElementPDI DebugPDI(&View, nullptr, nullptr);