r.ShaderPipelineCache.StartupMode

r.ShaderPipelineCache.StartupMode

#Overview

name: r.ShaderPipelineCache.StartupMode

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.ShaderPipelineCache.StartupMode is to control the startup behavior of the Pipeline State Object (PSO) cache in Unreal Engine’s rendering system. This setting variable determines how the PSO cache operates after initialization, affecting shader compilation and performance during game startup.

This setting variable is primarily used by the rendering system, specifically the shader pipeline cache subsystem. It is part of the RenderCore module, as evidenced by its location in the ShaderPipelineCache.cpp file.

The value of this variable is set through the console variable system, allowing it to be modified at runtime or through configuration files. It is defined as a TAutoConsoleVariable with an initial value of 1.

The associated variable CVarPSOFileCacheStartupMode directly interacts with r.ShaderPipelineCache.StartupMode. They share the same value and purpose.

Developers must be aware of the following when using this variable:

  1. It has three possible values (0, 1, 2), each with different implications for shader compilation:

    • 0: Precompilation is paused until explicitly resumed
    • 1: Precompilation is enabled in ‘Fast’ mode (default)
    • 2: Precompilation is enabled in ‘Background’ mode

  2. The chosen mode affects the initial performance and loading times of the game.

  3. The variable is used in the FShaderPipelineCache constructor to determine the initial state of the cache.

Best practices when using this variable include:

  1. Consider the target platform and hardware capabilities when choosing a mode.
  2. Use mode 1 (Fast) for development to reduce startup times.
  3. Consider using mode 2 (Background) for shipped games to balance between fast startup and thorough shader precompilation.
  4. Use mode 0 only when you need fine-grained control over when shader compilation occurs.

Regarding the associated variable CVarPSOFileCacheStartupMode:

This is the actual console variable that stores and manages the value of r.ShaderPipelineCache.StartupMode. It is defined using TAutoConsoleVariable, which allows it to be easily accessed and modified through the console or configuration files. The variable is used directly in the FShaderPipelineCache constructor to determine the initial behavior of the shader pipeline cache. Developers should interact with this variable through the console commands or configuration settings rather than modifying it directly in code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:47

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCacheStartupMode(
														  TEXT("r.ShaderPipelineCache.StartupMode"),
														  1,
														  TEXT("Sets the startup mode for the PSO cache, determining what the cache does after initialisation:\n")
														  TEXT("\t0: Precompilation is paused and nothing will compile until a call to ResumeBatching().\n")
														  TEXT("\t1: Precompilation is enabled in the 'Fast' mode.\n")
														  TEXT("\t2: Precompilation is enabled in the 'Background' mode.\n")
														  TEXT("Default is 1."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:46

Scope: file

Source code excerpt:



static TAutoConsoleVariable<int32> CVarPSOFileCacheStartupMode(
														  TEXT("r.ShaderPipelineCache.StartupMode"),
														  1,
														  TEXT("Sets the startup mode for the PSO cache, determining what the cache does after initialisation:\n")
														  TEXT("\t0: Precompilation is paused and nothing will compile until a call to ResumeBatching().\n")
														  TEXT("\t1: Precompilation is enabled in the 'Fast' mode.\n")
														  TEXT("\t2: Precompilation is enabled in the 'Background' mode.\n")

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:1571

Scope (from outer to inner):

file
function     FShaderPipelineCache::FShaderPipelineCache

Source code excerpt:

    SET_DWORD_STAT(STAT_ShaderPipelineActiveTaskCount, 0);
	
	int32 Mode = CVarPSOFileCacheStartupMode.GetValueOnAnyThread();
	switch (Mode)
	{
		case 0:
			BatchSize = CVarPSOFileCacheBatchSize.GetValueOnAnyThread();
			BatchTime = CVarPSOFileCacheBatchTime.GetValueOnAnyThread();
			PausedCount = 1;