Metal Shading Language Specification

4.9.1   
Vertex – Fragment Signature Matching  
There are two kinds of data that can be passed between a vertex and fragment function: user-
defined and built-in variables.  
The per-instance input to a fragment function is declared with the 
[[stage_in]]
 attribute. 
These are output by an associated vertex function.  
Built-in variables are declared with one of the attribute attributes defined in section 4.3.3. These 
are either generated by a vertex function (such as 
[[position]]
,  
[[point_size]]
,  
[[clip_distance]]
), are generated by the rasterizer (such as 
[[point_coord]]
, 
[[front_facing]]
, 
[[sample_id]]
, 
[[sample_mask]]
) or refer to a framebuffer color value 
(such as 
[[color]]
) passed as an input to the fragment function.  
The built-in variable 
[[position]]
 must always be returned. The other built-in variables 
(
[[point_size]]
,  
[[clip_distance]]
) generated by a vertex function, if needed, must be 
declared in the return type of the vertex function but cannot be accessed by the fragment 
function.  
Built-in variables generated by the rasterizer or refer to a framebuffer color value may also 
declared as arguments of the fragment function with the appropriate attribute attribute. 
The attribute 
[[user(name)]]
 syntax can also be used to specify an attribute name for any 
user-defined variables. 
A vertex and fragment function are considered to have matching signatures if: 
• There is no input argument with the 
[[stage_in]]_,_…)_{__float4_clr;__…__return_clr;_}_fragment_float4_my_fragment2(VertexOutput_f_[[stage_in]]'>[[stage_in]]
 attribute declared in the fragment 
function. 
• For a fragment function argument declared with 
[[stage_in]]
, each element in the 
type associated with this argument can be one of the following: a built-in variable 
generated by the rasterizer, a framebuffer color value passed as input to the fragment 
function, or a user-generated output from a vertex function. For built-in variables 
generated by the rasterizer or framebuffer color values, there is no requirement for a 
matching type to be associated with elements of the vertex return type. For elements 
that are user-generated outputs, the following rules apply: 
• If the attribute name given by 
[[user(name)]]
 is specified for an element, then this 
attribute name must match with an element in the return type of the vertex function, and 
their corresponding data types must also match.   
• If the 
[[user(name)]]
 attribute name is not specified, then the argument name and 
types must match. 
Below is an example of compatible signatures: 
struct VertexOutput { 
 
float4 position [[position]]; 
 
float3 normal; 
 
float2 texcoord; 
}; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
92
174

---

vertex VertexOutput  
my_vertex(…)  
{  
 
VertexOutput v; 
 
… 
 
return v; 
} 
fragment float4 
my_fragment(VertexOutput f [[stage_in]], …) 
{ 
 
float4 clr; 
 
… 
 
return clr; 
} 
fragment float4 
my_fragment2(VertexOutput f [[stage_in]], 
  bool is_front_face [[front_facing]], …) 
{ 
float4 clr; 
…  
return clr; 
} 
my_vertex
 and 
my_fragment
 or 
my_vertex
 and 
my_fragment2
 can be used together to 
render a primitive. 
Below is another example of compatible signatures: 
struct VertexOutput { 
float4 position [[position]]; 
float3 vertex_normal [[user(normal)]]; 
float2 texcoord [[user(texturecoord)]]; 
}; 
struct FragInput { 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
93
174

---

float3 frag_normal [[user(normal)]]; 
float4 position [[position]]; 
float4 framebuffer_color [[color(0)]]; 
bool is_front_face [[front_facing]]; 
}; 
vertex VertexOutput  
my_vertex(…)  
{  
VertexOutput v; 
…   
return v; 
} 
fragment float4 
my_fragment(FragInput f [[stage_in]], …) 
{ 
float4 clr; 
…  
return clr; 
} 
Below is another example of compatible signatures: 
struct VertexOutput { 
float4 position [[position]]; 
float3 normal; 
float2 texcoord; 
}; 
struct FragInput { 
float4 position [[position]]; 
float2 texcoord; 
}; 
vertex VertexOutput  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
94
174

---

my_vertex(… )  
{  
VertexOutput v; 
…    
return v; 
} 
fragment float4 
my_fragment(FragInput f [[stage_in]], …) 
{ 
float4 clr; 
…  
return clr; 
} 
Below is another example of compatible signatures: 
struct VertexOutput { 
float4 position [[position]]; 
float3 normal; 
float2 texcoord; 
}; 
vertex VertexOutput 
my_vertex(…)  
 
 
 
 
{  
VertexOutput v; 
…  
return v; 
} 
fragment float4 
my_fragment(float4 p [[position]], …) 
{ 
float4 clr; 
…   
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
95
174

---