GameFeaturePlugin.ForceSyncLoadShaderLibrary

GameFeaturePlugin.ForceSyncLoadShaderLibrary

#Overview

name: GameFeaturePlugin.ForceSyncLoadShaderLibrary

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 GameFeaturePlugin.ForceSyncLoadShaderLibrary is to control the loading behavior of shader libraries in the Game Features plugin system. It is specifically used to force shader libraries to be opened on the game thread, rather than asynchronously.

This setting variable is primarily used within the Game Features plugin, which is part of Unreal Engine’s runtime module system. It affects the plugin loading and management process, particularly in relation to shader loading.

The value of this variable is set as a console variable (CVar) in the GameFeaturePluginStateMachine.cpp file. It is initialized with a default value of true, meaning by default, shader libraries will be forced to load synchronously on the game thread.

The associated variable CVarForceSyncLoadShaderLibrary directly interacts with GameFeaturePlugin.ForceSyncLoadShaderLibrary. They share the same value and purpose.

Developers must be aware that using this variable can impact performance, especially during plugin loading. Forcing synchronous loading on the game thread can potentially cause frame rate drops or hitches, particularly when loading large shader libraries.

Best practices when using this variable include:

  1. Only enable it when necessary, such as for debugging or when experiencing issues with asynchronous shader loading.
  2. Consider the performance implications, especially on lower-end hardware.
  3. Use in conjunction with profiling tools to measure the impact on load times and frame rates.
  4. Be cautious when changing this setting in shipping builds, as it can significantly affect the user experience.

Regarding the associated variable CVarForceSyncLoadShaderLibrary:

The purpose of CVarForceSyncLoadShaderLibrary is identical to GameFeaturePlugin.ForceSyncLoadShaderLibrary. It is the actual console variable implementation that controls the behavior.

This variable is used within the Game Features plugin system, specifically in the plugin state machine that manages the loading and unloading of game feature plugins.

The value of CVarForceSyncLoadShaderLibrary is set in the same location as GameFeaturePlugin.ForceSyncLoadShaderLibrary, in the GameFeaturePluginStateMachine.cpp file.

CVarForceSyncLoadShaderLibrary interacts directly with the plugin loading process. It is checked in the UpdateState_MountPlugin function to determine whether to use synchronous or asynchronous loading for plugins.

Developers should be aware that this variable directly affects the plugin loading process and can impact game performance, especially during level transitions or when activating game features.

Best practices for using CVarForceSyncLoadShaderLibrary include:

  1. Use it for debugging shader loading issues or when investigating plugin loading problems.
  2. Be cautious about enabling it in production builds due to potential performance impacts.
  3. Consider using it in combination with other debugging tools to isolate shader loading or plugin mounting issues.
  4. Remember to disable it when not needed to ensure optimal performance in most scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:79

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to force only searching for monolithic shader libs when possible"));

	static TAutoConsoleVariable<bool> CVarForceSyncLoadShaderLibrary(TEXT("GameFeaturePlugin.ForceSyncLoadShaderLibrary"),
		true,
		TEXT("Enable to force shaderlibs to be opened on the game thread"));

	static TAutoConsoleVariable<bool> CVarForceSyncAssetRegistryAppend(TEXT("GameFeaturePlugin.ForceSyncAssetRegistryAppend"),
		false,
		TEXT("Enable to force calls to IAssetRegistry::AppendState to happen on the game thread"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:79

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to force only searching for monolithic shader libs when possible"));

	static TAutoConsoleVariable<bool> CVarForceSyncLoadShaderLibrary(TEXT("GameFeaturePlugin.ForceSyncLoadShaderLibrary"),
		true,
		TEXT("Enable to force shaderlibs to be opened on the game thread"));

	static TAutoConsoleVariable<bool> CVarForceSyncAssetRegistryAppend(TEXT("GameFeaturePlugin.ForceSyncAssetRegistryAppend"),
		false,
		TEXT("Enable to force calls to IAssetRegistry::AppendState to happen on the game thread"));

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:1998

Scope (from outer to inner):

file
function     void UpdateState_MountPlugin

Source code excerpt:

		}

		if (!UseAsyncLoading() || UE::GameFeatures::CVarForceSyncLoadShaderLibrary.GetValueOnGameThread())
		{
			verify(IPluginManager::Get().MountExplicitlyLoadedPlugin(StateProperties.PluginName));
			if (!UE::GameFeatures::bDeferLocalizationDataLoad)
			{
				IPluginManager::Get().MountExplicitlyLoadedPluginLocalizationData(StateProperties.PluginName);
			}