r.AllowGlobalClipPlane

r.AllowGlobalClipPlane

#Overview

name: r.AllowGlobalClipPlane

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 r.AllowGlobalClipPlane is to enable support for a global clip plane in mesh shaders, which is necessary for planar reflections. This setting variable is primarily used in the rendering system of Unreal Engine 5.

Several Unreal Engine subsystems and modules rely on this setting variable:

  1. Renderer module
  2. Engine module
  3. RenderCore module

The value of this variable is set as a console variable, which means it can be changed at runtime through the console or configuration files. It is initialized with a default value of 0 (disabled).

This variable interacts with other parts of the engine, particularly:

  1. It affects shader compilation and defines (PROJECT_ALLOW_GLOBAL_CLIP_PLANE).
  2. It influences the ability to edit certain properties in SceneCaptureComponent2D.
  3. It impacts the use of mesh shaders in Nanite rendering.
  4. It affects planar reflection rendering decisions.

Developers must be aware of several things when using this variable:

  1. Enabling this feature adds about 15% BasePass GPU cost on PS4.
  2. Changing this variable causes a full shader recompile, which can be time-consuming.
  3. It may not be supported on all platforms, especially those that don’t support clip distance output with mesh shaders.

Best practices when using this variable include:

  1. Only enable it when planar reflections are needed in the project, as it comes with a performance cost.
  2. Be prepared for longer compile times when changing this setting.
  3. Test thoroughly on target platforms to ensure compatibility and acceptable performance.
  4. Consider the interaction with other rendering features and settings, especially on mobile platforms.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/BasePassRendering.cpp:47

Scope: file

Source code excerpt:

// Changing this causes a full shader recompile
static TAutoConsoleVariable<int32> CVarGlobalClipPlane(
	TEXT("r.AllowGlobalClipPlane"),
	0,
	TEXT("Enables mesh shaders to support a global clip plane, needed for planar reflections, which adds about 15% BasePass GPU cost on PS4."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

// Changing this causes a full shader recompile
static TAutoConsoleVariable<int32> CVarVertexFoggingForOpaque(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SceneCaptureComponent.cpp:806

Scope (from outer to inner):

file
function     bool USceneCaptureComponent2D::CanEditChange

Source code excerpt:

		}

		static IConsoleVariable* ClipPlaneCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.AllowGlobalClipPlane"));

		if (PropertyName == GET_MEMBER_NAME_STRING_CHECKED(USceneCaptureComponent2D, bEnableClipPlane))
		{
			return ClipPlaneCVar->GetInt() != 0;
		}

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.AllowGlobalClipPlane"));
		SET_SHADER_DEFINE(Input.Environment, PROJECT_ALLOW_GLOBAL_CLIP_PLANE, CVar ? (CVar->GetInt() != 0) : 0);
	}

	{
		const bool bSupportsClipDistance = FDataDrivenShaderPlatformInfo::GetSupportsClipDistance((EShaderPlatform)Target.Platform);
		SET_SHADER_DEFINE(Input.Environment, PLATFORM_SUPPORTS_CLIP_DISTANCE, bSupportsClipDistance ? 1u : 0u);

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

Scope (from outer to inner):

file
function     static FShaderGlobalDefines FetchShaderGlobalDefines

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.AllowGlobalClipPlane"));
		Ret.PROJECT_ALLOW_GLOBAL_CLIP_PLANE = CVar ? (CVar->GetInt() != 0) : 0;
	}

	{
		if (MaskedInEarlyPass((EShaderPlatform)TargetPlatform))
		{

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.AllowGlobalClipPlane"));
		KeyString += (CVar && CVar->GetInt() != 0) ? TEXT("_ClipP") : TEXT("");
	}

	{
		// Extra data (names, etc)
		KeyString += ShouldEnableExtraShaderData(ShaderFormatName) ? TEXT("_ExtraData") : TEXT("");

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:346

Scope (from outer to inner):

file
function     static bool UseMeshShader

Source code excerpt:


	// Disable mesh shaders if global clip planes are enabled and the platform cannot support MS with clip distance output
	static const auto AllowGlobalClipPlaneVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.AllowGlobalClipPlane"));
	static const bool bAllowGlobalClipPlane = (AllowGlobalClipPlaneVar && AllowGlobalClipPlaneVar->GetValueOnAnyThread() != 0);
	const bool bMSSupportsClipDistance = FDataDrivenShaderPlatformInfo::GetSupportsMeshShadersWithClipDistance(ShaderPlatform);

	// We require tier1 support to utilize primitive attributes
	const bool bSupported = CVarNaniteMeshShaderRasterization.GetValueOnAnyThread() != 0 && GRHISupportsMeshShadersTier1 && (!bAllowGlobalClipPlane || bMSSupportsClipDistance);
	return bSupported;

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

Scope (from outer to inner):

file
function     void FSceneRenderer::OnRenderFinish

Source code excerpt:

		if (Scene->PlanarReflections.Num() > 0)
		{
			static const auto* CVarClipPlane = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.AllowGlobalClipPlane"));
			
			const bool bShouldUseClipPlaneForPlanarReflection = (FeatureLevel > ERHIFeatureLevel::ES3_1 && GetMobilePlanarReflectionMode() != EMobilePlanarReflectionMode::MobilePPRExclusive)
															|| GetMobilePlanarReflectionMode() == EMobilePlanarReflectionMode::Usual;
			
			if (CVarClipPlane && CVarClipPlane->GetValueOnRenderThread() == 0
				&& bShouldUseClipPlaneForPlanarReflection)