Metal Shading Language Specification

types, or a struct built with these types. The data members of the imageblock struct use the 
appropriate alignment rules for each data member type declared in the struct to determine the 
actual struct layout and size.  
A fragment function can read one or more data members in the per-fragment imageblock data 
and write to one or more data members in the per-fragment imageblock data. The input and 
output imageblock data to a fragment function can be declared as a struct. The input and 
output imageblock structs can be the fully explicit imageblock struct (referred to as the master 
explicit imageblock struct) or be a subset of the master explicit imageblock struct (referred to as 
the imageblock view struct). For the latter case, the 
[[imageblock_data(type)]]
 attribute 
must be used with the input and output imageblock data struct specified on a fragment 
function, where 
type
 specifies the fully explicit imageblock data struct.  
If the 
[[imageblock_data(type)]] 
attribute is specified on the input argument or output 
struct element without type, the fragment function is assumed to use the master explicit 
imageblock data struct on the input or output.  
Example:  
struct I { 
float a [[raster_order_group(0)]];  
};  
struct FragOut { 
float c [[color(0)]]; 
I i [[imageblock_data]];  
};  
fragment FragOut 
my_fragment(I i [[imageblock_data]]) 
{ 
FragOut fragOut; 
… 
return fragOut;  
} 
Fragment functions can access both an implicit imageblock and an explicit imageblock as 
separate input arguments, or as fields in a return struct.  
Example:  
struct I { 
float a [[raster_order_group(0)]];  
};  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
33
174

---

struct FragOut { 
float c [[color(0)]]; 
I i [[imageblock_data]];  
};  
fragment FragOut 
my_fragment(I i [[imageblock_data]], 
 float c [[color(0)]]) 
{  
FragOut fragOut; 
… 
return fragOut;  
}  
By default, the explicit imageblock storage is separate from the storage of the implicit 
imageblock. To share storage between the explicit imageblock and implicit imageblock, see 
section 4.7.3.  
2.10.2  
Imageblocks in Kernel Functions  
The 
imageblock
 type (defined in the header 

) can only be used for 
arguments declared in a kernel function or user functions called by a kernel function. Only a 
kernel function can have an argument declared as an 
imageblock
 type. The data in an 
imageblock is visible only to threads in a threadgroup.  
This imageblock argument to a kernel function is declared as the following templated type:  
class imageblock_layout_explicit; 
class imageblock_layout_implicit;  
template  
struct imageblock;  
with the following restrictions:  
•
L
 is either 
imageblock_layout_explicit
 or 
imageblock_layout_implicit
,  
•
T
 is a struct, and  
• each member of 
T
 may be any of the following:  
• scalars  
• vectors and packed vectors  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
34
174

---

• pixel data types  
• an array with elements that are one of the types on this list  
• a struct with members that are one of the types on this list  
For an imageblock with implicit layout (
imageblock_layout_implicit
), each member of the 
struct may have a color attachment (see the 
[[color(m)]]
 attribute in Table 12 of section 
4.3.4). The color index 
m
 must be unique for each member (and sub-member) of 
T
.  
If no imageblock layout is specified by the user, the compiler deduces the layout based on 
T
. If 
T
 
is not compatible with an implicit or explicit imageblock, a compiler error is generated.  
Both explicit and implicit imageblocks can be passed as arguments to a kernel function. This 
also makes it easy to share explicit and implicit imageblock structs between fragment and 
kernel functions. By default, the explicit imageblock storage is separate from the storage of the 
implicit imageblock. To share storage between the explicit imageblock and implicit imageblock, 
see section 4.7.3.  


2.11 Aggregate Types  
Metal supports several aggregate types: arrays, structs, classes, and unions.  
Do not specify a struct member with an address space attribute, unless the member is a pointer 
type. All members of an aggregate type must belong to the same address space. (See section 
4.2 for details on address spaces.)  
Unless used in an Argument Buffer (see section 2.12), the following restriction is applicable:  
• An 
array
 type used to declare an array of textures (see section 2.11.1) cannot be 
declared in a struct.  
2.11.1  
Arrays of Textures and Samplers 
An array of textures is declared as: 
array
 or 
const array
 
T
 must be a texture type described in section 2.8 declared with the 
access::read
 or 
access::sample
 attribute. 
An array of samplers is declared as: 
array
 or 
const array
 
An array of textures or an array of samplers can be passed as an argument to a function 
(graphics, kernel, or user function) or be declared as a local variable inside a function. An array 
of samplers can also be declared in program scope. 
The Metal shading language also adds support for 
array_ref
. An 
array_ref
 
represents an immutable array of 
size()
 elements of type 
T
. 
T
 must be a sampler type or a 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
35
174

---