r.PostProcessing.PropagateAlpha

r.PostProcessing.PropagateAlpha

#Overview

name: r.PostProcessing.PropagateAlpha

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

It is referenced in 18 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PostProcessing.PropagateAlpha is to control alpha channel support in post-processing within Unreal Engine’s rendering system. It allows developers to enable or disable the propagation of alpha values through the post-processing pipeline.

This setting variable is primarily used by the Unreal Engine’s rendering system, specifically in the post-processing pipeline. It affects various subsystems and modules, including:

  1. The core rendering module
  2. Movie Render Pipeline
  3. Media IO Framework
  4. OpenXR plugin
  5. Display Cluster plugin
  6. Various editor tools and modes

The value of this variable is set through the console variable system. It can be set to: 0: Disabled (default) 1: Enabled in linear color space 2: Enabled through the tonemapper (for specific broadcasting hardware)

Several other variables interact with r.PostProcessing.PropagateAlpha:

  1. It’s directly associated with CVarPostProcessingPropagateAlpha.
  2. It affects the behavior of bAccumulatorIncludesAlpha in UMoviePipelineDeferredPassBase.
  3. It interacts with r.Mobile.PropagateAlpha for mobile platforms.

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

  1. Enabling alpha propagation (1 or 2) can impact performance, adding about 30% cost to accumulation.
  2. Some features, like VR scouting mode, require this setting to be 0.
  3. It affects shader compilation and may require engine restarts when changed.
  4. It’s crucial for certain output scenarios, like broadcasting or movie rendering with alpha channel support.

Best practices when using this variable include:

  1. Keep it disabled (0) by default unless alpha channel support is specifically needed.
  2. When enabling, prefer setting 1 (linear color space) over 2 (through tonemapper) unless working with specific broadcasting hardware.
  3. Be aware of the performance impact and only enable when necessary.
  4. Coordinate its use with other alpha-related settings, especially on mobile platforms.

Regarding the associated variable CVarPostProcessingPropagateAlpha:

The purpose of CVarPostProcessingPropagateAlpha is to serve as the actual console variable implementation of r.PostProcessing.PropagateAlpha. It’s defined in the rendering module and controls the same functionality as r.PostProcessing.PropagateAlpha.

This variable is used internally by the engine to query the current state of alpha propagation in post-processing. It’s accessed through the console variable system and shares the same values and meanings as r.PostProcessing.PropagateAlpha.

Developers should generally interact with r.PostProcessing.PropagateAlpha rather than CVarPostProcessingPropagateAlpha directly, as the former is the intended interface for this functionality.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<int32> CVarPostProcessingPropagateAlpha(
	TEXT("r.PostProcessing.PropagateAlpha"),
	0,
	TEXT("0 to disable scene alpha channel support in the post processing.\n")
	TEXT(" 0: disabled (default);\n")
	TEXT(" 1: enabled in linear color space;\n")
	TEXT(" 2: same as 1, but also enable it through the tonemapper. Compositing after the tonemapper is incorrect, as their is no meaning to tonemap the alpha channel. This is only meant to be use exclusively for broadcasting hardware that does not support linear color space compositing and tonemapping."),
	ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Plugins/Experimental/Avalanche/Source/AvalancheMediaEditor/Private/Rundown/Preview/SAvaRundownPagePreview.cpp:302

Scope (from outer to inner):

file
function     void SAvaRundownPagePreview::HandleCheckerboardActionExecute

Source code excerpt:

	if (bShowCheckerBoard)
	{
		const IConsoleVariable* PropagateAlphaCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha"));
		if (PropagateAlphaCVar && PropagateAlphaCVar->GetInt() != 2)
		{
			const FText NotificationText = LOCTEXT("AlphaSupport",
				"An output requested Alpha Support but the required project setting is not enabled!\n"
				"Go to Project Settings > Rendering > PostProcessing > 'Enable Alpha Channel Support in Post Processing' and set it to 'Allow through tonemapper'.");

#Loc: <Workspace>/Engine/Plugins/Experimental/VirtualScouting/Source/VirtualScoutingEditor/Private/VPScoutingMode.cpp:104

Scope (from outer to inner):

file
function     bool UVPScoutingMode::ValidateSettings

Source code excerpt:


	IConsoleManager& ConsoleMgr = IConsoleManager::Get();
	if (IConsoleVariable* PropagateAlpha = ConsoleMgr.FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha")))
	{
		if (PropagateAlpha->GetInt() != 0)
		{
			InvalidSettingNotification(LOCTEXT("InvalidCvarPropagateAlpha", "r.PostProcessing.PropagateAlpha must be set to 0 (and requires an engine restart)"));
			bSettingsValid = false;
		}
	}

	return bSettingsValid;
}

#Loc: <Workspace>/Engine/Plugins/Experimental/XRCreativeFramework/Source/XRCreativeEditor/Private/XRCreativeVREditorMode.cpp:284

Scope (from outer to inner):

file
function     bool UXRCreativeVREditorMode::ValidateSettings

Source code excerpt:


	IConsoleManager& ConsoleMgr = IConsoleManager::Get();
	if (IConsoleVariable* PropagateAlpha = ConsoleMgr.FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha")))
	{
		if (PropagateAlpha->GetInt() != 0)
		{
			InvalidSettingNotification(LOCTEXT("InvalidCvarPropagateAlpha", "r.PostProcessing.PropagateAlpha must be set to 0 (and requires an engine restart)"));
			bSettingsValid = false;
		}
	}

	return bSettingsValid;
}

#Loc: <Workspace>/Engine/Plugins/Media/AppleProResMedia/Source/AppleProResMedia/Private/AppleProResEncoderProtocol.cpp:570

Scope (from outer to inner):

file
function     bool UAppleProResEncoderProtocol::HasAlpha

Source code excerpt:

bool UAppleProResEncoderProtocol::HasAlpha() const
{
	static const auto CVarPropagateAlpha = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
	const EAlphaChannelMode::Type PropagateAlpha = EAlphaChannelMode::FromInt(CVarPropagateAlpha->GetValueOnAnyThread());
	return EAlphaChannelMode::AllowThroughTonemapper == PropagateAlpha;
}

void UAppleProResEncoderProtocol::ConvertFColorToRGBA4444(const TArray<FColor>& InColorbuffer)
{

#Loc: <Workspace>/Engine/Plugins/Media/MediaIOFramework/Source/MediaIOCore/Private/FileMediaOutput.cpp:85

Scope (from outer to inner):

file
function     EMediaCaptureConversionOperation UFileMediaOutput::GetConversionOperation

Source code excerpt:

	{
		// We invert alpha only when alpha channel as valid data when used with "passthrough tone mapper" or using a render target, otherwise we force it to 1.0f.
		static const auto CVarPropagateAlpha = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
		EAlphaChannelMode::Type PropagateAlpha = EAlphaChannelMode::FromInt(CVarPropagateAlpha->GetValueOnAnyThread());
		if ((PropagateAlpha == EAlphaChannelMode::AllowThroughTonemapper) || (InSourceType == EMediaCaptureSourceType::RENDER_TARGET))
		{
			return bInvertAlpha ? EMediaCaptureConversionOperation::INVERT_ALPHA :
				EMediaCaptureConversionOperation::NONE;
		}

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineCore/Private/MoviePipeline.cpp:107

Scope (from outer to inner):

file
function     void UMoviePipeline::ValidateSequenceAndSettings

Source code excerpt:

	// Check to see if they're trying to output alpha and don't have the required project setting set.
	{
		IConsoleVariable* TonemapAlphaCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha"));
		check(TonemapAlphaCVar);

		TArray<UMoviePipelineRenderPass*> OutputSettings = GetPipelinePrimaryConfig()->FindSettings<UMoviePipelineRenderPass>();
		bool bAnyOutputWantsAlpha = false;

		for (const UMoviePipelineRenderPass* Output : OutputSettings)

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineRenderPasses/Public/MoviePipelineDeferredPasses.h:85

Scope (from outer to inner):

file
function     class MOVIERENDERPIPELINERENDERPASSES_API UMoviePipelineDeferredPassBase : public UMoviePipelineImagePassBase { GENERATED_BODY

Source code excerpt:

public:
	/**
	* Should multiple temporal/spatial samples accumulate the alpha channel? This requires r.PostProcessing.PropagateAlpha
	* to be set to 1 or 2 (see "Enable Alpha Channel Support in Post Processing" under Project Settings > Rendering). This adds
	* ~30% cost to the accumulation so you should not enable it unless necessary. You must delete both the sky and fog to ensure
	* that they do not make all pixels opaque.
	*/
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Settings")
	bool bAccumulatorIncludesAlpha;

	/**
	* Certain passes don't support post-processing effects that blend pixels together. These include effects like
	* Depth of Field, Temporal Anti-Aliasing, Motion Blur and chromattic abberation. When these post processing
	* effects are used then each final output pixel is composed of the influence of many other pixels which is

#Loc: <Workspace>/Engine/Plugins/Runtime/OpenXR/Source/OpenXRHMD/Private/OpenXRHMD.cpp:1506

Scope (from outer to inner):

file
function     bool FOpenXRHMD::ReconfigureForShaderPlatform

Source code excerpt:

	bIsMobileMultiViewEnabled = Aspects.IsMobileMultiViewEnabled();

	static const auto CVarPropagateAlpha = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
	bProjectionLayerAlphaEnabled = !IsMobilePlatform(NewShaderPlatform) && CVarPropagateAlpha->GetValueOnAnyThread() != 0;

	ConfiguredShaderPlatform = NewShaderPlatform;

	UE_LOG(LogHMD, Log, TEXT("HMD configured for shader platform %s, bIsMobileMultiViewEnabled=%d, bProjectionLayerAlphaEnabled=%d"),
		*LexToString(ConfiguredShaderPlatform),

#Loc: <Workspace>/Engine/Plugins/Runtime/nDisplay/Source/DisplayCluster/Private/Render/Viewport/Configuration/DisplayClusterViewportConfigurationHelpers_RenderFrameSettings.cpp:86

Scope (from outer to inner):

file
function     EDisplayClusterRenderFrameAlphaChannelCaptureMode FDisplayClusterViewportConfigurationHelpers_RenderFrameSettings::GetAlphaChannelCaptureMode

Source code excerpt:

	ECVarDisplayClusterAlphaChannelCaptureMode AlphaChannelCaptureMode = (ECVarDisplayClusterAlphaChannelCaptureMode)FMath::Clamp(GDisplayClusterAlphaChannelCaptureMode, 0, (int32)ECVarDisplayClusterAlphaChannelCaptureMode::COUNT - 1);

	static const auto CVarPropagateAlpha = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
	const EAlphaChannelMode::Type PropagateAlpha = EAlphaChannelMode::FromInt(CVarPropagateAlpha->GetValueOnGameThread());
	const bool bAllowThroughTonemapper = PropagateAlpha == EAlphaChannelMode::AllowThroughTonemapper;

	switch (AlphaChannelCaptureMode)
	{
	case ECVarDisplayClusterAlphaChannelCaptureMode::ThroughTonemapper:

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/PlayLevel.cpp:3330

Scope (from outer to inner):

file
function     TSharedRef<SPIEViewport> UEditorEngine::GeneratePIEViewportWindow

Source code excerpt:

	bool bEnableStereoRendering = bVRPreview;

	static const auto CVarPropagateAlpha = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
	const EAlphaChannelMode::Type PropagateAlpha = EAlphaChannelMode::FromInt(CVarPropagateAlpha->GetValueOnGameThread());
	const bool bIgnoreTextureAlpha = (PropagateAlpha != EAlphaChannelMode::AllowThroughTonemapper);

	TSharedRef<SPIEViewport> PieViewportWidget =
		SNew(SPIEViewport)
		.RenderDirectlyToWindow(bRenderDirectlyToWindow)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:8583

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha"));
		int32 PropagateAlpha = CVar->GetInt();

		if (bIsMobilePlatform)
		{
			static FShaderPlatformCachedIniValue<int32> MobilePropagateAlphaIniValue(TEXT("r.Mobile.PropagateAlpha"));
			int MobilePropagateAlphaIniValueInt = MobilePropagateAlphaIniValue.Get((EShaderPlatform)ShaderPlatform);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderGenerationUtil.cpp:419

Scope (from outer to inner):

file
function     static FShaderGlobalDefines FetchShaderGlobalDefines

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.PostProcessing.PropagateAlpha"));
		int32 PropagateAlpha = CVar->GetInt();
		if (PropagateAlpha < 0 || PropagateAlpha > 2)
		{
			PropagateAlpha = 0;
		}
		Ret.POST_PROCESS_ALPHA = PropagateAlpha != 0;

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:1910

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

		else
		{
			static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.PostProcessing.PropagateAlpha"));
			if (CVar)
			{
				PropagateAlphaType = CVar->GetValueOnAnyThread();
			}
		}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HairStrands/HairStrandsComposition.cpp:98

Scope (from outer to inner):

file
function     void InternalCommonDrawPass
lambda-function

Source code excerpt:

			else
			{
				// Alpha usage/output is controlled with r.PostProcessing.PropagateAlpha. The value are:
				// 0: disabled(default);
				// 1: enabled in linear color space;
				// 2: same as 1, but also enable it through the tonemapper.
				//
				// When enable (PorpagateAlpha is set to 1 or 2), the alpha value means:
				// 0: valid pixel

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/VisualizeTemporalUpscaler.cpp:279

Scope (from outer to inner):

file
function     FScreenPassTexture AddVisualizeTemporalUpscalerPass
lambda-function

Source code excerpt:

			// Display alpha support
			{
				FString Text = bSupportsAlpha ? TEXT("r.PostProcessing.PropagateAlpha=true") : TEXT("r.PostProcessing.PropagateAlpha=false");
				if (Inputs.TAAConfig == EMainTAAPassConfig::ThirdParty)
				{
					Text = TEXT("Unknown");
				}
				QuickDrawSummary(/* Location = */ 4, TEXT("Support Alpha: ") + Text);
			}

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarPostProcessingPropagateAlpha(
	TEXT("r.PostProcessing.PropagateAlpha"),
	0,
	TEXT("0 to disable scene alpha channel support in the post processing.\n")
	TEXT(" 0: disabled (default);\n")
	TEXT(" 1: enabled in linear color space;\n")
	TEXT(" 2: same as 1, but also enable it through the tonemapper. Compositing after the tonemapper is incorrect, as their is no meaning to tonemap the alpha channel. This is only meant to be use exclusively for broadcasting hardware that does not support linear color space compositing and tonemapping."),

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

Scope (from outer to inner):

file
function     bool IsPostProcessingWithAlphaChannelSupported

Source code excerpt:

bool IsPostProcessingWithAlphaChannelSupported()
{
	return CVarPostProcessingPropagateAlpha.GetValueOnAnyThread() != 0;
}

#if DEBUG_POST_PROCESS_VOLUME_ENABLE
FScreenPassTexture AddFinalPostProcessDebugInfoPasses(FRDGBuilder& GraphBuilder, const FViewInfo& View, FScreenPassTexture& ScreenPassSceneColor);
#endif