r.ShaderPipelineCache.UserCacheUnusedElementRetainDays

r.ShaderPipelineCache.UserCacheUnusedElementRetainDays

#Overview

name: r.ShaderPipelineCache.UserCacheUnusedElementRetainDays

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.UserCacheUnusedElementRetainDays is to control the retention period for unused Pipeline State Object (PSO) entries in the user cache of the shader pipeline cache system. This setting is part of Unreal Engine’s rendering system, specifically the shader pipeline caching mechanism.

This setting variable is primarily used in the RHI (Rendering Hardware Interface) module of Unreal Engine. It’s referenced in the PipelineFileCache.cpp file, which is responsible for managing the pipeline state object cache.

The value of this variable is set as a console variable using TAutoConsoleVariable. It’s initialized with a default value of 30 days, but can be changed at runtime through console commands or configuration files.

This variable interacts closely with the garbage collection mechanism for the user cache. It’s used in the GarbageCollectUserCache function to determine which PSO entries should be removed from the cache based on their last usage time.

Developers must be aware that this variable directly affects the size and performance of the shader pipeline cache. Setting it too low might result in frequently used shaders being evicted too soon, potentially impacting performance. Setting it too high might lead to unnecessary storage usage.

Best practices when using this variable include:

  1. Monitoring the size of the shader cache and adjusting this value based on available storage and performance needs.
  2. Considering the development cycle of the game - a longer retention period might be beneficial during active development to avoid frequent shader recompilations.
  3. Adjusting this value in conjunction with other cache-related settings for optimal performance.

The associated variable CVarPSOFileCacheUserCacheUnusedElementRetainDays is the actual console variable object that stores and provides access to the r.ShaderPipelineCache.UserCacheUnusedElementRetainDays value. It’s used in the same way and for the same purpose as described above. When querying or modifying this setting programmatically, developers would use this CVarPSOFileCacheUserCacheUnusedElementRetainDays object rather than directly referencing the console variable name.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementRetainDays(
                                                            TEXT("r.ShaderPipelineCache.UserCacheUnusedElementRetainDays"),
															30,
                                                            TEXT("The amount of time in days to keep unused PSO entries in the cache."),
                                                            ECVF_Default
                                                            );

static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementCheckPeriod(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

                                                            );

static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementRetainDays(
                                                            TEXT("r.ShaderPipelineCache.UserCacheUnusedElementRetainDays"),
															30,
                                                            TEXT("The amount of time in days to keep unused PSO entries in the cache."),
                                                            ECVF_Default
                                                            );

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

Scope (from outer to inner):

file
function     void GarbageCollectUserCache

Source code excerpt:

		}

		int64 StaleDays = CVarPSOFileCacheUserCacheUnusedElementRetainDays.GetValueOnAnyThread();
		FTimespan StaleTimespan = FTimespan::FromDays(StaleDays);
		int64 EvictionTime = UnixTime - (int64)StaleTimespan.GetTotalSeconds();

		auto EntryShouldBeRemovedFromUserCache = [&Header, FileGuid=this->FileGuid, EvictionTime,&KnownGuids](const FPipelineCacheFileFormatPSOMetaData& MetaData)
		{
			// Remove the element if it is in the user cache and the time has elapsed, or if it was in a cache that no longer exists.