Metal Shading Language Specification

The following member functions can be used to write to a 1D texture. Since mipmaps are not 
supported for 1D textures, 
lod
 must be 0. 
void write(T
v
 color, uint coord, uint lod = 0) 
void write(T
v
 color, ushort coord, ushort lod = 0) 
The following 1D texture query member functions are provided. Since mipmaps are not 
supported for 1D textures, 
get_num_mip_levels()
 must return 0, and 
lod
 must be 0 for 
get_width()
. 
uint get_width(uint lod = 0) const 
uint get_num_mip_levels() const 
5.10.22 
1D Texture Array 
The following member functions can be used to sample from a 1D texture array. 
T
v 
sample(sampler s, float coord, uint array) const 
The following member functions can be used to perform sampler-less reads from a 1D texture 
array. Mipmaps are not supported for 1D textures, so 
lod
 must be 0. 
T
v 
read(uint coord, uint array, uint lod = 0) const 
T
v 
read(ushort coord, ushort array, ushort lod = 0) const 
The following member functions can be used to write to a 1D texture array. Since mipmaps are 
not supported for 1D textures, 
lod
 must be 0. 
void write(T
v
 color, uint coord, uint array, uint lod = 0) 
void write(T
v
 color, ushort coord, ushort array, ushort lod = 0) 
The following 1D texture array query member functions are provided. Since mipmaps are not 
supported for 1D textures, 
get_num_mip_levels()
 must return 0, and 
lod
 must be 0 for 
get_width()
. 
uint get_width(uint lod = 0) const 
uint get_array_size() const 
uint get_num_mip_levels() const 
5.10.3 
2D Texture 
The following data types and corresponding constructor functions are available to specify 
various sampling options: 
bias(float value) 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
122
174

---

level(float lod) 
gradient2d(float2 dPdx, float2 dPdy) 
The following member functions can be used to sample from a 2D texture.  
T
v 
sample(sampler s, float2 coord, int2 offset = int2(0)) const 
T
v 
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 perform sampler-less reads from a 2D texture: 
T
v 
read(uint2 coord, uint lod = 0) const 
T
v 
read(ushort2 coord, ushort lod = 0) const 
The following member functions can be used to write to a 2D texture. 
void write(T
v
 color, uint2 coord, uint lod = 0) 
void write(T
v
 color, ushort2 coord, ushort lod = 0) 
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 texture. 
enum class component {x, y, z, w}; 
T
v 
gather(sampler s, float2 coord, int2 offset = int2(0), component c = 
component::x) const 
The following 2D 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.3.1 
2D Texture Sampling Example 
The following code shows several uses of the 2D texture sample function, depending upon its 
arguments.  
texture2d tex; 
sampler s; 
float2 coord; 
int2 offset; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
123
174

---

float lod; 
// no optional arguments 
float4 clr = tex.sample(s, coord); 
// sample using a mip-level 
clr = tex.sample(s, coord, level(lod)); 
// sample with an offset 
clr = tex.sample(s, coord, offset); 
// sample using a mip-level and an offset  
clr = tex.sample(s, coord, level(lod), offset); 
5.10.4 
2D Texture Array 
The following member functions can be used to sample from a 2D texture array. 
T
v 
sample(sampler s, float2 coord, uint array, int2 offset = int2(0)) const 
T
v 
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 perform sampler-less reads from a 2D texture 
array: 
T
v 
read(uint2 coord, uint array, uint lod = 0) const 
T
v 
read(ushort2 coord, ushort array, ushort lod = 0) const 
The following member functions can be used to write to a 2D texture array. 
void write(T
v
 color, uint2 coord, uint array, uint lod = 0) 
void write(T
v
 color, ushort2 coord, ushort array, ushort lod = 0) 
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 texture array. 
T
v 
gather(sampler s, float2 coord, uint array, int2 offset = int2(0), 
component c = component::x) const 
The following 2D texture array query member functions are provided. 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
124
174

---