ShowFlag.CameraSafeFrames

ShowFlag.CameraSafeFrames

#Overview

name: ShowFlag.CameraSafeFrames

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.CameraSafeFrames is to control the rendering of safe frames in the camera view. This setting variable is primarily used in the rendering system, specifically for visualizing safe areas within the camera’s viewport.

This setting variable is relied upon by the Unreal Engine’s editor subsystem, particularly in the EditorViewportClient module. It’s used to determine whether safe frames should be displayed in the viewport.

The value of this variable is set through the SHOWFLAG_FIXED_IN_SHIPPING macro in the ShowFlagsValues.inl file. It’s set to 1 by default, meaning safe frames are enabled by default in non-shipping builds.

The CameraSafeFrames variable interacts with CameraAspectRatioBars. Both are used in conjunction to determine how to draw the safe frame and aspect ratio visualizations in the viewport.

Developers must be aware that this variable is fixed in shipping builds, meaning its value cannot be changed at runtime in a released game. It’s primarily a development and debugging tool.

Best practices when using this variable include:

  1. Use it in conjunction with CameraAspectRatioBars for a complete view of camera framing.
  2. Remember that it’s not available in shipping builds, so don’t rely on it for gameplay features.
  3. Use it to ensure important visual elements stay within safe areas across different display types.

Regarding the associated variable CameraSafeFrames:

The purpose of CameraSafeFrames is the same as ShowFlag.CameraSafeFrames. It’s used interchangeably in the code to refer to the same concept.

This variable is also used in the editor subsystem, specifically in the EditorViewportClient.

The value is set in the same place as ShowFlag.CameraSafeFrames, using the SHOWFLAG_FIXED_IN_SHIPPING macro.

It interacts directly with ShowFlag.CameraSafeFrames, effectively being the same variable.

Developers should be aware that checking the state of safe frames can be done using the IsShowingSafeFrameBoxDisplay() function in the EditorViewportClient class.

Best practices remain the same as for ShowFlag.CameraSafeFrames, as they are effectively the same variable used 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/Engine/Public/ShowFlagsValues.inl:303

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, CameraAspectRatioBars, SFG_Advanced, NSLOCTEXT("UnrealEd", "CameraAspectRatioBarsSF", "Camera Aspect Ratio Bars"))
/** Render safe frames */
SHOWFLAG_FIXED_IN_SHIPPING(1, CameraSafeFrames, SFG_Advanced, NSLOCTEXT("UnrealEd", "CameraSafeFramesSF", "Camera Safe Frames"))
/** Render TextRenderComponents (3D text), for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(TextRender, SFG_Advanced, NSLOCTEXT("UnrealEd", "TextRenderSF", "Render (3D) Text"))
/** Any rendering/buffer clearing  (good for benchmarking and for pausing rendering while the app is not in focus to save cycles). */
SHOWFLAG_ALWAYS_ACCESSIBLE(Rendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "RenderingSF", "Any Rendering")) // do not make it FIXED_IN_SHIPPING, used by Oculus plugin.
/** Show the current mask being used by the highres screenshot capture */
SHOWFLAG_FIXED_IN_SHIPPING(0, HighResScreenshotMask, SFG_Transient, NSLOCTEXT("UnrealEd", "HighResScreenshotMaskSF", "High Res Screenshot Mask"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/EditorViewportClient.cpp:2159

Scope (from outer to inner):

file
function     void FEditorViewportClient::DrawSafeFrames

Source code excerpt:

void FEditorViewportClient::DrawSafeFrames(FViewport& InViewport, FSceneView& View, FCanvas& Canvas)
{
	if (EngineShowFlags.CameraAspectRatioBars || EngineShowFlags.CameraSafeFrames)
	{
		FSlateRect SafeRect;
		if (CalculateEditorConstrainedViewRect(SafeRect, &InViewport, Canvas.GetDPIScale()))
		{
			if (EngineShowFlags.CameraSafeFrames)
			{
				FSlateRect InnerRect = SafeRect.InsetBy(FMargin(0.5f * SafePadding * SafeRect.GetSize().Size()));
				FCanvasBoxItem BoxItem(FVector2D(InnerRect.Left, InnerRect.Top), InnerRect.GetSize());
				BoxItem.SetColor(FLinearColor(0.0f, 0.0f, 0.0f, 0.5f));
				Canvas.DrawItem(BoxItem);
			}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Public/EditorViewportClient.h:1279

Scope (from outer to inner):

file
class        class FEditorViewportClient : public FCommonViewportClient, public FViewElementDrawer, public FGCObject
function     bool IsShowingSafeFrameBoxDisplay

Source code excerpt:

	bool IsShowingSafeFrameBoxDisplay() const
	{
		return EngineShowFlags.CameraSafeFrames == 1;
	}

	/** Get the near clipping plane for this viewport. */
	UNREALED_API float GetNearClipPlane() const;

	/** Override the near clipping plane. Set to a negative value to disable the override. */

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(0, CameraAspectRatioBars, SFG_Advanced, NSLOCTEXT("UnrealEd", "CameraAspectRatioBarsSF", "Camera Aspect Ratio Bars"))
/** Render safe frames */
SHOWFLAG_FIXED_IN_SHIPPING(1, CameraSafeFrames, SFG_Advanced, NSLOCTEXT("UnrealEd", "CameraSafeFramesSF", "Camera Safe Frames"))
/** Render TextRenderComponents (3D text), for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(TextRender, SFG_Advanced, NSLOCTEXT("UnrealEd", "TextRenderSF", "Render (3D) Text"))
/** Any rendering/buffer clearing  (good for benchmarking and for pausing rendering while the app is not in focus to save cycles). */
SHOWFLAG_ALWAYS_ACCESSIBLE(Rendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "RenderingSF", "Any Rendering")) // do not make it FIXED_IN_SHIPPING, used by Oculus plugin.
/** Show the current mask being used by the highres screenshot capture */
SHOWFLAG_FIXED_IN_SHIPPING(0, HighResScreenshotMask, SFG_Transient, NSLOCTEXT("UnrealEd", "HighResScreenshotMaskSF", "High Res Screenshot Mask"))