Metal Shading Language Specification

struct M  { 
struct A { 
int a [[user(x)]]; 
} 
b [[user(y), raster_order_group(0)]];  
};  
struct V { 
int a [[user(x)]]; 
M::A b [[user(y)]]; // illegal: b aliases with a  
}; 
fragment void 
f(V i [[imageblock_data(M)]]) 
{…}  
NOTE: Explicit imageblock types cannot have data members declared with the [[color(n)]] attribute.  
4.7.2   
Imageblocks and Raster Order Groups 
In a kernel function, a 
[[raster_order_group(index)]]
 attribute specified on data members 
of an imageblock is ignored.  
In a fragment function, the 
[[raster_order_group(index)]]
 attribute must be specified 
with data members of the master explicit imageblock data struct.  
If the master explicit imageblock struct contains data members that are structs, the

[[raster_order_group(index)]]
 attribute can be specified for all data members in the 
nested struct or just the nested struct. If the 
[[raster_order_group(index)]]
 attribute is 
specified on the nested struct, then it applies to all data members of the nested struct, and no 
data member in the nested struct can have the 
[[raster_order_group(index)]]
 attribute 
declared.  
The 
[[raster_order_group(index)]]
 may be optionally specified with data members of an 
imageblock view struct, but the 
[[raster_order_group(index)]]
 must match the same 
[[raster_order_group(index)]]
 specified on the data member of the master explicit 
imageblock struct.  
The following example shows how the 
[[raster_order_group(index)]]
 attribute can be 
specified for data members of a master imageblock. Since the 
[[raster_order_group(index)]]
 attribute is used on the 
S
 struct member of the 
gBufferData
 struct, the attribute cannot be used on any members of the 
S
 struct.  
struct S { 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
88
174

---

rgb9e5 normal; 
float factor;  
};  
struct gBufferData { 
half3 color [[raster_order_group(0)]]; 
S s [[raster_order_group(1)]]; 
rgb11b10f lighting [[raster_order_group(2)]];  
};  
Data members declared as an array have a single raster order group associated with all 
members of the array. The following example shows how the 
[[raster_order_group(index)]]
 attribute can be specified for data members of a master 
imageblock that are declared as an array of a struct type.  
struct S { 
rgb9e5 normal; 
float factor;  
};  
struct IM { 
half3 color [[raster_order_group(0)]]; 
S s [[raster_order_group(1)]][2];  
rgb11b10f lighting [[raster_order_group(2)]]; 
};  
The following example shows an incorrect use of the 
[[raster_order_group(index)]]
 
attribute where data-member 
s
 is declared as an array of a struct of type 
S
 with members that 
specify raster order groups that will result in a compilation error.  
struct S { 
rgb9e5 normal [[raster_order_group(0)]]; 
float factor [[raster_order_group(1)]];  
};  
struct IM { 
half3 color [[raster_order_group(0)]]; 
S s[2]; // compilation error 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
89
174

---

rgb11b10f lighting [[raster_order_group(2)]];  
};  
4.7.3   
Aliasing Explicit and Implicit Imageblocks 
By default, explicit and implicit imageblocks do not alias. To alias the allocation of an explicit 
imageblock with the implicit imageblock fully or partially, the following attribute can also be 
specified with an explicit imageblock:  
[[alias_implicit_imageblock]] 
[[alias_implicit_imageblock_color(n)]]  
The 
[[alias_implicit_imageblock]]
 attribute specifies that the explicit imageblock 
allocation completely aliases the implicit imageblock.  
The 
[[alias_implicit_imageblock_color(n)]]
 attribute specifies that the explicit 
imageblock allocation aliases the implicit imageblock starting at a specific color attachment 
given by 
color(n)
.  
NOTE: Accessing data members of an implicit imageblock that are aliased with an explicit 
imageblock is undefined if the kernel or fragment function modifies the aliased imageblock data 
members using the explicit imageblock and its associated member functions.  
Example:  
struct I { 
rgba8unorm a; 
rgb9e5f b; 
int c; 
float d;  
};  
struct FragOut { 
float4 finalColor [[color(0)]]; 
I i [[imagelock_data, alias_implicit_imageblock_color(1)]];  
};  
fragment FragOut 
my_fragment(I i [[imageblock_data]], …) 
{ 
FragOut fragOut; 
… 
return fragOut;  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
90
174

---

}  
4.7.4   
Imageblocks and Function Constants 
Use of 
[[function_constant(name)]]
 is unsupported with data members of an imageblock 
struct that is either passed as inputs to or returned as output from a fragment or kernel function.  
4.8  Programmable Blending 
The fragment function can be used to perform per-fragment or per-sample programmable 
blending. The color attachment index identified by the 
[[color(m)]]
 attribute can be specified 
as an argument to a fragment function. 
Below is an OpenGL ES programmable blending example that describes how to paint grayscale 
onto what is below. 
The GLSL version is: 
#extension GL_APPLE_shader_framebuffer_fetch : require 
void main() 
{ 
// RGB to grayscale 
mediump float lum = dot(gl_LastFragData[0].rgb, vec3(0.30,0.59,0.11)); 
gl_FragColor = vec4(lum, lum, lum, 1.0); 
} 
The Metal version equivalent is: 
fragment half4 
paint_grayscale(half4 dst_color [[color(0)]])  
{ 
// RGB to grayscale 
half lum = dot(dst_color.rgb, half3(0.30h, 0.59h, 0.11h)); 
return half4(lum, lum, lum, 1.0h); 
} 
4.9  Graphics Function – Signature Matching 
A graphics function signature is a list of parameters that are either input to or output from a 
graphics function.  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
91
174

---