r.DebugSafeZone.Mode

r.DebugSafeZone.Mode

#Overview

name: r.DebugSafeZone.Mode

This variable is created as a Console Variable (cvar).

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DebugSafeZone.Mode is to control the visualization of safe zones in Unreal Engine 5. It is primarily used for debugging and visualizing the title safe zone and action safe zone in the game viewport.

This setting variable is mainly utilized by the rendering system, specifically for HUD and viewport debugging. Based on the callsites, it is primarily used in the Engine module, particularly in the HUD and GameViewportClient classes.

The value of this variable is set through the console or programmatically. It can be changed using console commands or by directly modifying the CVar (Console Variable) in code.

The r.DebugSafeZone.Mode variable interacts with the associated variable GSafeZoneVisualizationModeCVar. They share the same value and purpose, with GSafeZoneVisualizationModeCVar being the actual TAutoConsoleVariable instance that stores the value.

Developers should be aware that this variable has three possible values: 0: Disabled (default) 1: Show Title Safe Zone 2: Show Action Safe Zone

When using this variable, developers should consider the following best practices:

  1. Use it primarily for debugging purposes during development.
  2. Be cautious when enabling it in production builds, as it may impact performance or visuals.
  3. Consider providing a user-friendly way to toggle this debug visualization in development builds.

Regarding the associated variable GSafeZoneVisualizationModeCVar:

The purpose of GSafeZoneVisualizationModeCVar is to store and provide access to the safe zone visualization mode value. It is an instance of TAutoConsoleVariable that corresponds to the r.DebugSafeZone.Mode console variable.

This variable is used in the Engine module, specifically in the HUD class for drawing the safe zone overlay. It is accessed using the GetValueOnGameThread() method to determine which type of safe zone (if any) should be visualized.

The value of GSafeZoneVisualizationModeCVar is set when the r.DebugSafeZone.Mode console variable is modified, as they are directly linked.

Developers should be aware that this variable is thread-safe and should be accessed using the GetValueOnGameThread() method when used in game thread contexts.

Best practices for using GSafeZoneVisualizationModeCVar include:

  1. Use it for reading the current safe zone visualization mode in game code.
  2. Avoid directly modifying this variable; instead, use the r.DebugSafeZone.Mode console command to change its value.
  3. Consider caching the value if it’s accessed frequently to avoid potential performance impact from repeated CVar lookups.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:37

Scope: file

Source code excerpt:

// Should we visualize the safe zone? (and if so, title or action?)
TAutoConsoleVariable<int32> GSafeZoneVisualizationModeCVar(
	TEXT("r.DebugSafeZone.Mode"),
	0,
	TEXT("The safe zone visualization mode (0..2)\n")
	TEXT(" 0: Disabled (default)\n")
	TEXT(" 1: Show Title Safe Zone\n")
	TEXT(" 2: Show Action Safe Zone"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/GameViewportClient.h:130

Scope: file

Source code excerpt:


	/** Exec for toggling the display of the title safe area
	  * @deprecated Use the cvar "r.DebugSafeZone.Mode=1".
	  */
	UFUNCTION(exec, meta = (DeprecatedFunction, DeprecationMessage = "Use the cvar \"r.DebugSafeZone.Mode=1.\""))
	ENGINE_API virtual void ShowTitleSafeArea();

	/** Sets the player which console commands will be executed in the context of. */
	UFUNCTION(exec)
	ENGINE_API virtual void SetConsoleTarget(int32 PlayerIndex);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/GameViewportClient.h:469

Scope: file

Source code excerpt:


	/**  
	 * Draws the safe area using the current r.DebugSafeZone.Mode=1 when there is not a valid PlayerController HUD.
	 * 
	 * @param Canvas	Canvas on which to draw
	 */
	ENGINE_API virtual void DrawTitleSafeArea( UCanvas* Canvas );

	/**
	 * Called after rendering the player views and HUDs to render menus, the console, etc.
	 * This is the last rendering call in the render loop
	 *
	 * @param Canvas	The canvas to use for rendering.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:2393

Scope (from outer to inner):

file
function     void UGameViewportClient::ShowTitleSafeArea

Source code excerpt:

void UGameViewportClient::ShowTitleSafeArea()
{
	static IConsoleVariable* DebugSafeZoneModeCvar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DebugSafeZone.Mode"));
	if (DebugSafeZoneModeCvar)
	{
		const int32 DebugSafeZoneMode = DebugSafeZoneModeCvar->GetInt();
		if (DebugSafeZoneMode != 1)
		{
			DebugSafeZoneModeCvar->Set(1);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:2837

Scope (from outer to inner):

file
function     void UGameViewportClient::DrawTitleSafeArea

Source code excerpt:

	}

	// If r.DebugSafeZone.Mode isn't set to draw title area, don't draw it.
	static IConsoleVariable* SafeZoneModeCvar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.DebugSafeZone.Mode"));
	if (SafeZoneModeCvar && (SafeZoneModeCvar->GetInt() != 1))
	{
		return;
	}

	FMargin SafeZone;

#Loc: <Workspace>/Engine/Source/Runtime/UMG/Public/Components/SafeZone.h:20

Scope: file

Source code excerpt:

 * 
 * To enable a red band to visualize the safe zone, use this console command,
 * r.DebugSafeZone.Mode controls the debug visualization overlay (0..2, default 0).
 *   0: Do not display the safe zone overlay.
 *   1: Display the overlay for the title safe zone.
 *   2: Display the overlay for the action safe zone.
 */
UCLASS(MinimalAPI)
class USafeZone : public UContentWidget
{
	GENERATED_BODY()
public:
	UMG_API USafeZone();

#if WITH_EDITOR
	UMG_API virtual const FText GetPaletteCategory() override;

	UMG_API virtual void OnDesignerChanged(const FDesignerChangedEventArgs& EventArgs) override;
#endif

	UMG_API virtual void OnSlotAdded( UPanelSlot* Slot ) override;
	UMG_API virtual void OnSlotRemoved( UPanelSlot* Slot ) override;
	UMG_API virtual UClass* GetSlotClass() const override;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:36

Scope: file

Source code excerpt:


// Should we visualize the safe zone? (and if so, title or action?)
TAutoConsoleVariable<int32> GSafeZoneVisualizationModeCVar(
	TEXT("r.DebugSafeZone.Mode"),
	0,
	TEXT("The safe zone visualization mode (0..2)\n")
	TEXT(" 0: Disabled (default)\n")
	TEXT(" 1: Show Title Safe Zone\n")
	TEXT(" 2: Show Action Safe Zone"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:262

Scope (from outer to inner):

file
function     void AHUD::DrawSafeZoneOverlay

Source code excerpt:

{
#if ENABLE_DRAW_DEBUG
	const int32 DebugSafeZoneMode = GSafeZoneVisualizationModeCVar.GetValueOnGameThread();

	if ((DebugSafeZoneMode > 0) && (DebugCanvas != nullptr) && (DebugCanvas->Canvas != nullptr))
	{

		const float Width = DebugCanvas->SizeX;
		const float Height = DebugCanvas->SizeY;