r.Shadow.DrawPreshadowFrustums

r.Shadow.DrawPreshadowFrustums

#Overview

name: r.Shadow.DrawPreshadowFrustums

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.DrawPreshadowFrustums is to visualize preshadow frustums when the shadowfrustums show flag is enabled in Unreal Engine 5. This setting variable is primarily used for debugging and visual inspection of shadow rendering.

This setting variable is part of the rendering system, specifically the shadow rendering subsystem within Unreal Engine 5. Based on the callsites, it is utilized in the Renderer module, particularly in the shadow setup and initialization process.

The value of this variable is set through the console variable system in Unreal Engine. It is defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

The associated variable CVarDrawPreshadowFrustum directly interacts with r.Shadow.DrawPreshadowFrustums. They share the same value and purpose.

Developers must be aware that this variable is intended for debugging purposes. Enabling it may have performance implications, as it adds additional visualization elements to the rendering process. It should be used judiciously and primarily during development or when investigating shadow-related issues.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging shadow issues.
  2. Ensure it’s disabled in production builds to avoid unnecessary performance overhead.
  3. Use it in conjunction with the shadowfrustums show flag for comprehensive shadow visualization.
  4. Be mindful of potential visual clutter when enabled, especially in complex scenes with many shadow-casting objects.

Regarding the associated variable CVarDrawPreshadowFrustum:

The purpose of CVarDrawPreshadowFrustum is identical to r.Shadow.DrawPreshadowFrustums. It’s an internal representation of the console variable used within the C++ code.

This variable is used directly in the rendering code to determine whether to draw the preshadow frustums. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to its value.

The value of CVarDrawPreshadowFrustum is set through the r.Shadow.DrawPreshadowFrustums console command, as they are linked.

Developers should be aware that this variable is used in conditional statements within the shadow rendering logic. Changing its value at runtime will immediately affect the visualization of preshadow frustums.

Best practices for CVarDrawPreshadowFrustum align with those of r.Shadow.DrawPreshadowFrustums, as they are essentially the same variable represented in different contexts within the engine code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

/** Can be used to visualize preshadow frustums when the shadowfrustums show flag is enabled. */
static TAutoConsoleVariable<int32> CVarDrawPreshadowFrustum(
	TEXT("r.Shadow.DrawPreshadowFrustums"),
	0,
	TEXT("visualize preshadow frustums when the shadowfrustums show flag is enabled"),
	ECVF_RenderThreadSafe
	);

/** Whether to allow preshadows (static world casting on character), can be disabled for debugging. */

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


/** Can be used to visualize preshadow frustums when the shadowfrustums show flag is enabled. */
static TAutoConsoleVariable<int32> CVarDrawPreshadowFrustum(
	TEXT("r.Shadow.DrawPreshadowFrustums"),
	0,
	TEXT("visualize preshadow frustums when the shadowfrustums show flag is enabled"),
	ECVF_RenderThreadSafe
	);

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

Scope (from outer to inner):

file
function     void FSceneRenderer::InitProjectedShadowVisibility

Source code excerpt:

					if(bPrimitiveIsShadowRelevant && !bShadowIsOccluded)
					{
						bool bDrawPreshadowFrustum = CVarDrawPreshadowFrustum.GetValueOnRenderThread() != 0;

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