MetalLanguageVersion

MetalLanguageVersion

#Overview

name: MetalLanguageVersion

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 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MetalLanguageVersion is to specify the Metal shader language version to be used when compiling shaders for Apple platforms (iOS and macOS) in Unreal Engine 5. This setting is crucial for the rendering system, particularly for projects targeting Metal-based graphics on Apple devices.

This setting variable is primarily relied upon by the Metal RHI (Runtime Hardware Interface) module, which is part of Unreal Engine’s rendering subsystem. It’s also used in the iOS and Mac target platform modules for build configuration.

The value of this variable is typically set in the project’s configuration files, specifically in the Engine.ini file. It can be modified through the project settings in the Unreal Editor, under the iOS or Mac platform settings in the “Rendering” category.

This variable interacts with other Metal-related settings, such as UseFastIntrinsics, which determines whether to use Metal’s fast intrinsics for shader compilation.

Developers must be aware that changing this variable requires a project restart to take effect, as indicated by the “ConfigRestartRequired” meta tag in the property declaration. Additionally, the chosen Metal language version affects shader compatibility and performance on different Apple devices, so it should be set carefully based on the target hardware and iOS/macOS versions.

Best practices when using this variable include:

  1. Setting it to the lowest version that supports all required features for your project to ensure maximum device compatibility.
  2. Testing thoroughly on various Apple devices to ensure shader compatibility and performance.
  3. Considering the target audience and minimum supported iOS/macOS versions when choosing the Metal language version.
  4. Documenting the chosen version and its implications for the project’s minimum system requirements.
  5. Regularly reviewing and updating this setting as the project evolves and new Metal features are required.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3028, section: [/Script/IOSRuntimeSettings.IOSRuntimeSettings]

Location: <Workspace>/Engine/Config/BaseEngine.ini:3172, section: [/Script/MacTargetPlatform.MacTargetSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSPlatformEditor/Private/IOSTargetSettingsCustomization.cpp:820

Scope (from outer to inner):

file
function     SETUP_SOURCEONLY_PROP

Source code excerpt:

    // Handle max. shader version a little specially.
    {
        ShaderVersionPropertyHandle = DetailLayout.GetProperty(GET_MEMBER_NAME_CHECKED(UIOSRuntimeSettings, MetalLanguageVersion));
		ShaderVersionPropertyHandle->SetOnPropertyValueChanged(OnUpdateShaderStandardWarning);
		
		// Drop-downs for setting type of lower and upper bound normalization
		IDetailPropertyRow& ShaderVersionPropertyRow = RenderCategory.AddProperty(ShaderVersionPropertyHandle.ToSharedRef());
		ShaderVersionPropertyRow.CustomWidget()
		.NameContent()

#Loc: <Workspace>/Engine/Source/Developer/Mac/MacTargetPlatform/Classes/MacTargetSettings.h:103

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

     */
    UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Metal Shader Standard To Target", ConfigRestartRequired = true))
    int32 MetalLanguageVersion;
    
    /**
     * Whether to use the Metal shading language's "fast" intrinsics.
	 * Fast intrinsics assume that no NaN or INF value will be provided as input, 
	 * so are more efficient. However, they will produce undefined results if NaN/INF 
	 * is present in the argument/s. By default fast-instrinics are disabled so Metal correctly handles NaN/INF arguments.

#Loc: <Workspace>/Engine/Source/Developer/Mac/MacTargetPlatform/Private/MacTargetPlatformModule.cpp:52

Scope (from outer to inner):

file
class        class FMacTargetPlatformModule : public ITargetPlatformModule
function     virtual void StartupModule

Source code excerpt:

        GConfig->GetArray(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("TargetedRHIs"), TargetSettings->TargetedRHIs, GEngineIni);
       
        if (!GConfig->GetInt(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("MetalLanguageVersion"), TargetSettings->MetalLanguageVersion, GEngineIni))
        {
            TargetSettings->MetalLanguageVersion = 0;
        }
        
		if (!GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("UseFastIntrinsics"), TargetSettings->UseFastIntrinsics, GEngineIni))
		{
			TargetSettings->UseFastIntrinsics = false;
		}

#Loc: <Workspace>/Engine/Source/Editor/DetailCustomizations/Private/MacTargetSettingsDetails.cpp:183

Scope (from outer to inner):

file
function     void FMacTargetSettingsDetails::CustomizeDetails

Source code excerpt:

    {
        IDetailCategoryBuilder& RenderCategory = DetailBuilder.EditCategory(TEXT("Rendering"));
        ShaderVersionPropertyHandle = DetailBuilder.GetProperty(TEXT("MetalLanguageVersion"));
		
		// Drop-downs for setting type of lower and upper bound normalization
		IDetailPropertyRow& ShaderVersionPropertyRow = RenderCategory.AddProperty(ShaderVersionPropertyHandle.ToSharedRef());
		ShaderVersionPropertyRow.CustomWidget()
		.NameContent()
		[

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalCommandQueue.cpp:52

Scope: file

Source code excerpt:

	const TCHAR* const Settings = TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings");
#endif
    GConfig->GetInt(Settings, TEXT("MetalLanguageVersion"), MetalShaderVersion, GEngineIni);
	
    if(!GConfig->GetInt(Settings, TEXT("IndirectArgumentTier"), IndirectArgumentTier, GEngineIni))
	{
		IndirectArgumentTier = 0;
	}
	ValidateVersion(MetalShaderVersion);

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:461

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

    // The Metal shader language version which will be used when compiling the shaders.
    UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Metal Shader Standard To Target", ConfigRestartRequired = true))
	uint8 MetalLanguageVersion;
	
	/**
	 * Whether to use the Metal shading language's "fast" intrinsics.
	 * Fast intrinsics assume that no NaN or INF value will be provided as input,
	 * so are more efficient. However, they will produce undefined results if NaN/INF
	 * is present in the argument/s.

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

Scope (from outer to inner):

file
function     uint32 RHIGetMetalShaderLanguageVersion

Source code excerpt:

            if (MacMetalShaderLanguageVersion == -1)
            {
                if (!GConfig->GetInt(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("MetalLanguageVersion"), MacMetalShaderLanguageVersion, GEngineIni))
                {
                    MacMetalShaderLanguageVersion = 0; // 0 means default EMacMetalShaderStandard::MacMetalSLStandard_Minimum
                }
            }
            return MacMetalShaderLanguageVersion;
		}

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

Scope (from outer to inner):

file
function     uint32 RHIGetMetalShaderLanguageVersion

Source code excerpt:

            if (IOSMetalShaderLanguageVersion == -1)
            {
                if (!GConfig->GetInt(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("MetalLanguageVersion"), IOSMetalShaderLanguageVersion, GEngineIni))
                {
                	IOSMetalShaderLanguageVersion = 0;  // 0 means default EIOSMetalShaderStandard::IOSMetalSLStandard_Minimum
                }
            }
            return IOSMetalShaderLanguageVersion;
        }