EnableMathOptimisations

EnableMathOptimisations

#Overview

name: EnableMathOptimisations

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 EnableMathOptimisations is to control whether fast-math optimizations are enabled for shader compilation on Mac and iOS platforms in Unreal Engine 5.

This setting variable is primarily used by the rendering system, specifically in the shader compilation process. It is relied upon by the MacTargetPlatform and IOSRuntimeSettings modules, which are responsible for platform-specific configurations for Mac and iOS, respectively.

The value of this variable is set in the project’s configuration files (e.g., Engine.ini) and can be modified through the project settings in the Unreal Editor. It is defined as a boolean property in both UMacTargetSettings and UIOSRuntimeSettings classes.

EnableMathOptimisations interacts with other rendering-related variables such as UseFastIntrinsics, ForceFloats, and IndirectArgumentTier. These variables collectively influence how shaders are compiled for the target platforms.

Developers must be aware that enabling this option can potentially affect the precision of mathematical operations in shaders. While it can improve performance, it may lead to slight differences in rendering output compared to when the option is disabled.

Best practices when using this variable include:

  1. Testing thoroughly on target devices to ensure that enabling math optimizations doesn’t introduce visual artifacts or unintended behavior.
  2. Considering the trade-off between performance gains and potential precision loss.
  3. Documenting the use of this setting in project guidelines to ensure consistency across the development team.
  4. Being cautious when using this option for games that require high precision in their rendering calculations.

It’s also important to note that changes to this setting require a restart of the engine to take effect, as indicated by the “ConfigRestartRequired = true” meta tag in the property definition.

#Setting Variables

#References In INI files

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

Location: <Workspace>/Engine/Config/BaseEngine.ini:3175, 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:121

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Enable Fast-Math optimisations", ConfigRestartRequired = true))
	bool EnableMathOptimisations;
	
	/** Whether to compile shaders using a tier Indirect Argument Buffers. */
	UPROPERTY(config, EditAnywhere, Category = Rendering, Meta = (DisplayName = "Tier of Indirect Argument Buffers to use when compiling shaders", ConfigRestartRequired = true))
	int32 IndirectArgumentTier;

	/** Sample rate to run the audio mixer with. */

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

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("EnableMathOptimisations"), TargetSettings->EnableMathOptimisations, GEngineIni))
		{
			TargetSettings->EnableMathOptimisations = true;
		}
		
		if (!GConfig->GetInt(TEXT("/Script/MacTargetPlatform.MacTargetSettings"), TEXT("IndirectArgumentTier"), TargetSettings->IndirectArgumentTier, GEngineIni))
		{
			TargetSettings->IndirectArgumentTier = 0;
		}

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

			{
				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
				bAllowDevelopmentShaderCompile = false;

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

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(EditAnywhere, config, Category=Rendering, meta = (DisplayName = "Enable Fast-Math optimisations", ConfigRestartRequired = true))
	bool EnableMathOptimisations;
	
	/** Whether to compile shaders using a tier Indirect Argument Buffers. */
	UPROPERTY(config, EditAnywhere, Category = Rendering, Meta = (DisplayName = "Tier of Indirect Argument Buffers to use when compiling shaders", ConfigRestartRequired = true))
	int32 IndirectArgumentTier;
	
    /** Supports Apple A8 devices.

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

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

		{
			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);
		}
		
		if (bAllowFastIntrinsics)