r.PSOPrecache.CustomDepth

r.PSOPrecache.CustomDepth

#Overview

name: r.PSOPrecache.CustomDepth

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.PSOPrecache.CustomDepth is to control the precompilation of Pipeline State Objects (PSOs) for the custom depth rendering pass in Unreal Engine 5’s rendering system. This setting variable is specifically used to manage the optimization of custom depth rendering performance.

This setting variable is primarily used by the Renderer module of Unreal Engine 5, particularly in the custom depth rendering subsystem. The code referencing this variable is found in the CustomDepthRendering.cpp file, which is part of the renderer’s implementation.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s initialized with a default value of 1, but can be modified through console commands or configuration files.

The variable interacts directly with its associated variable CVarPSOPrecacheCustomDepth, which is the actual TAutoConsoleVariable object that stores and manages the value. They essentially represent the same setting, with r.PSOPrecache.CustomDepth being the console command name, and CVarPSOPrecacheCustomDepth being the C++ variable that holds the value.

Developers must be aware that this variable has three possible values, each with different implications: 0: No PSOs are compiled for the custom depth pass. 1: PSOs are compiled only for primitives that explicitly request custom depth rendering (default). 2: PSOs are compiled for all primitives that also request regular depth rendering.

The best practices when using this variable include:

  1. Leave it at the default value (1) unless you have specific performance needs.
  2. If custom depth is not used in your project, setting it to 0 can save compilation time and memory.
  3. Setting it to 2 can improve performance if many objects use custom depth, but at the cost of increased memory usage and compilation time.

Regarding the associated variable CVarPSOPrecacheCustomDepth:

The purpose of CVarPSOPrecacheCustomDepth is to provide a C++ interface for the r.PSOPrecache.CustomDepth console variable. It allows C++ code to read and react to changes in this setting.

This variable is used in the same Renderer module, specifically in the FCustomDepthPassMeshProcessor::CollectPSOInitializers function. This function is responsible for collecting Pipeline State Object initializers for the custom depth pass.

The value of CVarPSOPrecacheCustomDepth is set automatically by the console variable system when r.PSOPrecache.CustomDepth is modified.

CVarPSOPrecacheCustomDepth interacts directly with the r.PSOPrecache.CustomDepth console variable, effectively serving as its C++ representation.

Developers should be aware that this variable is marked as ECVF_ReadOnly, meaning its value should not be directly modified in C++ code. Instead, changes should be made through the console variable system.

Best practices for using CVarPSOPrecacheCustomDepth include:

  1. Use GetValueOnAnyThread() to safely read its value from any thread.
  2. Don’t attempt to modify its value directly in C++ code.
  3. Be aware of its performance implications when deciding how to use custom depth in your rendering pipeline.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOPrecacheCustomDepth(
	TEXT("r.PSOPrecache.CustomDepth"),
	1,
	TEXT("Also Precache PSOs with for custom depth pass.")  \
	TEXT(" 0: No PSOs are compiled for this pass.\n") \
	TEXT(" 1: PSOs are compiled for all primitives which explicitly request custom depth rendering (default).\n") \
	TEXT(" 2: PSOs are compiled for all primitives which also request regular depth rendering.\n"),
	ECVF_ReadOnly

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOPrecacheCustomDepth(
	TEXT("r.PSOPrecache.CustomDepth"),
	1,
	TEXT("Also Precache PSOs with for custom depth pass.")  \
	TEXT(" 0: No PSOs are compiled for this pass.\n") \
	TEXT(" 1: PSOs are compiled for all primitives which explicitly request custom depth rendering (default).\n") \
	TEXT(" 2: PSOs are compiled for all primitives which also request regular depth rendering.\n"),

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

Scope (from outer to inner):

file
function     void FCustomDepthPassMeshProcessor::CollectPSOInitializers

Source code excerpt:

void FCustomDepthPassMeshProcessor::CollectPSOInitializers(const FSceneTexturesConfig& SceneTexturesConfig, const FMaterial& Material, const FPSOPrecacheVertexFactoryData& VertexFactoryData, const FPSOPrecacheParams& PreCacheParams, TArray<FPSOPrecacheData>& PSOInitializers)
{
	int32 CustomDepthPrecacheMode = CVarPSOPrecacheCustomDepth.GetValueOnAnyThread();
	if (CustomDepthPrecacheMode == 0)
	{
		return;
	}

	// Setup the depth stencil state to use