r.PSOPrecache.ProjectedShadows

r.PSOPrecache.ProjectedShadows

#Overview

name: r.PSOPrecache.ProjectedShadows

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

• type: Var
• help: Also Precache PSOs with for projected shadows. 0: No PSOs are compiled for this pass.\n 1: PSOs are compiled for all primitives which render to depth pass (default).\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PSOPrecache.ProjectedShadows is to control the precompilation of Pipeline State Objects (PSOs) for projected shadows in Unreal Engine’s rendering system. This setting is part of the engine’s PSO precaching mechanism, which aims to improve rendering performance by preparing shader pipelines in advance.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the depth rendering subsystem. It’s defined and utilized in the DepthRendering.cpp file.

The value of this variable is set through a console variable (CVar) system, with a default value of 1. It can be changed at runtime, but it’s marked as ECVF_ReadOnly, suggesting that changes should be made with caution and possibly only during development or debugging.

The associated variable CVarPSOPrecacheProjectedShadows directly interacts with r.PSOPrecache.ProjectedShadows. They share the same value and purpose.

Developers must be aware that:

1. This variable affects performance and memory usage. When enabled (set to 1), it causes additional PSOs to be compiled for all primitives that render to the depth pass.
2. Changing this value may impact the startup time of the engine or the time taken to load levels, as PSO compilation can be time-consuming.
3. The setting is binary: 0 disables PSO precaching for projected shadows, while any non-zero value enables it.

Best practices when using this variable include:

1. Leave it at the default value (1) unless you have specific performance issues related to PSO compilation or memory usage.
2. If disabling it, thoroughly test the performance impact, especially in scenes with many dynamic shadows.
3. Consider the trade-off between initial loading time and runtime performance when adjusting this setting.

Regarding the associated variable CVarPSOPrecacheProjectedShadows:

• Its purpose is identical to r.PSOPrecache.ProjectedShadows, serving as the actual console variable implementation.
• It’s used directly in the C++ code to check the current setting (e.g., CVarPSOPrecacheProjectedShadows.GetValueOnAnyThread()).
• The variable is defined as a TAutoConsoleVariable, allowing for runtime changes.
• Developers should use this variable name when accessing the setting in C++ code.
• Best practices for CVarPSOPrecacheProjectedShadows are the same as for r.PSOPrecache.ProjectedShadows, as they represent the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DepthRendering.cpp:84

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarPSOPrecacheProjectedShadows(
	TEXT("r.PSOPrecache.ProjectedShadows"),
	1,
	TEXT("Also Precache PSOs with for projected shadows.")  \
	TEXT(" 0: No PSOs are compiled for this pass.\n") \
	TEXT(" 1: PSOs are compiled for all primitives which render to depth pass (default).\n"),
	ECVF_ReadOnly
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DepthRendering.cpp:83

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarPSOPrecacheProjectedShadows(
	TEXT("r.PSOPrecache.ProjectedShadows"),
	1,
	TEXT("Also Precache PSOs with for projected shadows.")  \
	TEXT(" 0: No PSOs are compiled for this pass.\n") \
	TEXT(" 1: PSOs are compiled for all primitives which render to depth pass (default).\n"),
	ECVF_ReadOnly

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DepthRendering.cpp:908

Scope (from outer to inner):

file
function     void FDepthPassMeshProcessor::CollectPSOInitializersInternal

Source code excerpt:

	// Also cache with project shadow depth stencil state (see FProjectedShadowInfo::SetupMeshDrawCommandsForProjectionStenciling)
	if (CVarPSOPrecacheProjectedShadows.GetValueOnAnyThread() > 0)
	{
		// Set stencil to one.
		DrawRenderState.SetDepthStencilState(
			TStaticDepthStencilState<
			false, CF_DepthNearOrEqual,
			true, CF_Always, SO_Keep, SO_Keep, SO_Replace,