ShowFlag.ShadowFrustums

ShowFlag.ShadowFrustums

#Overview

name: ShowFlag.ShadowFrustums

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 ShowFlag.ShadowFrustums is to control the visibility of shadow frustums in the rendering system of Unreal Engine 5. It is specifically used to display un-occluded shadow frustums in wireframe mode for debugging and visualization purposes.

This setting variable is primarily used in the rendering subsystem of Unreal Engine 5. Based on the callsites, it’s utilized in the SceneRenderer and MobileSceneRenderer modules, which are responsible for rendering scenes in the engine.

The value of this variable is set through the engine’s show flags system. It’s defined in the ShowFlagsValues.inl file with a default value of 0, meaning it’s disabled by default in shipping builds.

ShowFlag.ShadowFrustums interacts with other rendering-related variables and systems. For example, it’s used in conjunction with CVarDrawPreshadowFrustum to determine whether to draw pre-shadow frustums.

Developers should be aware that this variable is primarily intended for debugging and development purposes. It’s marked as SHOWFLAG_FIXED_IN_SHIPPING(0, …), which means it’s forced to be disabled in shipping builds.

Best practices for using this variable include:

  1. Only enable it when debugging shadow-related issues or when you need to visualize shadow frustums.
  2. Be aware that enabling this flag may have performance implications, especially in complex scenes with many shadow-casting lights.
  3. Use it in conjunction with other shadow-related debug tools and visualizations for comprehensive shadow debugging.

The associated variable ShadowFrustums is essentially the same as ShowFlag.ShadowFrustums. It’s used in the same context and serves the same purpose. The naming convention ShowFlag.ShadowFrustums is likely used in certain parts of the engine to explicitly denote it as a show flag, while ShadowFrustums might be used in other contexts where the show flag nature is implicit.

When working with ShadowFrustums, developers should follow the same guidelines and best practices as with ShowFlag.ShadowFrustums. It’s important to note that this variable is categorized as SFG_Advanced, indicating it’s an advanced feature that should be used with care and understanding of its implications on rendering and performance.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, Pivot, SFG_Hidden, NSLOCTEXT("UnrealEd", "PivotSF", "Pivot"))
/** Draws un-occluded shadow frustums in wireframe */
SHOWFLAG_FIXED_IN_SHIPPING(0, ShadowFrustums, SFG_Advanced, NSLOCTEXT("UnrealEd", "ShadowFrustumsSF", "Shadow Frustums"))
/** needed for VMI_Wireframe and VMI_BrushWireframe */
SHOWFLAG_FIXED_IN_SHIPPING(0, Wireframe, SFG_Hidden, NSLOCTEXT("UnrealEd", "WireframeSF", "Wireframe"))
/**  */
SHOWFLAG_FIXED_IN_SHIPPING(1, Materials, SFG_Hidden, NSLOCTEXT("UnrealEd", "MaterialsSF", "Materials"))
/** for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(StaticMeshes, SFG_Normal, NSLOCTEXT("UnrealEd", "StaticMeshesSF", "Static Meshes"))

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, Pivot, SFG_Hidden, NSLOCTEXT("UnrealEd", "PivotSF", "Pivot"))
/** Draws un-occluded shadow frustums in wireframe */
SHOWFLAG_FIXED_IN_SHIPPING(0, ShadowFrustums, SFG_Advanced, NSLOCTEXT("UnrealEd", "ShadowFrustumsSF", "Shadow Frustums"))
/** needed for VMI_Wireframe and VMI_BrushWireframe */
SHOWFLAG_FIXED_IN_SHIPPING(0, Wireframe, SFG_Hidden, NSLOCTEXT("UnrealEd", "WireframeSF", "Wireframe"))
/**  */
SHOWFLAG_FIXED_IN_SHIPPING(1, Materials, SFG_Hidden, NSLOCTEXT("UnrealEd", "MaterialsSF", "Materials"))
/** for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(StaticMeshes, SFG_Normal, NSLOCTEXT("UnrealEd", "StaticMeshesSF", "Static Meshes"))

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

Scope (from outer to inner):

file
function     void FSceneRenderer::InitProjectedShadowVisibility

Source code excerpt:

						bool bDrawPreshadowFrustum = CVarDrawPreshadowFrustum.GetValueOnRenderThread() != 0;

						if (ViewFamily.EngineShowFlags.ShadowFrustums && ((bDrawPreshadowFrustum && ProjectedShadowInfo.bPreShadow) || (!bDrawPreshadowFrustum && !ProjectedShadowInfo.bPreShadow)))
						{
							TaskData.DrawDebugShadowFrustumOps.Emplace(Views[ViewIndex], ProjectedShadowInfo);
						}
					}
				}
			}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetupMobile.cpp:428

Scope (from outer to inner):

file
function     void FMobileSceneRenderer::BuildCSMVisibilityState

Source code excerpt:

			FProjectedShadowInfo* ProjectedShadowInfo = &SingleCascadeInfo;

			if (ViewFamily.EngineShowFlags.ShadowFrustums)
			{
				FViewElementPDI ShadowFrustumPDI(&View, nullptr, nullptr);
				
				const FMatrix ViewMatrix = View.ViewMatrices.GetViewMatrix();
				const FMatrix ProjectionMatrix = View.ViewMatrices.GetProjectionMatrix();
				const FVector4 ViewOrigin = View.ViewMatrices.GetViewOrigin();