r.DebugSafeZone.TitleRatio

r.DebugSafeZone.TitleRatio

#Overview

name: r.DebugSafeZone.TitleRatio

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DebugSafeZone.TitleRatio is to control the safe zone ratio for debugging and testing purposes in Unreal Engine 5. It is primarily used for simulating safe zones on platforms that don’t have a defined safe zone, allowing developers to test how their UI and content will appear within different safe zone constraints.

This setting variable is mainly utilized by the rendering system and the UI system in Unreal Engine. It is referenced in the following subsystems and modules:

  1. UnrealEd: Used in the Level Editor Play Settings for customizing safe zones in the editor.
  2. ApplicationCore: Defined as a console variable in the generic application implementation.
  3. UMG (Unreal Motion Graphics): Referenced in the SafeZone component for UI layout purposes.

The value of this variable is set through the console or configuration files. It can be modified at runtime using console commands, such as “r.DebugSafeZone.TitleRatio 0.96”.

This variable interacts with other safe zone-related variables, such as r.DebugActionZone.ActionRatio and r.DebugSafeZone.Mode. It also affects the behavior of the PIESafeZoneOverride in the Level Editor Play Settings.

Developers should be aware of the following when using this variable:

  1. It affects the safe zone calculations in the editor and during gameplay.
  2. Changes to this value can impact UI layout and visibility of on-screen elements.
  3. It’s primarily intended for debugging and testing purposes, not for shipping builds.

Best practices when using this variable include:

  1. Use it in conjunction with other safe zone debugging tools to thoroughly test UI layouts.
  2. Reset the value to 1.0 (default) when not actively testing safe zones to avoid unintended effects.
  3. Consider using it alongside r.DebugSafeZone.Mode to visualize the safe zone boundaries.
  4. Be cautious when modifying this value in shipping builds, as it may affect the user experience across different devices.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Classes/Settings/LevelEditorPlaySettings.h:599

Scope (from outer to inner):

file
class        class ULevelEditorPlaySettings : public UObject

Source code excerpt:


#if WITH_EDITOR
	// Recalculates and broadcasts safe zone size changes based on device to emulate and r.DebugSafeZone.TitleRatio values.
	UNREALED_API void UpdateCustomSafeZones();
#endif

	UNREALED_API FMargin CalculateCustomUnsafeZones(TArray<FVector2D>& CustomSafeZoneStarts, TArray<FVector2D>& CustomSafeZoneDimensions, FString& DeviceType, FVector2D PreviewSize);
	UNREALED_API FMargin FlipCustomUnsafeZones(TArray<FVector2D>& CustomSafeZoneStarts, TArray<FVector2D>& CustomSafeZoneDimensions, FString& DeviceType, FVector2D PreviewSize);
	UNREALED_API void RescaleForMobilePreview(const class UDeviceProfile* DeviceProfile, int32 &PreviewWidth, int32 &PreviewHeight, float &ScaleFactor);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/LevelEditorPlaySettingsCustomization.cpp:700

Scope (from outer to inner):

file
function     FText FLevelEditorPlaySettingsCustomization::GetPreviewTextToolTipText

Source code excerpt:

	if (FDisplayMetrics::GetDebugTitleSafeZoneRatio() < 1.0f)
	{
		return LOCTEXT("SafeZoneSetFromRatioCvarToolTip", "Uniform Safe Zone was set from cvar (r.DebugSafeZone.TitleRatio).");
	}

	const ULevelEditorPlaySettings* LevelEditorPlaySettings = GetDefault<ULevelEditorPlaySettings>();
	if (!LevelEditorPlaySettings->DeviceToEmulate.IsEmpty() && !LevelEditorPlaySettings->PIESafeZoneOverride.GetDesiredSize().IsZero() )
	{
		FMargin PIESafeZoneOverride = LevelEditorPlaySettings->PIESafeZoneOverride;

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/LevelEditorPlaySettingsCustomization.h:81

Scope (from outer to inner):

file
class        class SScreenResolutionCustomization : public SCompoundWidget

Source code excerpt:


	// Handles swapping the current aspect ratio.
	// Also will set a custom safe zone matching the device profile, if r.DebugSafeZone.TitleRatio is set to 1.0
	FReply HandleSwapAspectRatioClicked();

private:

	// Handles selecting a common screen resolution.
	// Also will set a custom safe zone matching the device profile, if r.DebugSafeZone.TitleRatio is set to 1.0
	void HandleCommonResolutionSelected( const FPlayScreenResolution Resolution );

	const FSlateBrush* GetAspectRatioSwitchImage() const;

	void OnSizeChanged();

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/SettingsClasses.cpp:636

Scope (from outer to inner):

file
function     void ULevelEditorPlaySettings::UpdateCustomSafeZones

Source code excerpt:

	const bool bResetCustomSafeZone = FDisplayMetrics::GetDebugTitleSafeZoneRatio() < 1.f;

	// Prefer to use r.DebugSafeZone.TitleRatio if it is set
	if (bResetCustomSafeZone)
	{
		PIESafeZoneOverride = FMargin();
	}
	else
	{

#Loc: <Workspace>/Engine/Source/Runtime/ApplicationCore/Private/GenericPlatform/GenericApplication.cpp:93

Scope (from outer to inner):

file
function     FSafeZoneConsoleVariables

Source code excerpt:

	FSafeZoneConsoleVariables()
		: DebugSafeZoneRatioCVar(
			TEXT("r.DebugSafeZone.TitleRatio"),
			GDebugSafeZoneRatio,
			TEXT("The safe zone ratio that will be returned by FDisplayMetrics::GetDisplayMetrics on platforms that don't have a defined safe zone (0..1)\n")
			TEXT(" default: 1.0"))
		, DebugActionZoneRatioCVar(
			TEXT("r.DebugActionZone.ActionRatio"),
			GDebugActionZoneRatio,

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

Scope: file

Source code excerpt:

 * 
 * Useful testing console commands to help, simulate the safe zone on PC,
 *   r.DebugSafeZone.TitleRatio 0.96
 *   r.DebugActionZone.ActionRatio 0.96
 * 
 * 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