ShowFlag.HighResScreenshotMask

ShowFlag.HighResScreenshotMask

#Overview

name: ShowFlag.HighResScreenshotMask

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShowFlag.HighResScreenshotMask is to control the visibility of the mask used during high-resolution screenshot capture in Unreal Engine 5. This setting is primarily used in the rendering system, specifically for screenshot and capture functionality.

This setting variable is utilized by several Unreal Engine subsystems and modules:

  1. The Engine module, particularly in viewport and client-related code.
  2. The Renderer module, in post-processing functionality.
  3. The LevelEditor module, for high-resolution screenshot UI.
  4. The CustomizableObjectEditor plugin, for customizable object screenshots.

The value of this variable is typically set in the following scenarios:

  1. When opening high-resolution screenshot dialogs (in both LevelEditor and CustomizableObjectEditor).
  2. During the high-resolution screenshot capture process in the viewport.

The associated variable HighResScreenshotMask interacts closely with ShowFlag.HighResScreenshotMask. They share the same value and are used interchangeably in different parts of the codebase.

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

  1. It’s marked as SHOWFLAG_FIXED_IN_SHIPPING, meaning it’s not accessible in shipping builds.
  2. It’s categorized as SFG_Transient, indicating it’s not persistently stored.
  3. It affects the rendering pipeline, particularly in post-processing stages.

Best practices when using this variable include:

  1. Ensure to restore the original value after modifying it for screenshot purposes.
  2. Be cautious when using it in gameplay-critical code, as it’s primarily intended for editor and development use.
  3. Consider the performance implications of enabling the mask visualization, especially in complex scenes.

Regarding the associated variable HighResScreenshotMask:

The purpose of HighResScreenshotMask is identical to ShowFlag.HighResScreenshotMask. It’s used to control the visibility of the high-resolution screenshot mask in various engine components.

This variable is used in the same subsystems and modules as ShowFlag.HighResScreenshotMask, including the Engine, Renderer, and editor-related modules.

The value is typically set and accessed through the EngineShowFlags struct, often via ViewportClient or FViewInfo instances.

Developers should be aware that this variable directly affects rendering behavior and should be used carefully, especially in performance-sensitive contexts.

Best practices for HighResScreenshotMask align with those of ShowFlag.HighResScreenshotMask, emphasizing the need to manage its state properly and consider its impact on rendering performance.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

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"))
/** Distortion of output for HMD devices, SHOWFLAG_ALWAYS_ACCESSIBLE for now because USceneCaptureComponent needs that */
SHOWFLAG_ALWAYS_ACCESSIBLE(HMDDistortion, SFG_PostProcess, NSLOCTEXT("UnrealEd", "HMDDistortionSF", "HMD Distortion"))
/** Whether to render in stereoscopic 3d, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's used by StereoRendering */
SHOWFLAG_ALWAYS_ACCESSIBLE(StereoRendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "StereoRenderingSF", "Stereoscopic Rendering"))
/** Show objects even if they should be distance culled, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceCulledPrimitives, SFG_Hidden, NSLOCTEXT("UnrealEd", "DistanceCulledPrimitivesSF", "Distance Culled Primitives"))

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Mutable/Source/CustomizableObjectEditor/Private/MuCOE/SCustomizableObjectHighresScreenshot.cpp:411

Scope (from outer to inner):

file
function     TWeakPtr<class SWindow> SCustomizableObjectHighresScreenshot::OpenDialog

Source code excerpt:

		if (InSceneViewport.IsValid())
		{
			bMaskVisualizationWasEnabled = InSceneViewport->GetClient()->GetEngineShowFlags()->HighResScreenshotMask;
			InSceneViewport->GetClient()->GetEngineShowFlags()->SetHighResScreenshotMask(Config.bMaskEnabled);
		}
	}

	return CurrentWindow;
}

#Loc: <Workspace>/Engine/Source/Editor/LevelEditor/Private/HighResScreenshotUI.cpp:373

Scope (from outer to inner):

file
function     TWeakPtr<class SWindow> SHighResScreenshotDialog::OpenDialog

Source code excerpt:

		if (InViewport.IsValid())
		{
			bMaskVisualizationWasEnabled = InViewport->GetClient()->GetEngineShowFlags()->HighResScreenshotMask;
			InViewport->GetClient()->GetEngineShowFlags()->SetHighResScreenshotMask(Config.bMaskEnabled);
		}
	}

	return CurrentWindow;
}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealClient.cpp:1436

Scope (from outer to inner):

file
function     void FViewport::HighResScreenshot

Source code excerpt:

	BeginInitResource(DummyViewport);

	bool MaskShowFlagBackup = ViewportClient->GetEngineShowFlags()->HighResScreenshotMask;
	const auto MotionBlurShowFlagBackup = ViewportClient->GetEngineShowFlags()->MotionBlur;

	ViewportClient->GetEngineShowFlags()->SetHighResScreenshotMask(GetHighResScreenshotConfig().bMaskEnabled);
	ViewportClient->GetEngineShowFlags()->SetMotionBlur(false);

	// Forcing 128-bit rendering pipeline

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

Scope: file

Source code excerpt:

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"))
/** Distortion of output for HMD devices, SHOWFLAG_ALWAYS_ACCESSIBLE for now because USceneCaptureComponent needs that */
SHOWFLAG_ALWAYS_ACCESSIBLE(HMDDistortion, SFG_PostProcess, NSLOCTEXT("UnrealEd", "HMDDistortionSF", "HMD Distortion"))
/** Whether to render in stereoscopic 3d, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's used by StereoRendering */
SHOWFLAG_ALWAYS_ACCESSIBLE(StereoRendering, SFG_Hidden, NSLOCTEXT("UnrealEd", "StereoRenderingSF", "Stereoscopic Rendering"))
/** Show objects even if they should be distance culled, for now SHOWFLAG_ALWAYS_ACCESSIBLE because it's exposed in SceneCapture */
SHOWFLAG_ALWAYS_ACCESSIBLE(DistanceCulledPrimitives, SFG_Hidden, NSLOCTEXT("UnrealEd", "DistanceCulledPrimitivesSF", "Distance Culled Primitives"))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessMaterial.cpp:1028

Scope (from outer to inner):

file
function     bool IsHighResolutionScreenshotMaskEnabled

Source code excerpt:

bool IsHighResolutionScreenshotMaskEnabled(const FViewInfo& View)
{
	return View.Family->EngineShowFlags.HighResScreenshotMask || View.FinalPostProcessSettings.HighResScreenshotCaptureRegionMaterial;
}

bool IsPathTracingVarianceTextureRequiredInPostProcessMaterial(const FViewInfo& View)
{
	// query the post process material to check if any variance texture has been used
	bool bIsPathTracingVarianceTextureRequired = false;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessMaterial.cpp:1112

Scope (from outer to inner):

file
function     FScreenPassTexture AddHighResolutionScreenshotMaskPass

Source code excerpt:

	static_assert(UE_ARRAY_COUNT(PassNames) == static_cast<uint32>(EPass::MAX), "Pass names array doesn't match pass enum");

	const bool bHighResScreenshotMask = View.Family->EngineShowFlags.HighResScreenshotMask != 0;

	TOverridePassSequence<EPass> PassSequence(Inputs.OverrideOutput);
	PassSequence.SetEnabled(EPass::Material, bHighResScreenshotMask && Inputs.Material != nullptr);
	PassSequence.SetEnabled(EPass::MaskMaterial, bHighResScreenshotMask && Inputs.MaskMaterial != nullptr && GIsHighResScreenshot);
	PassSequence.SetEnabled(EPass::CaptureRegionMaterial, Inputs.CaptureRegionMaterial != nullptr);
	PassSequence.Finalize();