Metal Shading Language Specification

NOTE:  
sample_compare
 performs a comparison of the 
compare_value
 value against the 
pixel value (1.0 if the comparison passes and 0.0 if it fails). These comparison result 
values per-pixel are then blended together as in normal texture filtering and the 
resulting value between 0.0 and 1.0 is returned. 
The following member functions can be used to perform sampler-less reads from a 2D depth 
texture: 
T read(uint2 coord, uint lod = 0) const 
T read(ushort2 coord, ushort lod = 0) const 
The following built-in functions can be used to do a gather of four samples that would be used 
for bilinear interpolation when sampling a 2D depth texture. 
T
v 
gather(sampler s, float2 coord, int2 offset = int2(0)) const 
The following member functions can be used do a gather of four samples that would be used 
for bilinear interpolation when sampling a 2D depth texture and comparing these samples with a 
specified comparison value (1.0 if the comparison passes and 0.0 if it fails).  
T
v 
gather_compare(sampler s, float2 coord, float compare_value, int2 offset 
= int2(0)) const 
T
 must be a 
float
 type.  
The following 2D depth texture query member functions are provided. 
uint  get_width(uint lod = 0) const 
uint  get_height(uint lod = 0) const 
uint  get_num_mip_levels() const 
5.10.10 
2D Depth Texture Array 
The following member functions can be used to sample from a 2D depth texture array. 
T sample(sampler s, float2 coord, uint array, int2 offset = int2(0)) const 
T sample(sampler s, float2 coord, uint array, lod_options options, int2 
offset = int2(0)) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradient2d
. 
The following member functions can be used to sample from a 2D depth texture array and 
compare a single component against the specified comparison value 
T sample_compare(sampler s, float2 coord, uint array, float compare_value, 
int2 offset = int2(0)) const 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
129
174

---

T sample_compare(sampler s, float2 coord, uint array, float compare_value, 
lod_options options, int2 offset = int2(0)) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradient2d
. 
T
 must be a 
float
 type.  
The following member functions can be used to perform sampler-less reads from a 2D depth 
texture array: 
T read(uint2 coord, uint array, uint lod = 0) const 
T read(ushort2 coord, ushort array, ushort lod = 0) const 
The following member functions can be used to do a gather of four samples that would be used 
for bilinear interpolation when sampling a 2D depth texture array. 
T
v 
gather(sampler s, float2 coord, uint array, int2 offset = int2(0)) const 
The following member functions can be used do a gather of four samples that would be used 
for bilinear interpolation when sampling a 2D depth texture array and comparing these samples 
with a specified comparison value.  
T
v 
gather_compare(sampler s, float2 coord, uint array, float compare_value, 
int2 offset = int2(0)) const 
T
 must be a 
float
 type.  
The following 2D depth texture array query member functions are provided. 
uint get_width(uint lod = 0) const 
uint get_height(uint lod = 0) const 
uint get_array_size() const 
uint get_num_mip_levels() const 
5.10.11 
Cube Depth Texture 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
bias(float value) 
level(float lod) 
gradientcube(float3 dPdx, float3 dPdy) 
The following member functions can be used to sample from a cube depth texture. 
T sample(sampler s, float3 coord) const 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
130
174

---

T sample(sampler s, float3 coord, lod_options options) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradientcube
. 
The following member functions can be used to sample from a cube depth texture and compare 
a single component against the specified comparison value 
T sample_compare(sampler s, float3 coord, float compare_value) const 
T sample_compare(sampler s, float3 coord, float compare_value, lod_options 
options) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradientcube
. 
T
 must be a 
float
 type.  
The following member functions can be used to perform sampler-less reads from a cube depth 
texture: 
T read(uint2 coord, uint face, uint lod = 0) const 
T read(ushort2 coord, ushort face, ushort lod = 0) const 
The following member functions can be used to do a gather of four samples that would be used 
for bilinear interpolation when sampling a cube depth texture. 
T
v 
gather(sampler s, float3 coord) const 
The following member functions can be used do a gather of four samples that would be used 
for bilinear interpolation when sampling a cube texture and comparing these samples with a 
specified comparison value.  
T
v 
gather_compare(sampler s, float3 coord, float compare_value) const 
T
 must be a 
float
 type.  
The following cube depth texture query member functions are provided. 
uint get_width(uint lod = 0) const 
uint get_height(uint lod = 0) const 
uint get_num_mip_levels() const 
5.10.12 
Cube Array Depth Texture 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
bias(float value) 
level(float lod) 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
131
174

---