r.EarlyZPass
r.EarlyZPass
#Overview
name: r.EarlyZPass
The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.
This variable is created as a Console Variable (cvar).
- type:
Var - help:
Whether to use a depth only pass to initialize Z culling for the base pass. Cannot be changed at runtime.\nNote: also look at r.EarlyZPassMovable\n 0: off\n 1: good occluders only: not masked, and large on screen\n 2: all opaque (including masked)\n x: use built in heuristic (default is 3)
It is referenced in 10 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of r.EarlyZPass is to control the early Z-pass in Unreal Engine’s rendering pipeline. The early Z-pass is a depth-only rendering pass used to initialize Z culling for the base pass, which can improve performance by reducing overdraw.
This setting variable is primarily used by the renderer subsystem in Unreal Engine. It’s referenced in the RendererSettings, RendererScene, and SceneRendering modules.
The value of this variable is set through several means:
- It can be configured in the project settings under the Renderer category.
- It can be set via console command using “r.EarlyZPass”.
- It’s initialized with a default value of 3 in the C++ code.
The r.EarlyZPass variable interacts with several other variables, including r.EarlyZPassMovable, r.EarlyZPassOnlyMaterialMasking, and r.BasePassWriteDepthEvenWithFullPrepass. These variables work together to fine-tune the early Z-pass behavior.
Developers should be aware that:
- This setting cannot be changed at runtime.
- It has significant impact on rendering performance and visual quality.
- The optimal setting may vary depending on the specific scene and performance requirements.
Best practices when using this variable include:
- Experiment with different settings to find the best balance between performance and visual quality for your specific project.
- Consider using setting 1 (good occluders only) for scenes with large, opaque objects that can benefit from early occlusion.
- Use setting 2 (all opaque including masked) if your scene has many masked materials that could benefit from early Z testing.
- Monitor performance metrics when changing this setting to ensure it’s providing the desired benefits.
The associated variable EarlyZPass is an enum that corresponds to the r.EarlyZPass console variable. It’s used in the URendererSettings class to expose the early Z-pass option in the project settings UI. The same considerations and best practices apply to this variable as they do to r.EarlyZPass.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:293, section: [IOS DeviceProfile]
- INI Section:
IOS DeviceProfile - Raw value:
0 - Is Array:
False
Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:549, section: [iPadPro DeviceProfile]
- INI Section:
iPadPro DeviceProfile - Raw value:
3 - Is Array:
False
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:770
Scope (from outer to inner):
file
class class URendererSettings : public UDeveloperSettings
Source code excerpt:
UPROPERTY(config, EditAnywhere, Category = Optimizations, meta = (
ConsoleVariable="r.EarlyZPass",DisplayName="Early Z-pass",
ToolTip="Whether to use a depth only pass to initialize Z culling for the base pass."))
TEnumAsByte<EEarlyZPass::Type> EarlyZPass;
UPROPERTY(config, EditAnywhere, Category = Optimizations, meta = (
EditCondition = "EarlyZPass == EEarlyZPass::OpaqueAndMasked",
ConsoleVariable = "r.EarlyZPassOnlyMaterialMasking", DisplayName = "Mask material only in early Z-pass",
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:113
Scope: file
Source code excerpt:
TAutoConsoleVariable<int32> CVarEarlyZPass(
TEXT("r.EarlyZPass"),
3,
TEXT("Whether to use a depth only pass to initialize Z culling for the base pass. Cannot be changed at runtime.\n")
TEXT("Note: also look at r.EarlyZPassMovable\n")
TEXT(" 0: off\n")
TEXT(" 1: good occluders only: not masked, and large on screen\n")
TEXT(" 2: all opaque (including masked)\n")
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp:4941
Scope (from outer to inner):
file
function FRendererModule::FRendererModule
Source code excerpt:
FRendererModule::FRendererModule()
{
static auto EarlyZPassVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.EarlyZPass"));
EarlyZPassVar->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeCVarRequiringRecreateRenderState));
#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
void InitDebugViewModeInterface();
InitDebugViewModeInterface();
#endif // !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
#Associated Variable and Callsites
This variable is associated with another variable named EarlyZPass. They share the same value. See the following C++ source code.
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:772
Scope (from outer to inner):
file
class class URendererSettings : public UDeveloperSettings
Source code excerpt:
ConsoleVariable="r.EarlyZPass",DisplayName="Early Z-pass",
ToolTip="Whether to use a depth only pass to initialize Z culling for the base pass."))
TEnumAsByte<EEarlyZPass::Type> EarlyZPass;
UPROPERTY(config, EditAnywhere, Category = Optimizations, meta = (
EditCondition = "EarlyZPass == EEarlyZPass::OpaqueAndMasked",
ConsoleVariable = "r.EarlyZPassOnlyMaterialMasking", DisplayName = "Mask material only in early Z-pass",
ToolTip = "Whether to compute materials' mask opacity only in early Z pass. Changing this setting requires restarting the editor.",
ConfigRestartRequired = true))
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.h:309
Scope (from outer to inner):
file
class class FDeferredShadingSceneRenderer : public FSceneRenderer
Source code excerpt:
{
public:
/** Defines which objects we want to render in the EarlyZPass. */
FDepthPassInfo DepthPass;
FLumenCardRenderer LumenCardRenderer;
FSceneCullingRenderer SceneCullingRenderer;
#if RHI_RAYTRACING
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:1378
Scope (from outer to inner):
file
function static void UpdateEarlyZPassModeCVarSinkFunction
Source code excerpt:
const int32 AntiAliasingMethod = CVarAntiAliasingMethod->GetValueOnGameThread();
const int32 MSAACount = CVarMSAACount->GetValueOnGameThread();
const int32 EarlyZPass = CVarEarlyZPass.GetValueOnGameThread();
const int32 BasePassWriteDepthEvenWithFullPrepass = CVarBasePassWriteDepthEvenWithFullPrepass.GetValueOnGameThread();
// Switching between MSAA and another AA in forward shading mode requires EarlyZPassMode to update.
if (AntiAliasingMethod != CachedAntiAliasingMethod
|| MSAACount != CachedMSAACount
|| EarlyZPass != CachedEarlyZPass
|| BasePassWriteDepthEvenWithFullPrepass != CachedBasePassWriteDepthEvenWithFullPrepass)
{
for (TObjectIterator<UWorld> It; It; ++It)
{
UWorld* World = *It;
if (World && World->Scene)
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:1398
Scope (from outer to inner):
file
function static void UpdateEarlyZPassModeCVarSinkFunction
Source code excerpt:
CachedAntiAliasingMethod = AntiAliasingMethod;
CachedMSAACount = MSAACount;
CachedEarlyZPass = EarlyZPass;
CachedBasePassWriteDepthEvenWithFullPrepass = BasePassWriteDepthEvenWithFullPrepass;
}
}
static FAutoConsoleVariableSink CVarUpdateEarlyZPassModeSink(FConsoleCommandDelegate::CreateStatic(&UpdateEarlyZPassModeCVarSinkFunction));
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:112
Scope: file
Source code excerpt:
);
TAutoConsoleVariable<int32> CVarEarlyZPass(
TEXT("r.EarlyZPass"),
3,
TEXT("Whether to use a depth only pass to initialize Z culling for the base pass. Cannot be changed at runtime.\n")
TEXT("Note: also look at r.EarlyZPassMovable\n")
TEXT(" 0: off\n")
TEXT(" 1: good occluders only: not masked, and large on screen\n")
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:1373
Scope (from outer to inner):
file
function static void UpdateEarlyZPassModeCVarSinkFunction
Source code excerpt:
static int32 CachedAntiAliasingMethod = CVarAntiAliasingMethod->GetValueOnGameThread();
static int32 CachedMSAACount = CVarMSAACount->GetValueOnGameThread();
static int32 CachedEarlyZPass = CVarEarlyZPass.GetValueOnGameThread();
static int32 CachedBasePassWriteDepthEvenWithFullPrepass = CVarBasePassWriteDepthEvenWithFullPrepass.GetValueOnGameThread();
const int32 AntiAliasingMethod = CVarAntiAliasingMethod->GetValueOnGameThread();
const int32 MSAACount = CVarMSAACount->GetValueOnGameThread();
const int32 EarlyZPass = CVarEarlyZPass.GetValueOnGameThread();
const int32 BasePassWriteDepthEvenWithFullPrepass = CVarBasePassWriteDepthEvenWithFullPrepass.GetValueOnGameThread();
// Switching between MSAA and another AA in forward shading mode requires EarlyZPassMode to update.
if (AntiAliasingMethod != CachedAntiAliasingMethod
|| MSAACount != CachedMSAACount
|| EarlyZPass != CachedEarlyZPass
#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RendererScene.cpp:4672
Scope (from outer to inner):
file
function void FScene::GetEarlyZPassMode
Source code excerpt:
// developer override, good for profiling, can be useful as project setting
{
const int32 CVarValue = CVarEarlyZPass.GetValueOnAnyThread();
switch (CVarValue)
{
case 0: OutZPassMode = DDM_None; break;
case 1: OutZPassMode = DDM_NonMaskedOnly; break;
case 2: OutZPassMode = DDM_AllOccluders; break;