r.ShaderPipelineCache.GameFileMaskEnabled

r.ShaderPipelineCache.GameFileMaskEnabled

#Overview

name: r.ShaderPipelineCache.GameFileMaskEnabled

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderPipelineCache.GameFileMaskEnabled is to control the usage of the GameFileMask during Pipeline State Object (PSO) precompilation in Unreal Engine 5’s rendering system. This setting is part of the shader pipeline caching mechanism, which aims to optimize shader compilation and loading times.

This setting variable is primarily used in the RenderCore module of Unreal Engine 5, specifically within the shader pipeline caching system. It affects the behavior of the FShaderPipelineCache class and related tasks.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

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

Developers must be aware of the following when using this variable:

  1. It’s a read-only and render thread safe variable, meaning it shouldn’t be modified during runtime.
  2. When enabled (set to non-zero), it affects the PSO precompilation process by using the GameFileMask.
  3. It interacts with other settings like r.ShaderPipelineCache.PreOptimizeEnabled.

Best practices for using this variable include:

  1. Always save out usage masks during recording to ensure data availability when needed.
  2. Consider enabling this feature if you want more granular control over which PSOs are precompiled based on game-specific usage patterns.
  3. Be aware of the performance implications of enabling this feature, as it may affect loading times and shader compilation behavior.

Regarding the associated variable CVarPSOFileCacheGameFileMaskEnabled:

The purpose of CVarPSOFileCacheGameFileMaskEnabled is identical to r.ShaderPipelineCache.GameFileMaskEnabled. It’s the internal representation of the console variable within the C++ code.

This variable is used throughout the FShaderPipelineCache and FShaderPipelineCacheTask implementations to determine whether the GameFileMask should be considered during various operations.

The value of this variable is set when the console variable is initialized and can be accessed using the GetValueOnAnyThread() method.

Developers should be aware that this variable is used in critical sections of the shader pipeline caching system, including task readiness checks, game usage mask setting, and PSO precompilation comparisons.

Best practices for using this variable include:

  1. Use GetValueOnAnyThread() to access its value in a thread-safe manner.
  2. Consider the implications of enabling or disabling this feature on shader compilation performance and loading times.
  3. Use in conjunction with other related variables like CVarPSOFileCachePreOptimizeEnabled for a comprehensive shader pipeline caching strategy.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:130

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCacheGameFileMaskEnabled(
																TEXT("r.ShaderPipelineCache.GameFileMaskEnabled"),
																(int32)0,
																TEXT("Set non zero to use GameFileMask during PSO precompile - recording should always save out the usage masks to make that data availble when needed."),
																ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOFileCachePreOptimizeEnabled(
																TEXT("r.ShaderPipelineCache.PreOptimizeEnabled"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:129

Scope: file

Source code excerpt:

																 );

static TAutoConsoleVariable<int32> CVarPSOFileCacheGameFileMaskEnabled(
																TEXT("r.ShaderPipelineCache.GameFileMaskEnabled"),
																(int32)0,
																TEXT("Set non zero to use GameFileMask during PSO precompile - recording should always save out the usage masks to make that data availble when needed."),
																ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarPSOFileCachePreOptimizeEnabled(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:403

Scope (from outer to inner):

file
class        class FShaderPipelineCacheTask
function     FShaderPipelineCacheTask

Source code excerpt:

		// * The usage mask mechanism is enabled and the mask has already been set.
		// * Pre-optimization is enabled.
		bReady = (!CVarPSOFileCacheGameFileMaskEnabled.GetValueOnAnyThread() || FPipelineFileCacheManager::IsGameUsageMaskSet())
			|| CVarPSOFileCachePreOptimizeEnabled.GetValueOnAnyThread();
	}

	bool Open(const FString& Key, const FString& Name, EShaderPlatform Platform);
	
	void Close();

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:660

Scope (from outer to inner):

file
function     bool FShaderPipelineCache::SetGameUsageMaskWithComparison

Source code excerpt:

	static bool bMaskChanged = false;

	if (ShaderPipelineCache != nullptr && CVarPSOFileCacheGameFileMaskEnabled.GetValueOnAnyThread())
	{
		FScopeLock Lock(&ShaderPipelineCache->Mutex);
		
		if (!ShaderPipelineCache->ShaderCacheTasks.IsEmpty())
		{
			uint64 OldMask = FPipelineFileCacheManager::SetGameUsageMaskWithComparison(InMask, InComparisonFnPtr);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:1949

Scope (from outer to inner):

file
function     void FShaderPipelineCacheTask::Tick

Source code excerpt:

	}
	
	if(CVarPSOFileCacheGameFileMaskEnabled.GetValueOnAnyThread())
	{
		if(TotalActiveTasks + TotalWaitingTasks == 0)
		{
			const uint64 Mask = FPipelineFileCacheManager::GetGameUsageMask();
			bool bAlreadyInSet = false;
			CompletedMasks.Add(Mask, &bAlreadyInSet);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:2015

Scope (from outer to inner):

file
function     static bool PreCompileMaskComparison

Source code excerpt:

{
	// If game mask use is disabled then the precompile comparison should succeed.
	const bool bIgnoreGameMask = CVarPSOFileCacheGameFileMaskEnabled.GetValueOnAnyThread() == 0;

	uint64 UsageMask = (ReferenceGameMask & PSOMask);
	return bIgnoreGameMask || ((UsageMask & (7l << (MaxQualityCount*3+MaxPlaylistCount))) && (UsageMask & (7 << (MaxQualityCount*3))) && (UsageMask & (63 << MaxQualityCount*2)) && (UsageMask & (63 << MaxQualityCount)) && (UsageMask & 63));
}

bool FShaderPipelineCacheTask::Open(const FString& Key, FString const& Name, EShaderPlatform Platform)