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
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