r.ShaderPipelineCache.PreOptimizeEnabled

r.ShaderPipelineCache.PreOptimizeEnabled

#Overview

name: r.ShaderPipelineCache.PreOptimizeEnabled

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.PreOptimizeEnabled is to control the pre-optimization of Pipeline State Objects (PSOs) in Unreal Engine 5’s rendering system. This setting allows some PSOs to be compiled in the foreground before entering the game, which can potentially improve performance by reducing runtime shader compilation.

This setting variable is primarily used by the rendering subsystem of Unreal Engine 5, specifically within the shader pipeline cache functionality. It is implemented in the RenderCore module, as evidenced by its location in the ShaderPipelineCache.cpp file.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 0, meaning it is disabled by default. Developers can change this value at runtime or through configuration files.

The associated variable CVarPSOFileCachePreOptimizeEnabled directly interacts with r.ShaderPipelineCache.PreOptimizeEnabled. They share the same value and purpose, with CVarPSOFileCachePreOptimizeEnabled being the actual C++ variable used in the code to access the setting.

Developers must be aware that enabling this setting (by setting it to a non-zero value) will cause some PSOs to be compiled in the foreground before the game starts. This can potentially increase initial loading times but may lead to smoother gameplay due to reduced runtime shader compilation.

Best practices when using this variable include:

  1. Only enable it if you’re experiencing issues with runtime shader compilation stuttering.
  2. Monitor the impact on initial loading times when enabled.
  3. Use in conjunction with other shader pre-compilation and optimization techniques for best results.
  4. Consider enabling it for release builds but keeping it disabled during development for faster iteration times.

Regarding the associated variable CVarPSOFileCachePreOptimizeEnabled:

The purpose of CVarPSOFileCachePreOptimizeEnabled is to provide a programmatic interface to the r.ShaderPipelineCache.PreOptimizeEnabled setting within the C++ code of Unreal Engine 5.

This variable is used directly in the RenderCore module, specifically in the FShaderPipelineCacheTask class. It’s used to determine whether the shader pipeline cache is ready for use, in conjunction with other conditions such as the game usage mask.

The value of CVarPSOFileCachePreOptimizeEnabled is set through the console variable system, mirroring the value of r.ShaderPipelineCache.PreOptimizeEnabled.

This variable interacts closely with CVarPSOFileCacheGameFileMaskEnabled, another console variable that controls aspects of the shader pipeline cache system.

Developers should be aware that this variable is marked as read-only and render thread safe, meaning its value should not be changed during runtime after initial configuration.

Best practices for using CVarPSOFileCachePreOptimizeEnabled include:

  1. Use GetValueOnAnyThread() to safely access its value from any thread.
  2. Consider the performance implications of enabling pre-optimization when deciding whether to use this feature.
  3. Use in combination with other shader pipeline cache settings for optimal performance tuning.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCachePreOptimizeEnabled(
																TEXT("r.ShaderPipelineCache.PreOptimizeEnabled"),
																(int32)0,
																TEXT("Set non zero to PreOptimize PSOs - this allows some PSOs to be compiled in the foreground before going in to game"),
																ECVF_ReadOnly | ECVF_RenderThreadSafe);


static TAutoConsoleVariable<int32> CVarPSOFileCacheMinBindCount(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

																ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOFileCachePreOptimizeEnabled(
																TEXT("r.ShaderPipelineCache.PreOptimizeEnabled"),
																(int32)0,
																TEXT("Set non zero to PreOptimize PSOs - this allows some PSOs to be compiled in the foreground before going in to game"),
																ECVF_ReadOnly | ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
class        class FShaderPipelineCacheTask
function     FShaderPipelineCacheTask

Source code excerpt:

		// * Pre-optimization is enabled.
		bReady = (!CVarPSOFileCacheGameFileMaskEnabled.GetValueOnAnyThread() || FPipelineFileCacheManager::IsGameUsageMaskSet())
			|| CVarPSOFileCachePreOptimizeEnabled.GetValueOnAnyThread();
	}

	bool Open(const FString& Key, const FString& Name, EShaderPlatform Platform);
	
	void Close();
	void Shutdown();