Metal Shading Language Specification

Where 
n
 and 
m
 are numbers of columns and rows. 
n
 and 
m
 must be 2, 3, or 4. A matrix of type 
floatnxm
 is composed of 
n
 
floatm
 vectors. Similarly, a matrix of type 
halfnxm
 is composed of 
n
 
halfm
 vectors. 
Table 5 lists the size and alignment of the matrix data types. 
Table 5 Size and Alignment of Matrix Data Types 
2.3.1   
Accessing Matrix Components 
The components of a matrix can be accessed using the array subscripting syntax. Applying a 
single subscript to a matrix treats the matrix as an array of column vectors. The top column is 
column 0. A second subscript would then operate on the resulting vector, as defined earlier for 
vectors. Hence, two subscripts select a column and then a row. 
Type
Size (in bytes)
Alignment (in bytes)
half2x2
8
4
half2x3
16
8
half2x4
16
8
half3x2
12
4
half3x3
24
8
half3x4
24
8
half4x2
16
4
half4x3
32
8
half4x4
32
8
float2x2
16
8
float2x3
32
16
float2x4
32
16
float3x2
24
8
float3x3
48
16
float3x4
48
16
float4x2
32
8
float4x3
64
16
float4x4
64
16
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
20
174

---

float4x4 m; 
// sets the 2nd column to all 2.0 
m[1] = float4(2.0f); 
// sets the 1st element of the 1st column to 1.0 
m[0][0] = 1.0f; 
// sets the 4th element of the 3rd column to 3.0 
m[2][3] = 3.0f; 
The 
floatnxm
 and 
halfnxm
 matrices can be accessed as an array of 
n floatm
 or 
n halfm
 
entries. 
Accessing a component outside the bounds of a matrix with a non-constant expression results 
in undefined behavior. Accessing a matrix component that is outside the bounds of the matrix 
with a constant expression generates a compile-time error. 
2.3.2   
Matrix Constructors 
Constructors can be used to create matrices from a set of scalars, vectors or matrices. When a 
matrix is initialized, its parameter signature determines how it is constructed. For example, if a 
matrix is initialized with only a single scalar parameter, the result is a matrix that contains that 
scalar for all components of the matrix’s diagonal, with the remaining components initialized to 
0.0. For example, a call to: 
float4x4(fval); 
where 
fval
 is a scalar floating-point value constructs a matrix with these initial contents: 
fval  0.0  0.0  0.0 
0.0  fval  0.0  0.0 
0.0  0.0  fval  0.0 
0.0  0.0  0.0  fval 
A matrix can also be constructed from another matrix that is of the same size; i.e., has the same 
number of rows and columns. For example,  
float3x4(float3x4); 
float3x4(half3x4); 
Matrix components are constructed and consumed in column-major order. The matrix 
constructor must have just enough values specified in its arguments to initialize every 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
21
174

---

component in the constructed matrix object. Providing more arguments than necessary results 
in an error. Under-initializing a matrix constructor results in a compile-time error. 
A matrix of type 
T
 with 
n
 columns and 
m
 rows can also be constructed from 
n
 vectors of type 
T
 
with 
m
 components. The following examples are legal constructors: 
float2x2(float2, float2); 
float3x3(float3, float3, float3); 
float3x2(float2, float2, float2); 
A matrix of type 
T
 with 
n
 columns and 
m
 rows can also be constructed from 
n * m
 scalars of  
type 
T
. The following examples are legal constructors: 
float2x2(float, float, float, float); 
float3x2(float, float, float, float, float, float);
 
The following are examples of matrix constructors that are not supported. A matrix cannot be 
constructed from combinations of vectors and scalars.  
// not supported 
float2x3(float2 a, float b, float2 c, float d); 
2.4  Alignment of Data Types 
The 
alignas
 alignment specifier can be used to specify the alignment requirement of a type or 
an object. The 
alignas
 specifier may be applied to the declaration of a variable or a data 

member of a struct or class. It may also be applied to the declaration of a struct, class, or 
enumeration type.  
The Metal compiler is responsible for aligning data items to the appropriate alignment as 

required by the data type. For arguments to a graphics or kernel function declared to be a 
pointer to a data type, the Metal compiler can assume that the pointee is always appropriately 
aligned as required by the data type.  
2.5  Atomic Data Types 
Objects of atomic types are the only Metal shading language objects that are free from data 
races. If one thread writes to an atomic object while another thread reads from it, the behavior is 
well-defined.  
For all versions of Metal, these atomic types are supported: 
atomic_int 
atomic_uint 
For 
ios-metal2.0
, these atomic types are also supported 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
22
174

---