Metal Shading Language Specification

1  Introduction 
This document describes the Metal Unified Graphics and Compute Language. Metal is a C++ 
based programming language that developers can use to write code that is executed on the 
GPU for graphics and general-purpose data-parallel computations. Since Metal is based on C+
+, developers will find it familiar and easy to use. With Metal, both graphics and compute 
programs can be written with a single, unified language, which allows tighter integration 
between the two.   
Metal is designed to work together with the Metal framework, which manages the execution, 
and optionally the compilation, of Metal code. Metal uses clang and LLVM so developers get a 
compiler that delivers close to the metal performance for code executing on the GPU. 
1.1  Audience 
Developers who are writing code with the Metal framework will want to read this document, 
because they will need to use the Metal shading language to write graphics and compute 
programs to be executed on the GPU.  
1.2  Organization of this Specification 
This document is organized into the following chapters: 
• This chapter, “Introduction,” is an introduction to this document and covers the 
similarities and differences between Metal and C++14.  
• “Data Types” lists the Metal data types, including types that represent vectors, matrices, 
buffers, textures, and samplers. It also discusses type alignment and type conversion. 
• “Operators” lists the Metal operators.  
• “Function and Variable Declarations” details how functions and variables are declared, 
sometimes with attributes that restrict how they are used. 
• “Metal Standard Library” defines a collection of built-in Metal functions. 
• “Compiler Options” details the options for the Metal compiler, including pre-processor 
directives, options for math intrinsics, and options that control optimization. 
• “Numerical Compliance” describes requirements for representing floating-point 
numbers, including accuracy in mathematical operations. 
1.3  References 
C++14 
Stroustrup, Bjarne. The C++ Programming Language (Fourth Edition). Harlow: Addison-Wesley, 
2013. 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
8
174

---

Metal 
An overview of the official Metal documentation is located here: 
https://developer.apple.com/documentation/metal 
1.4  Metal and C++14 
The Metal programming language is based on the C++14 Specification (a.k.a., the ISO/IEC 
JTC1/SC22/WG21 N4431 Language Specification) with specific extensions and restrictions. 
Please refer to the C++14 Specification for a detailed description of the language grammar.  
This section and its subsections describe modifications and restrictions to the C++14 language 
supported in Metal. 
For more information about Metal pre-processing directives and compiler options, see section 6 
of this document. 
1.4.1   
Overloading 
Metal supports overloading as defined by section 13 of the C++14 Specification. The function 
overloading rules are extended to include the address space attribute of an argument. Metal 
graphics and kernel functions cannot be overloaded. (For definition of graphics and kernel 
functions, see section 4.1 of this document.) 
1.4.2   
Templates 
Metal supports templates as defined by section 14 of the C++14 Specification. 
1.4.3   
Preprocessing Directives 
Metal supports the pre-processing directives defined by section 16 of the C++14 Specification. 
1.4.4   
Restrictions 
The following C++14 features are not available in Metal (section numbers in this list refer to the 
C++14 Specification):  
• lambda expressions (section 5.1.2) 
• dynamic_cast operator (section 5.2.7) 
• type identification (section 5.2.8) 
• recursive function calls (section 5.2.2, item 9) 
• new and delete operators (sections 5.3.4 and 5.3.5) 
• noexcept operator (section 5.3.7) 
• goto statement (section 6.6) 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
9
174

---

• register, thread_local storage attributes (section 7.1.1) 
• virtual function attribute (section 7.1.2) 
• derived classes (section 10, section 11) 
• exception handling (section 15)  
The C++ standard library must not be used in Metal code. Instead of the C++ standard library, 
Metal has its own standard library that is discussed in Chapter 5 of this document.  
Metal restricts the use of pointers: 
• Arguments to Metal graphics and kernel functions declared in a program that are 
pointers must be declared with the Metal 
device
, 
threadgroup
, 
threadgroup_imageblock
, or 
constant
 address space attribute. (See section 4.2 of 
this document for more about Metal address space attribute.) 
• Function pointers are not supported.  
A Metal function cannot be called 
main
. 
1.5  Metal Pixel Coordinate System 
In Metal, the origin of the pixel coordinate system of a framebuffer attachment is defined at the 
top left corner. Similarly, the origin of the pixel coordinate system of a framebuffer attachment is 
the top left corner. 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
10
174

---

2  Data Types 
This chapter details the Metal data types, including types that represent vectors and matrices. 
Atomic data types, buffers, textures, samplers, arrays, and user-defined structs are also 
discussed. Type alignment and type conversion are also described. 
2.1  Scalar Data Types 
Metal supports the scalar types listed in Table 1. Metal does not support the 
double
, 
long
, 
unsigned long
, 
long long
, 
unsigned long long
, and 
long double
 data types. 
Table 1 Metal Scalar Data Types  
Type
Description
bool
A conditional data type that has the value of either 
true
 or 
false
. 
The value 
true
 expands to the integer constant 1, and the value 
false
 expands to the integer constant 0.
char 
int8_t
A signed two’s complement 8-bit integer.
unsigned char 
uchar 
uint8_t
An unsigned 8-bit integer.
short 
int16_t
A signed two’s complement 16-bit integer.
unsigned short 
ushort 
unit16_t
An unsigned 16-bit integer.
int 
int32_t
A signed two’s complement 32-bit integer.
unsigned int 
uint 
uint32_t
An unsigned 32-bit integer.
half
A 16-bit floating-point. The half data type must conform to the 
IEEE 754 binary16 storage format.
float
A 32-bit floating-point. The float data type must conform to the 
IEEE 754 single precision storage format.
size_t
An unsigned integer type of the result of the 
sizeof
 operator. This 
is a 64-bit unsigned integer.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
11
174

---