r.CustomDepthEnableFastClear

r.CustomDepthEnableFastClear

#Overview

name: r.CustomDepthEnableFastClear

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.CustomDepthEnableFastClear is to control the fast clearing of the custom depth buffer in Unreal Engine’s rendering system. It enables or disables the use of HTile (Hierarchical Tile) optimization for the custom depth buffer.

This setting variable is primarily used in the rendering system of Unreal Engine, specifically in the custom depth rendering module. Based on the callsites, it’s evident that the Renderer module relies on this variable.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of false, meaning fast clearing is disabled by default.

The associated variable CVarCustomDepthEnableFastClear directly interacts with r.CustomDepthEnableFastClear. They share the same value and purpose.

Developers must be aware that enabling this variable can potentially improve rendering performance by allowing faster clearing of the custom depth buffer. However, it may not be suitable for all scenarios or hardware configurations.

Best practices when using this variable include:

  1. Testing the performance impact on target hardware before enabling it in production.
  2. Considering the trade-offs between potential performance gains and any visual artifacts that might occur.
  3. Using it in conjunction with other custom depth rendering settings for optimal results.

Regarding the associated variable CVarCustomDepthEnableFastClear:

The purpose of CVarCustomDepthEnableFastClear is identical to r.CustomDepthEnableFastClear. It’s the actual console variable implementation that controls the fast clearing of the custom depth buffer.

This variable is used in the Renderer module, specifically in the custom depth rendering system.

Its value is set when the engine initializes the console variables, with a default value of false.

CVarCustomDepthEnableFastClear directly interacts with the r.CustomDepthEnableFastClear setting. They are essentially the same variable, with CVarCustomDepthEnableFastClear being the internal representation.

Developers should be aware that this variable is accessed on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarCustomDepthEnableFastClear include:

  1. Accessing its value using GetValueOnRenderThread() when in render thread context.
  2. Not modifying its value directly, but rather using the console command system to change r.CustomDepthEnableFastClear.
  3. Considering its impact on custom depth buffer creation and clearing operations when optimizing rendering performance.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarCustomDepthEnableFastClear(
	TEXT("r.CustomDepthEnableFastClear"), false,
	TEXT("Enable HTile on the custom depth buffer (default:false).\n"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOPrecacheCustomDepth(
	TEXT("r.PSOPrecache.CustomDepth"),
	1,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<bool> CVarCustomDepthEnableFastClear(
	TEXT("r.CustomDepthEnableFastClear"), false,
	TEXT("Enable HTile on the custom depth buffer (default:false).\n"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOPrecacheCustomDepth(
	TEXT("r.PSOPrecache.CustomDepth"),

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

Scope (from outer to inner):

file
function     FCustomDepthTextures FCustomDepthTextures::Create

Source code excerpt:

		CreateFlags |= TexCreate_UAV;
	}
	else if (!CVarCustomDepthEnableFastClear.GetValueOnRenderThread())
	{
		CreateFlags |= TexCreate_NoFastClear;
	}

	const FRDGTextureDesc CustomDepthDesc = FRDGTextureDesc::Create2D(CustomDepthExtent, PF_DepthStencil, FClearValueBinding::DepthFar, CreateFlags);