Metal Shading Language Specification

5  Metal Standard Library  
This chapter describes the functions supported by the Metal standard library.  
5.1  Namespace and Header Files 
The Metal standard library functions and enums are declared in the 
metal
 namespace. In 
addition to the header files described in the Metal standard library functions, the 

 header is available and can access all the functions supported by the Metal 
standard library. 
5.2  Common Functions 
The functions in Table 16 are in the Metal standard library and are defined in the header 

. 
T
 is one of the scalar or vector floating-point types.  
Table 16 Common Functions in the Metal Standard Library 
Built-in common functions
Description
T clamp(T x, T minval, T maxval) 
Returns 
fmin(fmax(x, minval), maxval)
. 


Results are undefined if 
minval > maxval
.
T mix(T x, T y, T a)  
 
Returns the linear blend of 
x
 and 
y
 implemented 
as: 
x + (y – x ) * a
 
a
 must be a value in the range 0.0 to 1.0. If 
a
 is 
not in the range 0.0 to 1.0, the return values are 
undefined.
T saturate(T x)
Clamp the specified value within the range of 
0.0 to 1.0.
T sign(T x)
Returns 1.0 if 
x > 0
, -0.0 if 
x = -0.0
, +0.0 if 
x 
= +0.0
, or -1.0 if 
x < 0
. Returns 0.0 if x is a 
NaN.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
107
174

---

For single precision floating-point, Metal also supports a precise and fast variant of the 
following common functions: 
clamp
 and 
saturate
. The difference between the fast and 
precise variants is how NaNs are handled. In the fast variant, the behavior of NaNs is undefined 
whereas the precise variants follow the IEEE 754 rules for NaN handling. 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 common functions.  
5.3  Integer Functions 
The integer functions in Table 17 are in the Metal standard library and are defined in the header 

. 
T
 is one of the scalar or vector integer types. 
T
u
 is the corresponding 
unsigned scalar or vector integer type. 
Table 17 Integer Functions in the Metal Standard Library 
T smoothstep(T edge0, T edge1, T 
x) 
 
Returns 0.0 if 
x <= edge0
 and 1.0 if 
x >= 
edge1
 and performs a smooth Hermite 
interpolation between 0 and 1 when 
edge0 < x 
< edge1
. This is useful in cases where you want 
a threshold function with a smooth transition. 
This is equivalent to: 
t = clamp((x – edge0)/(edge1 – edge0), 
0, 1); 
return t * t * (3 – 2 * t);
 
Results are undefined if 
edge0 >= edge1
 or if 
x, edge0 or edge1 is a NaN.
T step(T edge, T x)
Returns 0.0 if 
x < edge
, otherwise it return 1.0.
Built-in common functions
Description
Built-in integer functions
Description
T abs(T x)
Returns 
|x|
.
T
u
 absdiff(T x, T y)
Returns 
|x–y|
 without modulo overflow.
T addsat(T x, T y)
Returns 
x + y
 and saturates the result.
T clamp(T x, T minval, T maxval) 
Returns 
min(max(x, minval), maxval)
. 


Results are undefined if 
minval > maxval
.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
108
174

---

T clz(T x)
Returns the number of leading 0-bits in 
x
, 
starting at the most significant bit position. If 
x
 
is 0, returns the size in bits of the type of x or 
component type of 
x
, if 
x
 is a vector
T ctz(T x)
Returns the count of trailing 0-bits in 
x
. If 
x
 is 0, 
returns the size in bits of the type of x or 
component type of 
x
, if 
x
 is a vector.
T extract_bits(T x, uint offset, 
uint bits) 
       
Extract bits [
offset
, 
offset+bits-1
] from 
x
, 
returning them in the least significant bits of the 
result. 
For unsigned data types, the most significant 
bits of the result are set to zero. For signed data 
types, the most significant bits are set to the 
value of bit 
offset+bits-1
. 
If 
bits
 is zero, the result is zero. The result is 
undefined if the sum of 
offset
 and 
bits
 is 
greater than the number of bits used to store 
the operand.
T hadd(T x, T y)
Returns 
(x + y) >> 1
. The intermediate sum 
does not modulo overflow.
T insert_bits(T base, T insert, 
uint offset, uint bits) 
       
Returns the insertion of the 
bits
 least-
significant bits of 
insert
 into 
base
. 
The result will have bits [
offset
, 
offset+bits-1
] taken from bits [
0
, 
bits-1
] of 
insert
, and all other bits taken directly from 
the corresponding bits of 
base
. If 
bits
 is zero, 
the result is 
base
. The result is undefined if the 
sum of 
offset
 and 
bits
 is greater than the 
number of bits used to store the operand.
T madhi(T a, T b, T c)
Returns 
mulhi(a, b) + c
.
T madsat(T a, T b, T c)
Returns 
a * b + c
 and saturates the result.
T max(T x, T y) 
Returns 
y
 if 
x < y
, otherwise it returns 
x
.
T min(T x, T x) 
Returns 
y
 if 
y < x
, otherwise it returns 
x
.
T mulhi(T x, T y)
Computes 
x * y
 and returns the high half of 
the product of 
x
 and 
y
.
T popcount(T x)
Returns the number of non-zero bits in 
x
.
Built-in integer functions
Description
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
109
174

---