Metal Shader Compiler Options

Compiler Options

Typically you compile Metal shaders offline by adding Metal shader source files to your Xcode project. Xcode compiles the shader source using the metal command-line tool, producing binaries that your app loads using APIs from the MTLLibrary class. You can also use the Metal compiler online—compiling Metal shader source during the run time of your app—using other MTLLibrary APIs.

When using the offline metal compiler, you can use the option flags listed in this chapter to control preprocessor behavior, choose math functions in the standard library, and request other options. When using the online Metal compiler, you can control a subset of these options using the MTLCompileOptions class.

Preprocessor Options

These options control the Metal preprocessor that is run on each shader source file before compilation.

-D  name

Predefines name as a macro, with definition 1. Equivalent to #define name 1 in shader source.

-D  name=definition

Tokenizes and processes the contents of definition as if they appeared in a #define directive in shader source. This option may receive multiple options, which are processed in the order in which they appear.

You can use this option to change which features of a shader are enabled or disabled.

-I  dir

Adds the directory dir to the list of directories to be searched for header files. This option is available only for the offline compiler.

Math Intrinsics Options

These options control compiler behavior regarding floating-point arithmetic. These options allow you to make trade-offs between speed and correctness.

-ffast-math

This (default) option enables optimizations for floating-point arithmetic that may violate the IEEE 754 standard. It also disables the high-precision variant of math functions for single-precision floating-point scalar and vector types. -ffast-math is the default.

-fno-fast-math

This option is the opposite of -ffast-math. It disables the optimizations for floating-point arithmetic that may violate the IEEE 754 standard. It also enables the high-precision variant of math functions for single-precision floating-point scalar and vector types.

The optimizations for floating-point arithmetic enabled by -ffast-math include:

• No NaNs – Allow optimizations to assume the arguments and result are not NaN.

• No INFs – Allow optimizations to assume the arguments and result are not positive or negative infinity.

• No Signed Zeroes – Allow optimizations to treat the sign of zero argument or result as insignificant.

• Allow Reciprocal – Allow optimizations to use the reciprocal of an argument rather than perform division.

• Fast – Allow algebraically equivalent transformations; that is, re-associate floating-point operations that may dramatically change results in floating-point.

The Metal standard library provides both fast and precise variants of math functions in the the metal::precise and metal::fast nested namespaces. When -ffast-math is specified, these functions use the fast variants by default (and you can call a function with the precise:: prefix to use the precise variant instead). When -fno-fast-math is specified, functions use the precise variants by default (and you can call a function with the fast:: prefix to use the fast variant instead). See Listing 5-1 for examples.

Options Controlling the Language Version

The following option controls the version of unified graphics/compute language that the compiler accepts.

-std=

Determine the language revision to use, which must be one of the following values:

• ios-metal1.0 – support the unified graphics / compute language revision 1.0 programs for iOS 8.0.

• ios-metal1.1 – support the unified graphics / compute language revision 1.1 programs for iOS 9.0.

• osx-metal1.1 – support the unified graphics / compute language revision 1.1 programs for OS X.

Options to Request or Suppress Warnings

The following options are available:

-Werror

Make all warnings into errors.

-W

Inhibit all warning messages.

Next Previous