Unreal Engine 5 Documentation has been moved to the Epic Developer Community

PSO Reference

Complete reference for PSO caching options.

Choose your operating system:

Windows

macOS

Linux

On the following page you will find all of the various commands and options that can be used with the Pipeline State Object (PSO) caching system.

Properties

Property

Description

SetBatchMode Background

Should be used behind interactive menus.

SetBatchMode Fast

Should be used when a loading screen or movie is being displayed to allow more PSOs to be compiled.

ResumeBatching

Should be used to restart the batching process.

NumPrecompilesRemaining

Is used to determine the total number of outstanding PSOs to compile.

NumPrecompilesActive

Returns the number of pipelines actively being precompiled this frame.

OpenPipelineFileCache

Opens the shader pipeline cache file with either the LastOpened setting if available, or the project name otherwise.

SavePipelineFileCache

Saves the current shader pipeline cache to disk using one of the defined save modes, Fast uses an incremental approach whereas Slow will consolidate all data into the file.

ClosePipelineFileCache

Closes the existing pipeline cache, allowing it to be reopened with a different file and/or shader platform. Will implicitly invoke a Fast Save.

ShaderLibraryStateChanged

Called by FShaderCodeLibrary to notify us that the shader code library state changed and shader availability will need to be re-evaluated.

SetGameUsageMaskWithComparison

Set the current PSO Game Usage Mask and comparison function. Returns true if this mask is different from the old mask or false if not or the cache system is disabled or if the mask feature is disabled. Any new PSO's found will be logged with this value or existing PSO should have their masks updated.  See FPipelineFileCache for more details.

FShaderPipelineCache

The FShaderPipelineCache provides the new PSO logging, serialisation & precompilation mechanism that replaces FShaderCache. Caching Pipeline State Objects and serialising the initialisers to disk allows for precompilation of these states the next time the game is run, which reduces hitching.To achieve this FShaderPipelineCache relies upon FShaderCodeLibrary & "Share Material Shader Code" and the RHI-level backend FPipelineFileCache.

Basic Runtime Usage

The following commands can be used while the PSO caching is running to help make sure that your project does not hitch while PSO data is being complied.

  • You can enable the cache with r.ShaderPipelineCache.Enabled = 1 , which allows the pipeline cache to load existing data from disk and precompile it.

  • Setting the default batch size with r.ShaderPipelineCache.BatchSize = X , where X is the maximum number of PSOs to compile in a single batch when precompiling in the default Fast BatchMode .

  • Setting the background batch size with r.ShaderPipelineCache.BackgroundBatchSize = X , where X is the maximum number of PSOs to compile when in the Background Batch Mode.

  • Instrument the game code to call FShaderPipelineCache::SetBatchMode to switch the batch mode between Fast & Background modes.

  • BatchMode::Fast should be used when a loading screen or movie is being displayed to allow more PSOs to be compiled whereas Background should be used behind interactive menus. If required call NumPrecompilesRemaining to determine the total number of outstanding PSOs to compile and keep the loading screen or movie visible until complete.

  • Depending on the game & target platform performance it may also be required to call PauseBatching to suspend precompilation during gameplay and then ResumeBatching when behind a loading screen, menu or movie to restart precompilation.

Other Runtime Options

The following commands can be used to help further control when the PSO will build the cache.

  • In the GGameIni (and thus also GGameUserSettingsIni) the Shader Pipeline Cache uses the [**ShaderPipelineCache.CacheFile**] section to store some settings.

  • The LastOpened setting stores the name of the last opened cache file as specified with Open, which if present will be used within FShaderPipelineCache::Initialize to open the existing cache. If not specified this will default to the AppName.

  • The SortMode settings stores the desired sort mode for the PSOs, which is one of:

    • Default : Loaded in the order specified in the file.

    • FirstToLatestUsed : Start with the PSOs with the lowest first-frame used and work toward those with the highest.

    • MostToLeastUsed : Start with the most often used PSOs working toward the least.

  • Will use "Default" within FShaderPipelineCache::Initialize & OpenPipelineFileCache if nothing is specified.

  • The GameVersionKey is a read-only integer specified in the GGameIni that specifies the game content version to disambiguate incompatible versions of the game content. By default this is taken from the FEngineVersion changlist.

Logging Usage

The following commands can be used when you are capturing PSO data.

  • You can enable PSO cache using the r.ShaderPipelineCache.Enabled = 1 command and then turn on runtime logging using the r.ShaderPipelineCache.LogPSO = 1 command.

  • When doing this you need to ensure that you have configured the game to open the appropriate cache on startup and allow the game to play.

  • PSOs are logged as they are encountered as Unreal Engine 4 (UE4) does not provide facility to cook them offline, so this system will only collect PSOs which are actually used to render.

  • As such you must either manually play through the game to collect logs or automate the process which is beyond the scope of this code.

  • The data can be saved at any time by calling FShaderPipelineCache::SavePipelineFileCache and this can happen automatically after a given number of PSOs by setting r.ShaderPipelineCache.SaveAfterPSOsLogged = X where X is the desired number of PSOs to log before saving (0 will disable auto-save).

  • Log files are shader platform specific to reduce overheads.

File Locations & Packaging

The following information provided more information on where the PSO data will be stored.

  • The writable cache file is always stored in the User Saved directory.

  • The game can also provide an immutable copy within its Game Content directory which will be used as the initial or seed data.

  • Having generated logs in development and merged them with UnrealEd.MergeShaderPipelineCaches they should be packaged inside the Game Content directory for the relevant platform.

Requirements

The following requirements must be adhered to when trying to setup PSO to be captured in your project.

  • FShaderCodeLibrary must be enabled through Project Settings > Packaging > Share Material Shader Code .

  • Enabling Native Shader Libraries is optional, but strongly preferred for Metal .

Additional Notes

  • The open cache file can be changed by closing the existing file with ClosePipelineFileCache (which implicitly Fast saves) and then opening a new one with OpenPipelineFileCache .

  • When logging if you switch files only new entries from after the switch will be logged, which means you will miss any PSOs that should have been logged prior to switching. This prevents polluting the cache with unexpected entries.

  • The UnrealEd.MergeShaderPipelineCaches command-let can be used to merge cache files with the same file-version, shader platform and game-version.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss