bSharedMaterialNativeLibraries

bSharedMaterialNativeLibraries

#Overview

name: bSharedMaterialNativeLibraries

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bSharedMaterialNativeLibraries is to control whether material shaders are compiled and packaged as shared native libraries for certain platforms, particularly for Metal-based platforms like iOS and macOS.

This setting variable is primarily used in the shader compilation and packaging systems of Unreal Engine. It affects how shaders are compiled, packaged, and potentially stripped for Metal-based platforms.

The value of this variable is set in the project’s packaging settings, specifically in the ProjectPackagingSettings section of the game’s INI file.

This variable interacts with other shader compilation and packaging flags, particularly the CFLAG_Archive compiler flag for Metal shaders.

Developers must be aware that:

  1. This setting affects shader compilation for Metal platforms.
  2. It can impact the size and structure of the final packaged game.
  3. It may affect runtime shader loading and performance on Metal platforms.

Best practices when using this variable include:

  1. Only enable it when targeting Metal platforms that benefit from shared material libraries.
  2. Consider the trade-offs between package size, load time, and runtime performance when enabling this option.
  3. Test thoroughly on target platforms to ensure shader compatibility and performance when changing this setting.
  4. Coordinate with the entire development team when modifying this setting, as it can affect both engine and game-specific shader code.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseGame.ini:112, section: [/Script/UnrealEd.ProjectPackagingSettings]

Location: <Workspace>/Projects/Lyra/Config/DefaultGame.ini:121, section: [/Script/UnrealEd.ProjectPackagingSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h:445

Scope (from outer to inner):

file
class        class UProjectPackagingSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(config, EditAnywhere, Category=Packaging, meta = (EditCondition = "bShareMaterialShaderCode", ConfigRestartRequired = true))
	bool bSharedMaterialNativeLibraries;

	/** A directory containing additional prerequisite packages that should be staged in the executable directory. Can be relative to $(EngineDir) or $(ProjectDir) */
	UPROPERTY(config, EditAnywhere, Category=Prerequisites, AdvancedDisplay)
	FDirectoryPath ApplocalPrerequisitesDirectory;

	/**

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Commandlets/ShaderCodeLibraryToolsCommandlet.cpp:39

Scope (from outer to inner):

file
function     int32 UShaderCodeLibraryToolsCommandlet::StaticMain

Source code excerpt:

		
		bool bArchive = false;
		if (GConfig->GetBool(TEXT("/Script/UnrealEd.ProjectPackagingSettings"), TEXT("bSharedMaterialNativeLibraries"), bArchive, GGameIni))
		{
			bNativeFormat |= bArchive;
		}

		bool bNeedsDeterministicOrder = false;
		GConfig->GetBool(TEXT("/Script/UnrealEd.ProjectPackagingSettings"), TEXT("bDeterministicShaderCodeOrder"), bNeedsDeterministicOrder, GGameIni);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/CookOnTheFlyServer.cpp:9483

Scope (from outer to inner):

file
function     void UCookOnTheFlyServer::BeginCookStartShaderCodeLibrary

Source code excerpt:

	if (bCacheShaderLibraries)
	{
		FShaderLibraryCooker::InitForCooking(PackagingSettings->bSharedMaterialNativeLibraries);

		bool bAllPlatformsNeedStableKeys = false;
		// support setting without Hungarian prefix for the compatibility, but allow newer one to override
		GConfig->GetBool(TEXT("DevOptions.Shaders"), TEXT("NeedsShaderStableKeys"), bAllPlatformsNeedStableKeys, GEngineIni);
		GConfig->GetBool(TEXT("DevOptions.Shaders"), TEXT("bNeedsShaderStableKeys"), bAllPlatformsNeedStableKeys, GEngineIni);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:8217

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

		// Shaders built for archiving - for Metal that requires compiling the code in a different way so that we can strip it later
		bool bArchive = false;
		GConfig->GetBool(TEXT("/Script/UnrealEd.ProjectPackagingSettings"), TEXT("bSharedMaterialNativeLibraries"), bArchive, GGameIni);
		if (bCanCompileOfflineMetalShaders && bArchive)
		{
			Input.Environment.CompilerFlags.Add(CFLAG_Archive);
		}
		
		{

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:1851

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

		// Shaders built for archiving - for Metal that requires compiling the code in a different way so that we can strip it later
		bool bArchive = false;
		GConfig->GetBool(TEXT("/Script/UnrealEd.ProjectPackagingSettings"), TEXT("bSharedMaterialNativeLibraries"), bArchive, GGameIni);
		if (bArchive)
		{
			KeyString += TEXT("_ARCHIVE");
		}
	}