r.EarlyZPassOnlyMaterialMasking

r.EarlyZPassOnlyMaterialMasking

#Overview

name: r.EarlyZPassOnlyMaterialMasking

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.EarlyZPassOnlyMaterialMasking is to control whether materials’ mask opacity is computed only in the early Z pass of the rendering pipeline. This setting is specifically related to the rendering system in Unreal Engine 5.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, as evidenced by its declaration in the RendererScene.cpp file. It also has implications for the RenderCore module, as seen in the RenderUtils.cpp file.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 0 and can be changed at runtime, although changing it requires restarting the editor due to its impact on shader compilation.

The associated variable CVarEarlyZPassOnlyMaterialMasking interacts directly with r.EarlyZPassOnlyMaterialMasking. They share the same value and are used interchangeably in the code.

Developers must be aware of several important points when using this variable:

  1. Changing this setting requires restarting the editor to recompile shaders.
  2. It only takes effect when r.EarlyZPass == 2 and r.EarlyZPassMovable == 1.
  3. It affects the BasePassPixelShader.usf file, which is crucial for the rendering pipeline.
  4. The variable is marked as read-only and render thread safe, indicating it shouldn’t be modified during gameplay.

Best practices when using this variable include:

  1. Only modify it when necessary and understand its implications on rendering performance and visual quality.
  2. Ensure that the prerequisites (r.EarlyZPass and r.EarlyZPassMovable) are set correctly before enabling this feature.
  3. Test thoroughly after changing this setting, as it can significantly impact the rendering pipeline.
  4. Be cautious when using it in mobile platforms, as the behavior differs from non-mobile platforms.

Regarding the associated variable CVarEarlyZPassOnlyMaterialMasking:

This is the actual console variable object that represents r.EarlyZPassOnlyMaterialMasking in the code. It’s used to retrieve the current value of the setting and to determine whether the early Z pass should only compute material masking. The MaskedInEarlyPass function in RenderUtils.cpp uses this variable to decide whether to perform material masking in the early Z pass for non-mobile platforms.

When working with CVarEarlyZPassOnlyMaterialMasking, developers should:

  1. Use it to query the current state of the r.EarlyZPassOnlyMaterialMasking setting.
  2. Be aware that it’s platform-dependent, with different behavior for mobile and non-mobile platforms.
  3. Consider caching its value for performance reasons if it’s queried frequently.
  4. Remember that it’s a read-only variable, so attempts to modify it directly may fail or lead to unexpected behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:105

Scope: file

Source code excerpt:

/** Affects BasePassPixelShader.usf so must relaunch editor to recompile shaders. */
static TAutoConsoleVariable<int32> CVarEarlyZPassOnlyMaterialMasking(
	TEXT("r.EarlyZPassOnlyMaterialMasking"),
	0,
	TEXT("Whether to compute materials' mask opacity only in early Z pass. Changing this setting requires restarting the editor.\n")
	TEXT("Note: Needs r.EarlyZPass == 2 && r.EarlyZPassMovable == 1"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:508

Scope (from outer to inner):

file
function     bool MaskedInEarlyPass

Source code excerpt:

RENDERCORE_API bool MaskedInEarlyPass(const FStaticShaderPlatform Platform)
{
	static IConsoleVariable* CVarEarlyZPassOnlyMaterialMasking = IConsoleManager::Get().FindConsoleVariable(TEXT("r.EarlyZPassOnlyMaterialMasking"));
	if (IsMobilePlatform(Platform))
	{
		return FReadOnlyCVARCache::MobileEarlyZPass(Platform) == 2 || MobileUsesFullDepthPrepass(Platform);
	}
	else
	{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:508

Scope (from outer to inner):

file
function     bool MaskedInEarlyPass

Source code excerpt:

RENDERCORE_API bool MaskedInEarlyPass(const FStaticShaderPlatform Platform)
{
	static IConsoleVariable* CVarEarlyZPassOnlyMaterialMasking = IConsoleManager::Get().FindConsoleVariable(TEXT("r.EarlyZPassOnlyMaterialMasking"));
	if (IsMobilePlatform(Platform))
	{
		return FReadOnlyCVARCache::MobileEarlyZPass(Platform) == 2 || MobileUsesFullDepthPrepass(Platform);
	}
	else
	{
		return (CVarEarlyZPassOnlyMaterialMasking && CVarEarlyZPassOnlyMaterialMasking->GetInt() != 0);
	}
}

RENDERCORE_API bool AllowPixelDepthOffset(const FStaticShaderPlatform Platform)
{
	if (IsMobilePlatform(Platform))

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:104

Scope: file

Source code excerpt:


/** Affects BasePassPixelShader.usf so must relaunch editor to recompile shaders. */
static TAutoConsoleVariable<int32> CVarEarlyZPassOnlyMaterialMasking(
	TEXT("r.EarlyZPassOnlyMaterialMasking"),
	0,
	TEXT("Whether to compute materials' mask opacity only in early Z pass. Changing this setting requires restarting the editor.\n")
	TEXT("Note: Needs r.EarlyZPass == 2 && r.EarlyZPassMovable == 1"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);