r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent

r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent

#Overview

name: r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent

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.LazyLoadShadersWhenPSOCacheIsPresent is to control lazy loading of shaders from the shader code library when a Pipeline State Object (PSO) cache is present. This setting is primarily used in the rendering system, specifically for shader and pipeline state management.

This setting variable is used in the RHI (Rendering Hardware Interface) subsystem of Unreal Engine 5. It’s particularly relevant to the pipeline file cache functionality, which is part of the rendering pipeline optimization.

The value of this variable is set through a console variable (CVarLazyLoadShadersWhenPSOCacheIsPresent) in the RHI module. It’s defined with a default value of 0, which means the feature is disabled by default.

This variable interacts with GRHISupportsLazyShaderCodeLoading, which is a global variable indicating whether the current RHI supports lazy shader code loading. It also affects GRHILazyShaderCodeLoading, which is set based on the value of this console variable.

Developers must be aware that this feature only works on RHIs that support the library+Hash CreateShader API (when GRHISupportsLazyShaderCodeLoading is true). It assumes that the PSO cache is more or less complete, which could potentially lead to missing shaders if the cache is incomplete.

Best practices when using this variable include:

  1. Ensure that the PSO cache is complete before enabling this feature.
  2. Monitor performance to verify that lazy loading is beneficial in your specific use case.
  3. Be prepared to disable this feature if you encounter issues with missing shaders.

Regarding the associated variable CVarLazyLoadShadersWhenPSOCacheIsPresent:

This is the actual console variable that controls the r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent setting. It’s an integer variable, where non-zero values enable the lazy loading feature.

The purpose of this variable is to provide a runtime-configurable way to enable or disable lazy shader loading when a PSO cache is present. It’s used in the same RHI subsystem and serves the same function as the r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent setting.

The value of this variable can be changed at runtime through the console, allowing for dynamic adjustment of the lazy loading behavior.

Developers should be aware that changes to this variable take effect when opening the pipeline file cache. It’s checked in the OpenPipelineFileCache function to determine whether to enable lazy shader code loading.

Best practices for using this variable include:

  1. Use it for debugging and performance tuning.
  2. Be cautious when enabling it in shipping builds, as it assumes a complete PSO cache.
  3. Consider exposing it as a configurable option for advanced users if shader loading performance is a critical aspect of your game.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLazyLoadShadersWhenPSOCacheIsPresent(
	TEXT("r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent"),
	0,
	TEXT("Non-Zero: If we load a PSO cache, then lazy load from the shader code library. This assumes the PSO cache is more or less complete. This will only work on RHIs that support the library+Hash CreateShader API (GRHISupportsLazyShaderCodeLoading == true)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarClearOSPSOFileCache(
														   TEXT("r.ShaderPipelineCache.ClearOSCache"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

                                                            );

static TAutoConsoleVariable<int32> CVarLazyLoadShadersWhenPSOCacheIsPresent(
	TEXT("r.ShaderPipelineCache.LazyLoadShadersWhenPSOCacheIsPresent"),
	0,
	TEXT("Non-Zero: If we load a PSO cache, then lazy load from the shader code library. This assumes the PSO cache is more or less complete. This will only work on RHIs that support the library+Hash CreateShader API (GRHISupportsLazyShaderCodeLoading == true)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarClearOSPSOFileCache(

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

Scope (from outer to inner):

file
function     bool OpenPipelineFileCache

Source code excerpt:

		}

		if (bGameFileOk && GRHISupportsLazyShaderCodeLoading && CVarLazyLoadShadersWhenPSOCacheIsPresent.GetValueOnAnyThread())
		{
			UE_LOG(LogRHI, Log, TEXT("Lazy loading from the shader code library is enabled."));
			GRHILazyShaderCodeLoading = true;
		}

#if !UE_BUILD_SHIPPING