r.CustomDepth.Order

r.CustomDepth.Order

#Overview

name: r.CustomDepth.Order

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.CustomDepth.Order is to control when the CustomDepth (and CustomStencil) pass is rendered in relation to the Base Pass in Unreal Engine’s rendering pipeline.

This setting variable is primarily used by the rendering system, specifically in the custom depth rendering module. It affects the order of rendering passes, which can impact performance and certain rendering features.

The Unreal Engine renderer subsystem relies on this setting variable, as evidenced by its usage in the CustomDepthRendering.cpp file.

The value of this variable is set through a console variable (CVarCustomDepthOrder) with a default value of 2. It can be changed at runtime through the console or configuration files.

The variable interacts with the DBuffer system, which is used for decal rendering. The ordering of the CustomDepth pass relative to the Base Pass can affect the availability of CustomDepth and CustomStencil data for decals.

Developers must be aware that:

  1. The value of this variable affects the rendering pipeline order.
  2. It can impact the availability of CustomDepth and CustomStencil data for decals when using DBuffer.
  3. Changing this value may have performance implications, especially when using AsyncCompute.

Best practices when using this variable include:

  1. Consider the needs of your project’s rendering pipeline when changing this value.
  2. Be aware of the potential impact on decal rendering when using DBuffer.
  3. Test performance with different settings, especially if using AsyncCompute.

Regarding the associated variable CVarCustomDepthOrder:

The purpose of CVarCustomDepthOrder is to provide a runtime-configurable way to control the r.CustomDepth.Order setting.

It is used in the GetCustomDepthPassLocation function to determine the location of the CustomDepth pass in the rendering pipeline.

The value of this variable is set when the console variable is created, with a default value of 2.

It interacts directly with the DBuffer system in determining the CustomDepth pass location.

Developers should be aware that changes to this variable will immediately affect the rendering pipeline order.

Best practices for using CVarCustomDepthOrder include:

  1. Use it for runtime configuration of the CustomDepth pass order.
  2. Consider the implications on rendering performance and feature availability when changing its value.
  3. Ensure that any code relying on the CustomDepth pass order is aware of potential runtime changes to this value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CustomDepthRendering.cpp:13

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarCustomDepthOrder(
	TEXT("r.CustomDepth.Order"),
	2,
	TEXT("When CustomDepth (and CustomStencil) is getting rendered\n")
	TEXT("  0: Before Base Pass (Allows samping in DBuffer pass. Can be more efficient with AsyncCompute.)\n")
	TEXT("  1: After Base Pass\n")
	TEXT("  2: Default (Before Base Pass if DBuffer enabled.)\n"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/HLSLMaterialTranslator.cpp:7478

Scope (from outer to inner):

file
function     void FHLSLMaterialTranslator::UseSceneTextureId

Source code excerpt:

		if (!bSceneTextureSupportsDecal)
		{
			// Note: For DBuffer decals CustomDepth and CustomStencil are not available if r.CustomDepth.Order = 1
			Errorf(TEXT("Decals can only access SceneDepth, CustomDepth, CustomStencil, and WorldNormal."));
		}

		const bool bSceneTextureRequiresSM5 = SceneTextureId == PPI_WorldNormal;
		if (bSceneTextureRequiresSM5)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialExpressionHLSL.cpp:2119

Scope (from outer to inner):

file
function     bool UMaterialExpressionSceneTexture::GenerateHLSLExpression

Source code excerpt:

			if (!bSceneTextureSupportsDecal)
			{
				// Note: For DBuffer decals CustomDepth and CustomStencil are not available if r.CustomDepth.Order = 1
				return Generator.Error(TEXT("Decals can only access SceneDepth, CustomDepth, CustomStencil, and WorldNormal."));
			}
		}

		if (SceneTextureId == PPI_SceneColor && MaterialDomain != MD_Surface)
		{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CustomDepthRendering.cpp:12

Scope: file

Source code excerpt:

#include "Nanite/NaniteComposition.h"

static TAutoConsoleVariable<int32> CVarCustomDepthOrder(
	TEXT("r.CustomDepth.Order"),
	2,
	TEXT("When CustomDepth (and CustomStencil) is getting rendered\n")
	TEXT("  0: Before Base Pass (Allows samping in DBuffer pass. Can be more efficient with AsyncCompute.)\n")
	TEXT("  1: After Base Pass\n")
	TEXT("  2: Default (Before Base Pass if DBuffer enabled.)\n"),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CustomDepthRendering.cpp:50

Scope (from outer to inner):

file
function     ECustomDepthPassLocation GetCustomDepthPassLocation

Source code excerpt:

ECustomDepthPassLocation GetCustomDepthPassLocation(EShaderPlatform Platform)
{
	const int32 CustomDepthOrder = CVarCustomDepthOrder.GetValueOnRenderThread();
	const bool bCustomDepthBeforeBasePase = CustomDepthOrder == 0 || (CustomDepthOrder == 2 && IsUsingDBuffers(Platform));
	return bCustomDepthBeforeBasePase ? ECustomDepthPassLocation::BeforeBasePass : ECustomDepthPassLocation::AfterBasePass;
}

bool IsCustomDepthPassWritingStencil()
{