r.ShaderPipelineCache.LogPSO

r.ShaderPipelineCache.LogPSO

#Overview

name: r.ShaderPipelineCache.LogPSO

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderPipelineCache.LogPSO is to control the logging of new Pipeline State Object (PSO) entries into the shader pipeline file cache. It is primarily used for the rendering system, specifically for shader pipeline caching and optimization.

This setting variable is utilized by the Unreal Engine’s rendering subsystem, particularly within the RHI (Rendering Hardware Interface) module. It’s closely tied to the shader pipeline cache system, which aims to optimize shader compilation and loading times.

The value of this variable is set through a console variable (CVarPSOFileCacheLogPSO) in the engine’s configuration system. It can be modified at runtime or set in configuration files.

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

Developers must be aware that:

  1. This variable affects performance and disk usage, as logging PSOs can impact runtime performance and increase file sizes.
  2. It’s primarily used for collecting data on PSO usage, which can be later used to optimize shader loading.
  3. The logged data is platform-specific, so separate logs may be needed for different platforms.

Best practices when using this variable include:

  1. Enable it during development and testing phases to collect PSO data.
  2. Disable it for release builds to avoid unnecessary overhead.
  3. Use in conjunction with other shader pipeline cache settings for comprehensive optimization.
  4. Regularly review and merge the logged PSO data to maintain an up-to-date shader pipeline cache.

Regarding the associated variable CVarPSOFileCacheLogPSO:

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCacheLogPSO(
														   TEXT("r.ShaderPipelineCache.LogPSO"),
														   PIPELINE_CACHE_DEFAULT_ENABLED,
														   TEXT("1 Logs new PSO entries into the file cache and allows saving."),
														   ECVF_Default | ECVF_RenderThreadSafe
														   );

static TAutoConsoleVariable<int32> CVarPSOFileCacheReportPSO(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Public/ShaderPipelineCache.h:53

Scope: file

Source code excerpt:

 *
 * Logging Usage:
 * - Enable the cache with r.ShaderPipelineCache.Enabled = 1 and also turn on runtime logging with r.ShaderPipelineCache.LogPSO = 1.
 * - Ensure that you have configured the game to open the appropriate cache on startup (see above) and allow the game to play.
 * - PSOs are logged as they are encountered as the Unreal Engine 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.
 *
 * 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.
 * - Different files can be used to minimise PSO compilation by having a file per-scalability bucket (i.e. one file for Low, one for Med, one for High).
 * - 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.
 *
 * File Locations & Packaging:
 * - 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 Gane Content directory for the relevant platform.
 *
 * Requirements:
 * - FShaderCodeLibrary must be enabled via Project Settings > Packaging > "Share Material Shader Code".
 * - Enabling "Native Shader Libraries" is optional, but strongly preferred for Metal.
 */
class FShaderPipelineCache : public FTickableObjectRenderThread
{
	// the FShaderPipelineCacheTask class represents a pipeline precompile of a single PSO file cache.
	friend class FShaderPipelineCacheTask;
public:
	/**
	 * Initializes the shader pipeline cache for the desired platform, called by the engine.
	 * The shader platform is used only to load the initial pipeline cache and can be changed by closing & reopening the cache if necessary.
	 */
	static RENDERCORE_API void Initialize(EShaderPlatform Platform);
	/** Terminates the shader pipeline cache, called by the engine. */
	static RENDERCORE_API void Shutdown();

	/** Pauses precompilation. */
	static RENDERCORE_API void PauseBatching();
	
	enum class BatchMode
	{
		Background, // The maximum batch size is defined by r.ShaderPipelineCache.BackgroundBatchSize
		Fast, // The maximum batch size is defined by r.ShaderPipelineCache.BatchSize
		Precompile // The maximum batch size is defined by r.ShaderPipelineCache.PrecompileBatchSize
	};
	
	/** Sets the precompilation batching mode. */
	static RENDERCORE_API void SetBatchMode(BatchMode Mode);
	
	/** Resumes precompilation batching. */
	static RENDERCORE_API void ResumeBatching();
	
	/** true if pipeline cache(s) are precompiling. */
	static RENDERCORE_API bool IsPrecompiling();

	/** Returns the number of pipelines waiting for precompilation of the current PSOFC task. 

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

														   );

static TAutoConsoleVariable<int32> CVarPSOFileCacheLogPSO(
														   TEXT("r.ShaderPipelineCache.LogPSO"),
														   PIPELINE_CACHE_DEFAULT_ENABLED,
														   TEXT("1 Logs new PSO entries into the file cache and allows saving."),
														   ECVF_Default | ECVF_RenderThreadSafe
														   );

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

Scope (from outer to inner):

file
function     bool FPipelineFileCacheManager::LogPSOtoFileCache

Source code excerpt:

		UE_CLOG(bCmdLineForce, LogRHI, Warning, TEXT("****************************** Forcing logging of PSOs from command line"));
	}
	return (bCmdLineForce || CVarPSOFileCacheLogPSO.GetValueOnAnyThread() == 1);
}

bool FPipelineFileCacheManager::ReportNewPSOs()
{
    static bool bOnce = false;
    static bool bCmdLineForce = false;