Metal Shading Language Specification

  texture2d img [[texture(0)]], 
  sampler s [[sampler(0)]], 
  float4 framebuffer [[color(0)]]) 
{ 
return c = mix(img.sample(s, tex_coord), framebuffer, mix_factor); 
} 
4.7  Imageblock Attributes 
This section describes several attributes that are used with imageblocks. The 
[[imageblock_data(type)]]
 attribute that specifies input and output imageblock with an 
explicit imageblock layout on a fragment function is described in section 2.10.  
4.7.1   
user Attribute for Matching Data Members of Master and View 
Imageblocks  
The 
[[user(name)]]
 attribute can be used to specify an attribute name for a data member of 
the imageblock data type for a fragment function. If the imageblock struct specified in a 
fragment function is a subset of the master explicit imageblock struct, the following rules are 
used to match data members declared in the imageblock struct used with a fragment function 
with corresponding data members declared in the master explicit imageblock struct:  
• Every attribute name given by [[ user(name) ]] must be unique for each data member in 
the imageblock.  
• If the attribute name given by 
[[user(name)]]
 is specified for a data member, the 
attribute name given by name must match with a data member declared in the master 
explicit imageblock struct. In addition, the associated data types must also match.  
• If the 
[[user(name)]]
 attribute is not specified, the data member name and type 
declared in the imageblock data type for a fragment function and the master imageblock 
struct must match. Additionally, the data member cannot be within a nested struct that is 
either within the view imageblock struct or within the master imageblock struct.  
The example below shows master and view imageblock structs with data members that are 
declared with the 
[[user(name)]]
 attribute:  
Example:  
// The explicit layout imageblock data master struct. 
struct IM { 
rgba8unorm a [[user(my_a), raster_order_group(0)]]; 
rgb9e5f b [[user(my_b), raster_order_group(0)]]; 
int c [[user(my_c), raster_order_group(0)]]; 
float d [[user(my_d), raster_order_group(0)]];  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
84
174

---

}; 
// The explicit layout imageblock data view struct for input. 
struct IVIn { 
rgb9e5f x [[user(my_b)]]; // Maps to IM::b  
float y [[user(my_d)]]; // Maps to IM::d 
};  
// The explicit layout imageblock data view struct for output. 
struct IVOut {  
int z [[ user(my_c) ]]; // Maps to IM::c  
};  
// The fragment return struct. 
struct FragOut {  
// IVOut is a view of the master IM. 
IVOut i [[ imagelock_data(IM) ]]; 
};  
// IVIn is a view of the master IM. 
fragment FragOut 
my_fragment(IVIn i [[imageblock_data(IM)]], …) {  
FragOut fragOut; 
… = i.x; 
… = i.y; 
fragOut.i.z = …; 
return fragOut;  
}  
The example below shows master and view imageblock structs with data members that are 
declared without the 
[[user(name)]]
 attribute:  
struct IM { 
rgba8unorm a [[raster_order_group(0)]]; 
rgb9e5f b [[raster_order_group(0)]]; 
int c [[raster_order_group(0)]]; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
85
174

---

float d [[raster_order_group(0)]];  
};  
struct IVIn { 
rgb9e5f b; // Maps to IM::b 
float d; // Maps to IM::d  
};  
struct IVOut { 
int c; // Maps to IM::c  
};  
struct FragOut { 
IVOut i [[imageblock_data(IM)]];  
};  
fragment FragOut 
my_fragment(IVIn i [[imageblock_data(IM)]], …) { 
FragOut fragOut; 
… = i.b; 
… = i.d;  
fragOut.i.c = …;  
return fragOut; 
}  
Nested structs can be declared in the master imageblock and view imageblock structs. Below is 
an example that shows how nested structs in an imageblock can be used with data members 
declared with the 
[[user(name)]]
 attribute: 
struct A { 
rgba8unorm a [[user(A_a)]]; 
rgb9e5f b [[user(A_b)]];  
}; 
  
struct B { 
int a [[user(B_a), raster_order_group(1)]]; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
86
174

---

float b [[user(B_b), raster_order_group(2)]];  
};  
struct IM { 
A a [[user(A), raster_order_group(0)]]; 
B b [[user(B)]];  
};  
struct IVIn { 
A x [[user(A)]]; // Maps to IM::a  
};  
struct IVOut { 
B y [[user(B)]]; // Maps to IM::b 
rgb9e5f z [[user(A_b)]]; // Maps to IM::A::b  
};  
struct FragOut { 
IVOut i [[imageblock_data(IM)]];  
};  
fragment FragOut 
my_fragment(IVIn i [[imageblock_data(IM)]], …) { 
FragOut fragOut; 
… = i.x; 
fragOut.i.y.a = …;  
fragOut.i.y.b = …; 
fragOut.i.z = …; 
return fragOut;  
}  
Each field of a view struct must correspond to exactly one master struct field. A master struct 
field can refer to a top-level struct field as well as a field within a nested struct. It is illegal for 
two or more view struct fields to alias the same master struct field.  
Example of Illegal Use:  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
87
174

---