UseFastIntrinsics

UseFastIntrinsics

#Overview

name: UseFastIntrinsics

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 UseFastIntrinsics is to enable or disable the use of fast-math intrinsics in shader compilation for Metal-based platforms (Mac and iOS). This setting is primarily related to the rendering system and shader compilation process in Unreal Engine 5.

The UseFastIntrinsics variable is used in the MacTargetPlatform and IOSRuntimeSettings modules, which are responsible for platform-specific configurations for macOS and iOS targets, respectively. It’s also referenced in the ShaderCompiler and RenderCore modules, which are core components of Unreal Engine’s rendering system.

The value of this variable is set in the project’s configuration files (GEngineIni) and can be modified through the project settings in the Unreal Engine editor. It’s typically read from the configuration at runtime or during shader compilation.

This variable interacts with other rendering-related settings, such as EnableMathOptimisations and ForceFloats. These settings collectively influence how shaders are compiled and optimized for Metal-based platforms.

Developers should be aware that enabling UseFastIntrinsics can improve shader performance but may come at the cost of reduced precision in floating-point calculations. This can potentially lead to visual artifacts or inconsistencies in rendering, especially in cases where precise floating-point computations are crucial.

Best practices when using this variable include:

  1. Testing thoroughly on target devices to ensure that enabling fast intrinsics doesn’t introduce visual artifacts or unexpected behavior in your game.
  2. Consider disabling UseFastIntrinsics for projects that require high precision in shader calculations, such as scientific visualizations or certain types of simulations.
  3. Use this setting in conjunction with other shader optimization settings to find the right balance between performance and precision for your specific project needs.
  4. Be cautious when enabling this for cross-platform projects, as it may lead to different visual results between platforms that support fast intrinsics and those that don’t.
  5. Document the use of this setting in your project, as it can affect the reproducibility of rendering results across different builds or platforms.

#Setting Variables

#References In INI files

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

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

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

     */
    UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Use Fast-Math intrinsics", ConfigRestartRequired = true))
	bool UseFastIntrinsics;
	
	/**
	 * Whether to use of Metal shader-compiler's -ffast-math optimisations.
	 * Fast-Math performs algebraic-equivalent & reassociative optimisations not permitted by the floating point arithmetic standard (IEEE-754).
	 * These can improve shader performance at some cost to precision and can lead to NaN/INF propagation as they rely on
	 * shader inputs or variables not containing NaN/INF values. By default fast-math is enabled for performance.

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

Scope (from outer to inner):

file
class        class FMacTargetPlatformModule : public ITargetPlatformModule
function     virtual void StartupModule

Source code excerpt:

        }
        
		if (!GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("UseFastIntrinsics"), TargetSettings->UseFastIntrinsics, GEngineIni))
		{
			TargetSettings->UseFastIntrinsics = false;
		}
		
		if (!GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("EnableMathOptimisations"), TargetSettings->EnableMathOptimisations, GEngineIni))
		{
			TargetSettings->EnableMathOptimisations = true;
		}

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

			if (IsPCPlatform(EShaderPlatform(Target.Platform)))
			{
				GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("UseFastIntrinsics"), bAllowFastIntrinsics, GEngineIni);
				GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("EnableMathOptimisations"), bEnableMathOptimisations, GEngineIni);
				GConfig->GetInt(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("IndirectArgumentTier"), IndirectArgumentTier, GEngineIni);
                
                // No half precision support on MacOS at the moment
                bForceFloats = true;
			}
			else
			{
				GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("UseFastIntrinsics"), bAllowFastIntrinsics, GEngineIni);
				GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("EnableMathOptimisations"), bEnableMathOptimisations, GEngineIni);
				GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("ForceFloats"), bForceFloats, GEngineIni);
				GConfig->GetInt(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("IndirectArgumentTier"), IndirectArgumentTier, GEngineIni);
                GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bSupportAppleA8"), bSupportAppleA8, GEngineIni);
                
				// Force no development shaders on iOS

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

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Use Fast-Math intrinsics", ConfigRestartRequired = true))
	bool UseFastIntrinsics;
	
	/**
	 * Whether to force Metal shaders to use 32bit floating point precision even when the shader uses half floats.
	 * Half floats are much more efficient when they are availble but have less accuracy over large ranges,
	 * as such some projects may need to use 32bit floats to ensure correct rendering.
	 */

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

		if (IsPCPlatform(Platform))
		{
			GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("UseFastIntrinsics"), bAllowFastIntrinsics, GEngineIni);
			GConfig->GetBool(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("EnableMathOptimisations"), bEnableMathOptimisations, GEngineIni);
			GConfig->GetInt(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("IndirectArgumentTier"), IndirectArgumentTier, GEngineIni);
		}
		else
		{
			GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("UseFastIntrinsics"), bAllowFastIntrinsics, GEngineIni);
			GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("EnableMathOptimisations"), bEnableMathOptimisations, GEngineIni);
			GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("ForceFloats"), bForceFloats, GEngineIni);
			GConfig->GetInt(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("IndirectArgumentTier"), IndirectArgumentTier, GEngineIni);
            GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bSupportAppleA8"), bSupportAppleA8, GEngineIni);
		}