ShowFlag.OnScreenDebug

ShowFlag.OnScreenDebug

#Overview

name: ShowFlag.OnScreenDebug

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 ShowFlag.OnScreenDebug is to control the display of on-screen debug information in Unreal Engine 5. This setting variable is primarily used for development and debugging purposes, allowing developers to toggle the visibility of various debug messages and visualizations on the screen during runtime.

This setting variable is utilized by the Unreal Engine’s rendering system, particularly in the Renderer module. It’s also used in the Engine module for controlling debug message display.

The value of this variable is set through the ShowFlags system, which is part of Unreal Engine’s rendering configuration. It can be toggled in real-time, allowing developers to enable or disable on-screen debug information as needed.

The ShowFlag.OnScreenDebug interacts with other variables, notably:

  1. bEnableOnScreenDebugMessages: A global config variable that controls whether on-screen debug messages are enabled.
  2. bEnableOnScreenDebugMessagesDisplay: A transient variable that controls the display of on-screen debug messages during runtime.

Developers should be aware that:

  1. This flag affects various debug visualizations, including streaming debug information and shader print data.
  2. It’s used as a condition for rendering certain debug information, so toggling it can impact performance and visual output during development.
  3. It’s always accessible, even in shipping builds, as indicated by the SHOWFLAG_ALWAYS_ACCESSIBLE macro.

Best practices when using this variable include:

  1. Use it judiciously during development and testing phases.
  2. Ensure it’s disabled in shipping builds to prevent unnecessary performance overhead.
  3. Combine it with other debugging tools and methods for comprehensive debugging.

Regarding the associated variable OnScreenDebug:

The purpose of OnScreenDebug is essentially the same as ShowFlag.OnScreenDebug. It’s used to control the display of on-screen debug information.

This variable is part of the Engine module and is used in conjunction with the ShowFlags system.

The value of OnScreenDebug can be set through the engine configuration or toggled at runtime.

It interacts closely with bEnableOnScreenDebugMessages and bEnableOnScreenDebugMessagesDisplay, which provide more granular control over debug message display.

Developers should be aware that:

  1. This variable is used in various parts of the engine for conditional rendering of debug information.
  2. It’s part of the EngineShowFlags structure, which is widely used throughout the rendering pipeline.

Best practices for using OnScreenDebug include:

  1. Use it in conjunction with other debug tools for comprehensive debugging.
  2. Be mindful of its performance impact, especially when dealing with complex scenes or large amounts of debug data.
  3. Ensure it’s properly managed in different build configurations to avoid unintended debug output in release builds.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(1, CameraImperfections, SFG_PostProcess, NSLOCTEXT("UnrealEd", "CameraImperfectionsSF", "Camera Imperfections"))
/** to allow to disable visualizetexture for some editor rendering (e.g. thumbnail rendering) */
SHOWFLAG_ALWAYS_ACCESSIBLE(OnScreenDebug, SFG_Developer, NSLOCTEXT("UnrealEd", "OnScreenDebugSF", "On Screen Debug"))
/** needed for VMI_Lit_DetailLighting, Whether to override material diffuse and specular with constants, used by the Detail Lighting viewmode. */
SHOWFLAG_FIXED_IN_SHIPPING(0, OverrideDiffuseAndSpecular, SFG_Hidden, NSLOCTEXT("UnrealEd", "OverrideDiffuseAndSpecularSF", "Override Diffuse And Specular"))
/** needed for VMI_LightingOnly, Whether to override material diffuse with constants, used by the Lighting Only viewmode. */
SHOWFLAG_FIXED_IN_SHIPPING(0, LightingOnlyOverride, SFG_Hidden, NSLOCTEXT("UnrealEd", "LightingOnlyOverrideSF", "Lighting Only"))
/** needed for VMI_ReflectionOverride, Whether to override all materials to be smooth, mirror reflections. */
SHOWFLAG_FIXED_IN_SHIPPING(0, ReflectionOverride, SFG_Hidden, NSLOCTEXT("UnrealEd", "ReflectionOverrideSF", "Reflections"))

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

public:

	/** If true, then disable OnScreenDebug messages. Can be toggled in real-time. */
	UPROPERTY(globalconfig)
	uint32 bEnableOnScreenDebugMessages:1;

	/** If true, then disable the display of OnScreenDebug messages (used when running) */
	UPROPERTY(transient)
	uint32 bEnableOnScreenDebugMessagesDisplay:1;

	/** If true, then skip drawing map warnings on screen even in non (UE_BUILD_SHIPPING || UE_BUILD_TEST) builds */
	UPROPERTY(globalconfig)
	uint32 bSuppressMapWarnings:1;

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

Scope: file

Source code excerpt:

SHOWFLAG_FIXED_IN_SHIPPING(1, CameraImperfections, SFG_PostProcess, NSLOCTEXT("UnrealEd", "CameraImperfectionsSF", "Camera Imperfections"))
/** to allow to disable visualizetexture for some editor rendering (e.g. thumbnail rendering) */
SHOWFLAG_ALWAYS_ACCESSIBLE(OnScreenDebug, SFG_Developer, NSLOCTEXT("UnrealEd", "OnScreenDebugSF", "On Screen Debug"))
/** needed for VMI_Lit_DetailLighting, Whether to override material diffuse and specular with constants, used by the Detail Lighting viewmode. */
SHOWFLAG_FIXED_IN_SHIPPING(0, OverrideDiffuseAndSpecular, SFG_Hidden, NSLOCTEXT("UnrealEd", "OverrideDiffuseAndSpecularSF", "Override Diffuse And Specular"))
/** needed for VMI_LightingOnly, Whether to override material diffuse with constants, used by the Lighting Only viewmode. */
SHOWFLAG_FIXED_IN_SHIPPING(0, LightingOnlyOverride, SFG_Hidden, NSLOCTEXT("UnrealEd", "LightingOnlyOverrideSF", "Lighting Only"))
/** needed for VMI_ReflectionOverride, Whether to override all materials to be smooth, mirror reflections. */
SHOWFLAG_FIXED_IN_SHIPPING(0, ReflectionOverride, SFG_Hidden, NSLOCTEXT("UnrealEd", "ReflectionOverrideSF", "Reflections"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessing.cpp:1775

Scope (from outer to inner):

file
function     void AddPostProcessingPasses

Source code excerpt:

		}

		// Piggy back off of OnScreenDebug to avoid having to create a new show flag just for this simple debug visualization. Otherwise it might render into certain thumbnails.
		// In the future it might be worth it to introduce a show flag?
		if (EngineShowFlags.OnScreenDebug)
		{
			UE::SVT::AddStreamingDebugPass(GraphBuilder, View, SceneColor);
		}

		if (ShaderPrint::IsEnabled(View.ShaderPrintData))
		{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:4133

Scope (from outer to inner):

file
function     void FSceneRenderer::OnRenderFinish

Source code excerpt:

	bHasRequestedToggleFreeze = false;

	if(ViewFamily.EngineShowFlags.OnScreenDebug && ViewFamilyTexture)
	{
		for(int32 ViewIndex = 0;ViewIndex < Views.Num();ViewIndex++)
		{
			const FViewInfo& View = Views[ViewIndex];

			if(!View.IsPerspectiveProjection())

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:5562

Scope (from outer to inner):

file
function     static void DisplayInternals

Source code excerpt:

	auto Family = InView.Family;
	// if r.DisplayInternals != 0
	if(Family->EngineShowFlags.OnScreenDebug && Family->DisplayInternalsData.IsValid())
	{
		FRDGTextureRef OutputTexture = GraphBuilder.FindExternalTexture(Family->RenderTarget->GetRenderTargetTexture());
		FScreenPassRenderTarget Output = FScreenPassRenderTarget::CreateViewFamilyOutput(OutputTexture, InView);
		AddDrawCanvasPass(GraphBuilder, RDG_EVENT_NAME("DisplayInternals"), InView, Output, [Family, &InView](FCanvas& Canvas)
		{
			// could be 0