Metal Shading Language Specification

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.5 
3D Texture   
 
 
 
 
 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
bias(float value) 
level(float lod) 
gradient3d(float3 dPdx, float3 dPdy) 
The following member functions can be used to sample from a 3D texture. 
T
v 
sample(sampler s, float3 coord, int3 offset = int3(0)) const 
T
v 
sample(sampler s, float3 coord, lod_options options, int3 offset = 
int3(0)) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradient3d
. 
The following member functions can be used to perform sampler-less reads from a 3D texture: 
T
v 
read(uint3 coord, uint lod = 0) const 
T
v 
read(ushort3 coord, ushort lod = 0) const 
The following member functions can be used to write to a 3D texture. 
void write(T
v
 color, uint3 coord, uint lod = 0) 
void write(T
v
 color, ushort3 coord, ushort lod = 0) 
The following 3D texture query member functions are provided. 
uint get_width(uint lod = 0) const 
uint get_height(uint lod = 0) const 
uint get_depth(uint lod = 0) const 
uint get_num_mip_levels() const 
5.10.6 
Cube Texture 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
125
174

---

bias(float value) 
level(float lod) 
gradientcube(float3 dPdx, float3 dPdy) 
The following member functions can be used to sample from a cube texture. 
T
v 
sample(sampler s, float3 coord) const 
T
v 
sample(sampler s, float3 coord, lod_options options) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradientcube
. 
Table 29 describes the cube face and the number used to identify the face. 
Table 29 Cube Face Number 
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 texture. 
T
v 
gather(sampler s, float3 coord, component c = component::x) const 
The following member functions can be used to perform sampler-less reads from a cube 
texture: 
T
v 
read(uint2 coord, uint face, uint lod = 0) const 
T
v 
read(ushort2 coord, ushort face, ushort lod = 0) const 
The following member functions can be used to write to a cube texture. 
void write(T
v
 color, uint2 coord, uint face, uint lod = 0) 
void write(T
v
 color, ushort2 coord, ushort face, ushort lod = 0) 
Face number
Cube face
0
Positive X
1
Negative X
2
Positive Y
3
Negative Y
4
Positive Z
5
Negative Z
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
126
174

---

The following cube 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.7  
Cube Array 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 array texture. 
T
v 
sample(sampler s, float3 coord, uint array) const 
T
v 
sample(sampler s, float3 coord, uint array, 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 do a gather of four samples that would be used 
for bilinear interpolation when sampling a cube array texture. 
T
v 
gather(sampler s, float3 coord, uint array, component c = component::x) 
const 
The following member functions can be used to perform sampler-less reads from a cube array 
texture: 
T
v 
read(uint2 coord, uint face, uint array, uint lod = 0) const 
T
v 
read(ushort2 coord, ushort face, ushort array, ushort lod = 0) const 
The following member functions can be used to write to a cube array texture. 
void write(T
v
 color, uint2 coord, uint face, uint array, uint lod = 0) 
void write(T
v
 color, ushort2 coord, ushort face, ushort array, ushort lod = 
0) 
The following cube array texture query member functions are provided. 
uint get_width(uint lod = 0) const 
uint get_height(uint lod = 0) const 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
127
174

---

uint get_array_size() const 
uint get_num_mip_levels() const 
5.10.8 
2D Multisampled Texture 
The following member functions can be used to perform sampler-less reads from a 2D 
multisampled texture: 
T
v 
read(uint2 coord, uint sample) const 
T read(ushort2 coord, ushort sample) const 
The following 2D multisampled texture query member functions are provided. 
uint  get_width() const 
uint  get_height() const 
uint  get_num_samples() const
 
5.10.9 
2D Depth Texture 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
bias(float value) 
level(float lod) 
gradient2d(float2 dPdx, float2 dPdy) 
The following member functions can be used to sample from a 2D depth texture.  
T sample(sampler s, float2 coord, int2 offset = int2(0)) const 
T sample(sampler s, float2 coord, 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 and compare a 
single component against the specified comparison value 
T sample_compare(sampler s, float2 coord, float compare_value, int2 offset 
= int2(0)) const 
T sample_compare(sampler s, float2 coord, 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.  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
128
174

---