r.ShaderPipelineCache.SaveUserCache

r.ShaderPipelineCache.SaveUserCache

#Overview

name: r.ShaderPipelineCache.SaveUserCache

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

• type: Var
• help: If > 0 then any missed PSOs will be saved to a writable user cache file for subsequent runs to load and avoid in-game hitches. Enabled by default on macOS only.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderPipelineCache.SaveUserCache is to control the saving of missed Pipeline State Objects (PSOs) to a writable user cache file. This setting is primarily used in the rendering system, specifically for shader pipeline caching.

This setting variable is utilized by the Unreal Engine’s rendering subsystem, particularly in the RHI (Rendering Hardware Interface) and RenderCore modules. It’s closely tied to the shader pipeline caching mechanism, which aims to improve rendering performance by reducing in-game hitches.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value that depends on the build configuration (PIPELINE_CACHE_DEFAULT_ENABLED && UE_BUILD_SHIPPING), meaning it’s enabled by default in shipping builds.

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

Developers must be aware that this variable affects performance and disk usage. When enabled, it can help reduce in-game hitches by caching missed PSOs, but it also writes to disk, which could impact storage space over time.

Best practices when using this variable include:

1. Enabling it for shipping builds to improve end-user experience.
2. Considering disabling it during development if rapid iteration is more important than simulating shipping performance.
3. Monitoring the size of the user cache file to ensure it doesn’t grow excessively large over time.

Regarding the associated variable CVarPSOFileCacheSaveUserCache:

The purpose of CVarPSOFileCacheSaveUserCache is identical to r.ShaderPipelineCache.SaveUserCache. It’s the actual console variable that controls the behavior described above.

This variable is used in the RHI and RenderCore modules, specifically in the pipeline file caching system.

The value is set when the console variable is created, and can be modified at runtime through console commands.

It interacts directly with r.ShaderPipelineCache.SaveUserCache, as they represent the same setting.

Developers should be aware that this is the actual variable queried in the code to determine whether to save the user cache. The GetPSOFileCacheSaveUserCache() function uses this variable to make its determination.

Best practices include using this variable name when querying the current state of the user cache saving feature in code, and potentially exposing it in debugging tools for runtime modification.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineFileCache.cpp:133

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarPSOFileCacheSaveUserCache(
                                                            TEXT("r.ShaderPipelineCache.SaveUserCache"),
															PIPELINE_CACHE_DEFAULT_ENABLED && UE_BUILD_SHIPPING,
                                                            TEXT("If > 0 then any missed PSOs will be saved to a writable user cache file for subsequent runs to load and avoid in-game hitches. Enabled by default on macOS only."),
                                                            ECVF_Default | ECVF_RenderThreadSafe
                                                            );

static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementRetainDays(

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

Scope (from outer to inner):

file
function     static bool GetPSOFileCacheSaveUserCache

Source code excerpt:

static bool GetPSOFileCacheSaveUserCache()
{
	static const auto CVarPSOFileCacheSaveUserCache = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShaderPipelineCache.SaveUserCache"));
	return GRHISupportsPipelineFileCache && (CVarPSOFileCacheSaveUserCache && CVarPSOFileCacheSaveUserCache->GetInt() > 0);
}

void ConsoleCommandLoadPipelineFileCache()
{
	FShaderPipelineCache::CloseUserPipelineFileCache();

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineFileCache.cpp:132

Scope: file

Source code excerpt:

														   );

static TAutoConsoleVariable<int32> CVarPSOFileCacheSaveUserCache(
                                                            TEXT("r.ShaderPipelineCache.SaveUserCache"),
															PIPELINE_CACHE_DEFAULT_ENABLED && UE_BUILD_SHIPPING,
                                                            TEXT("If > 0 then any missed PSOs will be saved to a writable user cache file for subsequent runs to load and avoid in-game hitches. Enabled by default on macOS only."),
                                                            ECVF_Default | ECVF_RenderThreadSafe
                                                            );

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

Scope (from outer to inner):

file
function     static bool GetPSOFileCacheSaveUserCache

Source code excerpt:

static bool GetPSOFileCacheSaveUserCache()
{
	static const auto CVarPSOFileCacheSaveUserCache = IConsoleManager::Get().FindConsoleVariable(TEXT("r.ShaderPipelineCache.SaveUserCache"));
	return GRHISupportsPipelineFileCache && (CVarPSOFileCacheSaveUserCache && CVarPSOFileCacheSaveUserCache->GetInt() > 0);
}

void ConsoleCommandLoadPipelineFileCache()
{
	FShaderPipelineCache::CloseUserPipelineFileCache();
	FShaderPipelineCache::OpenUserPipelineFileCache(GMaxRHIShaderPlatform);