r.Vulkan.EnablePipelineLRUCache

r.Vulkan.EnablePipelineLRUCache

#Overview

name: r.Vulkan.EnablePipelineLRUCache

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

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Vulkan.EnablePipelineLRUCache is to enable or disable the Pipeline Least Recently Used (LRU) cache for Vulkan rendering. This setting variable is primarily used in the Vulkan rendering subsystem of Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the VulkanRHI (Vulkan Rendering Hardware Interface) module. It’s specifically used in the pipeline state cache management system within the Vulkan renderer.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with two possible values: 0: disable LRU 1: Enable LRU

This variable interacts closely with other variables related to Vulkan pipeline management, such as those controlling remote compile services on Android platforms.

Developers must be aware that enabling this variable (setting it to 1) will activate the LRU caching mechanism for Vulkan pipelines. This can help manage memory usage by discarding least recently used pipelines when the cache reaches its capacity limit. However, it may also introduce potential hitches if a required pipeline is not in the cache and needs to be recompiled.

Best practices when using this variable include:

  1. Only enable it if you’re experiencing issues with pipeline compilation or memory usage.
  2. Monitor performance closely after enabling to ensure it’s not introducing unexpected hitches.
  3. Consider adjusting the LRU cache capacity (likely controlled by a separate variable) if enabled.

Regarding the associated variable CVarEnableLRU:

The purpose of CVarEnableLRU is similar to r.Vulkan.EnablePipelineLRUCache, but it’s used in multiple rendering backends, including both Vulkan and OpenGL.

This variable is referenced in both the VulkanRHI and OpenGLDrv modules of Unreal Engine. In OpenGL, it’s specifically used to enable or disable the OpenGL program LRU cache.

The value of this variable is also set through the console variable system, with similar 0 and 1 values for disabling and enabling the LRU cache respectively.

Developers should be aware that in OpenGL, this variable is only effective if the driver supports program binary. If program binary is not supported, the engine will fall back to a non-LRU cache even if this variable is enabled.

Best practices for CVarEnableLRU are similar to those for r.Vulkan.EnablePipelineLRUCache, but developers should also consider the specific requirements and behaviors of each rendering backend (Vulkan and OpenGL) when deciding to enable or disable this feature.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:68

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarEnableLRU(
	TEXT("r.Vulkan.EnablePipelineLRUCache"),
	0,
	TEXT("Pipeline LRU cache.\n")
	TEXT("0: disable LRU\n")
	TEXT("1: Enable LRU"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/Android/VulkanAndroidPlatform.cpp:1416

Scope (from outer to inner):

file
function     static bool AreAndroidVulkanRemoteCompileServicesAvailable

Source code excerpt:

		const FString* ConfigRulesDisableProgramCompileServices = FAndroidMisc::GetConfigRulesVariable(TEXT("DisableProgramCompileServices"));
		bool bConfigRulesDisableProgramCompileServices = ConfigRulesDisableProgramCompileServices && ConfigRulesDisableProgramCompileServices->Equals("true", ESearchCase::IgnoreCase);
		static const auto CVarProgramLRU = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Vulkan.EnablePipelineLRUCache"));
		static const auto CVarNumRemoteProgramCompileServices = IConsoleManager::Get().FindConsoleVariable(TEXT("Android.Vulkan.NumRemoteProgramCompileServices"));

		RemoteCompileService = !bConfigRulesDisableProgramCompileServices && VKRemoteProgramCompileJNI.bAllFound && (CVarProgramLRU->GetInt() != 0) && (CVarNumRemoteProgramCompileServices->GetInt() > 0);
		FGenericCrashContext::SetEngineData(TEXT("Android.PSOService"), RemoteCompileService == 0 ? TEXT("disabled") : TEXT("enabled"));

		UE_LOG(LogRHI, Log, TEXT("External PSO compilers = %s"), RemoteCompileService == 0 ? TEXT("disabled") : TEXT("enabled"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/OpenGLDrv/Private/OpenGLShaders.cpp:26

Scope: file

Source code excerpt:

#include "SceneUtils.h"

static TAutoConsoleVariable<int32> CVarEnableLRU(
	TEXT("r.OpenGL.EnableProgramLRUCache"),
	0,
	TEXT("OpenGL program LRU cache.\n")
	TEXT("For use only when driver only supports a limited number of active GL programs.\n")
	TEXT("0: disable LRU. (default)\n")
	TEXT("1: When the LRU cache limits are reached, the least recently used GL program(s) will be deleted to make space for new/more recent programs. Expect hitching if requested shader is not in LRU cache."),

#Loc: <Workspace>/Engine/Source/Runtime/OpenGLDrv/Private/OpenGLShaders.cpp:1810

Scope (from outer to inner):

file
class        class FGLProgramCache
function     static bool IsUsingLRU

Source code excerpt:

		if (UseLRUCacheStatus == -1)
		{
			if (CVarEnableLRU.GetValueOnAnyThread() && !FOpenGL::SupportsProgramBinary())
			{
				UE_LOG(LogRHI, Warning, TEXT("Requesting OpenGL program LRU cache, but program binary is not supported by driver. Falling back to non-lru cache."));
			}

			UseLRUCacheStatus = CVarEnableLRU.GetValueOnAnyThread() == 1 && FOpenGLProgramBinaryCache::IsEnabled();
			UE_LOG(LogRHI, Log, TEXT("OpenGL program LRU cache active = %d (%d, %d)"), UseLRUCacheStatus, CVarEnableLRU.GetValueOnAnyThread(), FOpenGLProgramBinaryCache::IsEnabled());
		}
		check(UseLRUCacheStatus != -1);
		return UseLRUCacheStatus == 1;
	}

	FORCEINLINE_DEBUGGABLE void Touch(FOpenGLLinkedProgram* LinkedProgram)

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:67

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarEnableLRU(
	TEXT("r.Vulkan.EnablePipelineLRUCache"),
	0,
	TEXT("Pipeline LRU cache.\n")
	TEXT("0: disable LRU\n")
	TEXT("1: Enable LRU"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly);

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:291

Scope (from outer to inner):

file
function     FVulkanPipelineStateCacheManager::FVulkanPipelineStateCacheManager

Source code excerpt:

	, bPrecompilingCacheLoadedFromFile(false)
{
	bUseLRU = (int32)CVarEnableLRU.GetValueOnAnyThread() != 0;
	LRUUsedPipelineMax = CVarLRUPipelineCapacity.GetValueOnAnyThread();
}


FVulkanPipelineStateCacheManager::~FVulkanPipelineStateCacheManager()
{

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:386

Scope (from outer to inner):

file
function     bool FVulkanPipelineStateCacheManager::Load

Source code excerpt:


	//TODO: how to load LRU cache as it will have info about PSOs from multiple caches
	if(CVarEnableLRU.GetValueOnAnyThread() != 0)
	{
		for (const FString& CacheFilename : CacheFilenames)
		{
			double BeginTime = FPlatformTime::Seconds();
			FString LruCacheFilename = FVulkanPlatform::CreatePSOBinaryCacheFilename(Device, CacheFilename);
			LruCacheFilename += TEXT(".lru");

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:658

Scope (from outer to inner):

file
function     void FVulkanPipelineStateCacheManager::SavePSOCache

Source code excerpt:

	}

	if (CVarEnableLRU.GetValueOnAnyThread() != 0)
	{
		// LRU cache file
		TArray<uint8> MemFile;
		FMemoryWriter Ar(MemFile);
		FVulkanLRUCacheFile File;
		File.Header.Version = FVulkanLRUCacheFile::LRU_CACHE_VERSION;

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanPipeline.cpp:2486

Scope (from outer to inner):

file
function     bool FVulkanPipelineStateCacheManager::LRUEvictImmediately

Source code excerpt:

bool FVulkanPipelineStateCacheManager::LRUEvictImmediately()
{
	return bEvictImmediately && CVarEnableLRU.GetValueOnAnyThread() != 0;
}


void FVulkanPipelineStateCacheManager::LRUTrim(uint32 nSpaceNeeded)
{
	if(!bUseLRU)