Metal Shading Language Specification

Examples: 
void foo (texture2d imgA [[texture(0)]],  
     texture2d imgB [[texture(1)]], 
texture2d imgC [[texture(2)]])  
{ 
    texture2d x = imgA; // legal  
    texture2d y = imgB; // legal 
    texture2d z; // illegal 
    … 
} 
2.9  Samplers 
The 
sampler
 type identifies how to sample a texture. The Metal API allows you to create a 
sampler object and pass it in an argument to a graphics or kernel function. A sampler object can 
also be described in the program source instead of in the API. For these cases we only allow a 
subset of the sampler state to be specified: the addressing mode, filter mode, normalized 
coordinates and comparison function. 
Table 7 describes the list of supported sampler state enums and their associated values (and 
defaults). These states can be specified when a sampler is initialized in Metal program source. 
Table 7 Sampler State Enumeration Values 
Enum Name
Valid Values
Description
coord
normalized 
(default)
 
pixel
Specifies whether the texture coordinates 
when sampling from a texture are 
normalized or unnormalized values. 
address
repeat 
mirrored_repeat 
clamp_to_edge 
(default)
 
clamp_to_zero  
clamp_to_border
Sets the addressing mode for all texture 
coordinates. 
s_address 
t_address 
r_address
repeat 
mirrored_repeat 
clamp_to_edge 
(default)
 
clamp_to_zero  
clamp_to_border
Sets the addressing mode for individual 
texture coordinates. 
filter
nearest 
(default)
 
linear
Sets the magnification and minification 
filtering modes for texture sampling.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
27
174

---

clamp_to_border
 is only available on macOS. With 
clamp_to_border
, sampling outside a 
texture only uses the border color for the texture coordinate (and does not use any colors at the 
edge of the texture). 
clamp_to_zero
 is equivalent to 
clamp_to_border
 with a border color of 
transparent_black
 
(0.0, 0.0, 0.0) with the alpha component value from the texture. If 
clamp_to_zero
 is specified 
as the address mode for one or more texture coordinates, the other texture coordinates can use 
an address mode of 
clamp_to_border
 if and only if the border color is 
transparent_black
. 
Otherwise the behavior is undefined.  
The enumeration types used by the sampler data type as described in Table 7 are specified as 
follows: 
enum class coord   
{ normalized, pixel }; 
enum class filter  
{ nearest, linear }; 
enum class min_filter   { nearest, linear }; 
enum class mag_filter   { nearest, linear }; 
enum class mip_filter   { none, nearest, linear }; 
enum class s_address   { clamp_to_zero, clamp_to_edge, clamp_to_border 
    repeat, mirrored_repeat }; 
enum class t_address   { clamp_to_zero, clamp_to_edge, clamp_to_border 
    repeat, mirrored_repeat }; 
enum class r_address   { clamp_to_zero, clamp_to_edge, clamp_to_border  
mag_filter
nearest 
(default)
 
linear 
Sets the magnification filtering mode for 
texture sampling. 
min_filter
nearest 
(default)
 
linear
Sets the minification filtering mode for 
texture sampling. 
mip_filter
none 
(default)
 
nearest 
linear
Sets the mipmap filtering mode for texture 
sampling. If 
none
, then only one level-of-
detail is active. 
compare_func
never 
(default)
 
less 
less_equal 
greater 
greater_equal


equal 
not_equal 
always
Sets the comparison test that is used by 
the 
sample_compare
 and 
gather_compare
 texture functions.  

  
Enum Name
Valid Values
Description
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
28
174

---

    repeat, mirrored_repeat }; 
enum class address  
{ clamp_to_zero, clamp_to_edge, clamp_to_border 
    repeat, mirrored_repeat }; 
enum class compare_func { none, less, less_equal, greater, greater_equal, 
    equal, not_equal }; 
enum class border_color { transparent_black, opaque_black, opaque_white }; 
border_color
 is only valid if the 
address
 mode is 
clamp_to_border
. 
If 
coord
 is set to 
pixel
, the 
min_filter
 and 
mag_filter
 values must be the same, the 
mip_filter
 value must be 
none
, and the 
address
 modes must be either 
clamp_to_zero
, 
clamp_to_border
 or 
clamp_to_edge
. 
In addition to the enumeration types, the following types can also be specified with a sampler: 
max_anisotropy(int value) 
lod_clamp(float min, float max) 
Metal implements the sampler objects as follows: 
struct sampler { 
public: 
// full version of sampler constructor 
template 
constexpr sampler(Ts… sampler_params){}; 
private: 
};  
Ts
 must be the enumeration types listed above that can be used by the sampler data type. If the 
same enumeration type is declared multiple times in a given sampler constructor, the last listed 
value takes effect. 
The following Metal program source illustrates several ways to declare samplers. (The attributes 
(
sampler(n)
,  
buffer(n)
,  and 
texture(n)
) that appear in the code below are explained in 
section 4.3.1.). Note that samplers or constant buffers declared in program source do not need 
these attribute attributes. 
constexpr sampler s(coord::pixel,  
  
        address::clamp_to_zero, 
  
        filter::linear); 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
29
174

---