Metal Shading Language Specification

5.15 Imageblock Functions 
This section lists the Metal member functions for imageblocks. (For more on the imageblock 
data type, see section 2.10.)  
The following member functions query information about the imageblock:  
ushort get_width() const; 
ushort get_height() const; 
ushort get_num_samples() const;  


The following member function is used to query the number of unique color entries for a 
specific location given by an (x, y) coordinate inside the imageblock.  
ushort get_num_colors(ushort2 coord) const;  
The following member function return the color coverage mask (i.e., whether a given color 
covers one or more samples in the imageblock). Each sample is identified by its bit-position in 
the return value. If a bit is set, then this indicates that this sample uses the color index.  
ushort get_color_coverage_mask(ushort2 coord, ushort color_index) const;  
color_index
 is a value from 
0
 to 
get_num_colors() - 1
.  
5.15.1  
Functions for Imageblocks with Implicit Layout 
The following functions can be used to read/write an imageblock at pixel rate for a given (x, y) 
coordinate inside the imageblock.  
T read(ushort2 coord) const; 
void write(T data, ushort2 coord);  
The following member function can be used to read/write an imageblock at sample or color rate. 
coord
 specifies the (x, y) coordinate inside the imageblock, and 
index
 is the sample or color 
index.  
enum class imageblock_data_rate { color, sample };  
T read(ushort2 coord, ushort index, imageblock_data_rate data_rate) const; 
void write(T data, ushort2 coord, ushort index, imageblock_data_rate 
data_rate);  
Example:  
struct Foo { 
float4 a [[color(0)]]; 
int4 b [[color(1)]];  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
151
174

---

};  
kernel void 
my_kernel(imageblock img_blk, 
     ushort2 lid [[thread_index_in_threadgroup]] …)  
{ 
… 
Foo f = img_blk.read(lid); float4 r = f.a; 
… 
f.a = r;  
…  
img_blk.write(f, lid); 
}  
The following member function can be used to write an imageblock with a color coverage mask. 
This member function must be used when writing to an imageblock at color rate.  
void write(T data, ushort2 coord, ushort color_coverage_mask);  
The following member functions are used to get a region of a slice for a given data member in 
the imageblock. This is used to write data associated with a specific data member described in 
the imageblock for all threads in the threadgroup to a specified region in a texture. 
color_index
 refers to the data member declared in the struct type specified in 
imageblock
 with the 
[[color(n)]]
 attribute where 
n
 is 
color_index
. 
origin
 is the (x, y) 
coordinate in the slice. 
size
 is the actual size of the slice to be copied.  
const imageblock_slice slice(ushort 
color_index) const;  
const imageblock_slice slice(ushort 
color_index, ushort2 origin, ushort2 size) const;  
The 
slice(…)
 member function that does not take origin and size as arguments specifies the 
region to copy with an origin of (0,0) and the width and height of the imageblock.  
5.15.2  
Functions for Imageblocks with Explicit Layout  
The following member functions are used to get a reference to the imageblock data for a 
specific location given by an (x, y) coordinate inside the imageblock. These member functions 
should be used when reading or writing data members in an imageblock at pixel rate.  
threadgroup_imageblock T* data(ushort2 coord); 
const threadgroup_imageblock T* data(ushort2 coord) const;  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
152
174

---

The following member functions are used to get a reference to the imageblock data for a 
specific location given by an (x, y) coordinate inside the imageblock and a sample or color 
index. These member functions should be used when reading or writing data members in an 
imageblock at sample or color rate. 
T
 is the type specific in the 
imageblock
 templated 
declaration. 
coord
 is the coordinate in the imageblock, and 
index
 is the sample or color index 
for a multi-sampled imageblock. 
data_rate
 specifies whether the index is a color or sample 
index. If 
coord
 refers to a location outside the imageblock dimensions or if 
index
 is an invalid 
index, the behavior of 
data()
 is undefined.  
enum class imageblock_data_rate { color, sample };  
threadgroup_imageblock T* data(ushort2 coord, ushort index, 
imageblock_data_rate data_rate);  
const threadgroup_imageblock T* data(ushort2 coord, ushort index, 
imageblock_data_rate data_rate) const; 
Calling the 
data(coord)
 member function for an imageblock that stores pixels at sample or  
color rate is equivalent to calling 
data(coord,0,imageblock_data_rate::sample)
.  
Example:  
struct Foo { 
rgba8unorm a; 
int b;  
};  
kernel void  
my_kernel(imageblock img_blk,  
     ushort2 lid [[thread_position_in_threadgroup]] …)  
{ 
…   
threadgroup_imageblock Foo* f = img_blk.data(lid); 
half4 r = f->a; 
f->a = r; 
… 
}  
The following 
write
 member function can be used to write an imageblock with a color coverage 
mask. This member function must be used when writing to an imageblock at color rate.  
void write(T data, ushort2 coord, ushort color_coverage_mask);  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
153
174

---