r.Shadow.Virtual.Visualize.Layout

r.Shadow.Virtual.Visualize.Layout

#Overview

name: r.Shadow.Virtual.Visualize.Layout

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.Visualize.Layout is to control the visualization layout of virtual shadow maps in Unreal Engine 5’s rendering system. This setting variable is specifically designed for debugging and development purposes, allowing developers to view the virtual shadow map data in different layouts on the screen.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the virtual shadow mapping system. Based on the callsites, it’s clear that this variable is utilized in the VirtualShadowMapArray.cpp file, which is part of the rendering pipeline responsible for handling virtual shadow maps.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with three possible integer values: 0: Full screen 1: Thumbnail 2: Split screen

The associated variable CVarVisualizeLayout directly interacts with r.Shadow.Virtual.Visualize.Layout. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable is intended for visualization purposes only and should not be used in production builds. It’s marked as ECVF_RenderThreadSafe, meaning it can be safely changed on the render thread without causing synchronization issues.

Best practices when using this variable include:

  1. Use it only during development and debugging phases.
  2. Be cautious when changing its value at runtime, as it may impact performance.
  3. Understand the different layout options and choose the most appropriate one for the current debugging task.
  4. Remember to disable the visualization in final builds to avoid any performance overhead.

Regarding the associated variable CVarVisualizeLayout:

The purpose of CVarVisualizeLayout is to provide a programmatic way to access and modify the r.Shadow.Virtual.Visualize.Layout setting within the C++ code. It allows developers to read and potentially modify the visualization layout at runtime.

CVarVisualizeLayout is used in the FVirtualShadowMapArray::AddVisualizePass function to determine how to set up the output viewport for the virtual shadow map visualization. The value is retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access to the current setting.

Developers should be aware that modifying CVarVisualizeLayout directly in code will affect the r.Shadow.Virtual.Visualize.Layout setting. It’s important to use this variable consistently with the console variable to avoid confusion.

Best practices for using CVarVisualizeLayout include:

  1. Always access its value using GetValueOnRenderThread() when in render thread code.
  2. Consider caching the value if it’s accessed frequently to avoid repeated calls to GetValueOnRenderThread().
  3. Use it in conjunction with other debugging tools and visualizations for a comprehensive understanding of the virtual shadow mapping system.
  4. Remember that changes to this variable will immediately affect the visualization output, so use it judiciously during development and testing.

#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:273

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarVisualizeLayout(
	TEXT("r.Shadow.Virtual.Visualize.Layout"),
	0,
	TEXT("Overlay layout when virtual shadow map visualization is enabled:\n")
	TEXT("  0: Full screen\n")
	TEXT("  1: Thumbnail\n")
	TEXT("  2: Split screen"),
	ECVF_RenderThreadSafe

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarVisualizeLayout(
	TEXT("r.Shadow.Virtual.Visualize.Layout"),
	0,
	TEXT("Overlay layout when virtual shadow map visualization is enabled:\n")
	TEXT("  0: Full screen\n")
	TEXT("  1: Thumbnail\n")
	TEXT("  2: Split screen"),

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

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::AddVisualizePass

Source code excerpt:

		FScreenPassTextureViewport OutputViewport(Output);

		// See CVarVisualizeLayout documentation
		const int32 VisualizeLayout = CVarVisualizeLayout.GetValueOnRenderThread();
		if (VisualizeLayout == 1)		// Thumbnail
		{
			const int32 TileWidth  = View.UnscaledViewRect.Width() / 3;
			const int32 TileHeight = View.UnscaledViewRect.Height() / 3;

			OutputViewport.Rect.Max = OutputViewport.Rect.Min + FIntPoint(TileWidth, TileHeight);