Metal Shading Language Specification

For single precision floating-point, Metal supports two variants of the math functions listed in 
Table 19: the precise and the fast variants. The 
ffast-math
 compiler option (refer to section 
6.2) is used to select the appropriate variant when compiling the Metal source. In addition, the 
metal::precise
 and 
metal::fast
 nested namespaces are also available and provide 
developers a way to explicitly select the fast or precise variant of these math functions for single 
precision floating-point.  
Examples: 
float x; 
T modf(T x, T &intval)
Decompose a floating-point number. The modf 
function breaks the argument x into integral and 
fractional parts each of which has the same 
sign as the argument. 
Returns the fractional value. The integral value 
is returned in intval.
T pow(T x, T y)
Compute x to the power y.
T powr(T x, T y)
Compute x to the power y, where x is >= 0.
T rint(T x)
Round to integral value using round to nearest 
even rounding mode in floating-point format.
T round(T x)
Return the integral value nearest to x rounding 
halfway cases away from zero.
T rsqrt(T x)
Compute inverse square root.
T sin(T x)
Compute sine.
T sincos(T x, T &cosval)
Compute sine and cosine of x. The computed 
sine is the return value and compute cosine is 
returned in cosval.
T sinh(T x)
Compute hyperbolic sine.
T sinpi(T x)
Compute 
sin(πx)
.
T sqrt(T x)
Compute square root.
T tan(T x)
Compute tangent.
T tanh(T x)
Compute hyperbolic tangent.
T tanpi(T x)
Compute 
tan(πx)
.
T trunc(T x)
Round to integral value using the round to zero 
rounding mode.
Built-in math functions
Description
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
113
174

---

float a = sin(x); // use fast or precise version of sin based on  
  // whether –ffast-math is specified as  
  // compile option. 
float b = fast::sin(x); // use fast version of sin() 
float c = precise::cos(x); // use precise version of cos() 
Table 20 lists available symbolic constants with values of type 
float
 that are accurate  
within the precision of a single-precision floating-point number.  
Table 20 Constants for Single-Precision Floating-Point Math Functions 
Table 21 lists available symbolic constants with values of type 
half
 that are accurate within the 
precision of a half-precision floating-point number.  
Constant name Description
MAXFLOAT
Value of maximum non-infinite single precision floating-point number.   
HUGE_VALF
A positive float constant expression. 
HUGE_VALF
 evaluates to +infinity.
INFINITY
A constant expression of type float representing positive or unsigned 
infinity.
NAN
A constant expression of type float representing a quiet NaN.
M_E_F
Value of e
M_LOG2E_F
Value of log
2
e
M_LOG10E_F
Value of log
10
e
M_LN2_F
Value of log
e
2
M_LN10_F
Value of loge10
M_PI_F
Value of π
M_PI_2_F
Value of π / 2
M_PI_4_F
Value of π / 4
M_1_PI_F
Value of 1 / π
M_2_PI_F
Value of 2 / π
M_2_SQRTPI_F
Value of 2 / √π
M_SQRT2_F
Value of √2
M_SQRT1_2_F
Value of 1 / √2
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
114
174

---

Table 21 Constants for Half-Precision Floating-Point Math Functions 
5.6  Matrix Functions 
The functions in Table 22 are in the Metal standard library and are defined in the header 

. 
T
 is 
float
 or 
half
. 
Table 22 Matrix Functions in the Metal Standard Library 
Example: 
Constant name Description
MAXHALF
Value of maximum non-infinite half precision floating-point number.   
HUGE_VALH
A positive half constant expression. 
HUGE_VALH
 evaluates to +infinity.
M_E_H
Value of e
M_LOG2E_H
Value of log
2
e
M_LOG10E_H
Value of log
10
e
M_LN2_H
Value of log
e
2
M_LN10_H
Value of loge10
M_PI_H
Value of π
M_PI_2_H
Value of π / 2
M_PI_4_H
Value of π / 4
M_1_PI_H
Value of 1 / π
M_2_PI_H
Value of 2 / π
M_2_SQRTPI_H
Value of 2 / √π
M_SQRT2_H
Value of √2
M_SQRT1_2_H
Value of 1 / √2
Built-in matrix functions
Description
float determinant(floatnxn) 
half determinant(halfnxn) 
Compute the determinant of the matrix. The 
matrix must be a square matrix.
floatmxn transpose(floatnxm) 
halfmxn transpose(halfnxm)
Transpose a matrix.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
115
174

---

float4x4 mA; 
float det = determinant(mA); 
5.7  Geometric Functions 
The functions in Table 23 are in the Metal standard library and are defined in the header 

. 
T
 is a vector floating-point type (
floatn
 or 
halfn
). 
T
s
 refers to the 
corresponding scalar type (i.e., 
float
 if 
T
 is 
floatn
 and 
half
 if 
T
 is 
halfn
).  
Table 23 Geometric Functions in the Metal Standard Library 
Built-in geometric functions
Description
T cross(T x, T y) 
Return the cross product of 
x
 and 
y
. 

T
 must be a 3-component vector type.
T
s
 distance(T x, T y) 
Return the distance between 
x
 and 
y
, i.e., 
length(x-y)
T
s
 distance_squared(T x, T y) 
Return the square of the distance between 
x
 
and 
y
.
T
s
 dot(T x, T y)
Return the dot product of 
x
 and 
y
, i.e., 
x[0] * 
y[0] + x[1] * y[1] + …
T faceforward(T N, T I, T Nref)
If 
dot(Nref, I) < 0.0
 return 
N
, otherwise 
return 
–N
.
T
s
 length(T x)
Return the length of vector 
x
, i.e., 
sqrt(x[0]
2
 
+ x[1]
2
 + …)
T
s
 length_squared(T x)
Return the square of the length of vector x, i.e., 
(x[0]
2
 + x[1]
2
 + …)
T normalize(T x)
Returns a vector in the same direction as 
x
 but 
with a length of 1.
T reflect(T I, T N) 
For the incident vector 
I
 and surface orientation 
N
, returns the reflection direction: 
I – 2 * 
dot(N, I) * N
 
In order to achieve the desired result, 
N
 must be 
normalized.
T refract(T I, T N, T
s
 eta)
For the incident vector 
I
 and surface normal 
N
, 
and the ratio of indices of refraction 
eta
, return 
the refraction vector. 
The input parameters for the incident vector 
I
 
and the surface normal 
N
 must already be 
normalized to get the desired results.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
116
174

---