Metal Shading Language Specification

return clr; 
} 
Below is an example of incompatible signatures: 
struct VertexOutput { 
float4 position [[position]]; 
float3 normal; 
float2 texcoord; 
}; 
struct FragInput { 
float4 position [[position]]; 
half3 normal; 
}; 
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 incompatible signatures: 
struct VertexOutput { 
float4 position [[position]]; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
96
174

---

float3 normal [[user(normal)]]; 
float2 texcoord [[user(texturecoord)]]; 
}; 
struct FragInput { 
float3 normal [[user(foo)]]; 
float4 position [[position]]; 
}; 
vertex VertexOutput  
my_vertex_shader(…)  
{  
VertexOutput v; 
…  
return v; 
} 
fragment float4 
my_fragment_shader(FragInput f [[stage_in]], …) 
{ 
float4 clr; 
…  
return clr; 
} 
4.10 Program Scope Function Constants 
Metal shading language version 1.2 introduced support for function constants, which generates 
multiple variants of a function. Before version 1.2, developers could compile one function many 
times with different pre-processor macro defines to enable different features (a.k.a., an 
ubershader). Using pre-processor macros for ubershaders with offline compiling can result in a 
large number of variants and a significant increase in the size of the shading function library 
assets.  
The Metal shading language allows you to use function constants with the same ease of use as 
using pre-processor macros but moves the generation of the specific variants to the creation of 
the pipeline state. You do not have to compile the variants offline.  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
97
174

---

4.10.1  
Specifying Program Scope Function Constants 
The Metal shading language is extended to allow program scope variables to be declared with 
the following attribute: 
[[function_constant(index)]]   
Program scope variables declared with the 
[[function_constant(index)]]
 attribute or 
program scope variables initialized with variables declared with this attribute are referred to as 
function constants.  
These function constants are not initialized in the Metal shader source but instead their values 
are specified when the render or compute pipeline state is created. 
index
 is used to specify a 
location index that can be used to refer to the function constant variable (instead of by its name) 
in the runtime.  
Examples: 
constant int a [[function_constant(0)]]; 
constant bool b [[function_constant(2)]]; 
Variables in program scope declared in the constant address space can also be initialized using 
a function constant(s). 
Examples: 
constant int a [[function_constant(0)]]; 
constant bool b [[function_constant(2)]]; 
constant bool c = ((a == 1) && b); 
constant int d = (a * 4); 
The value of function constants 
a
 and 
b
 are specified when the render or compute pipeline state 
is created.  
The following built-in function can be used to determine if a function constant is available; i.e., it 
has been defined when the render or compute pipeline state is created. 
name
 must refer to a 
function constant variable.  
bool is_function_constant_defined(name)  
is_function_constant_defined(name)
 returns 
true
 if the function constant variable is 
defined when the render or compute pipeline state is created and 
false
 otherwise. 
If a function constant variable value is not defined when the render or compute pipeline state is 
created and if the graphics or kernel function specified with the render or compute pipeline 
state uses these function constants, the behavior is the same as when the value returned by 
is_function_constant_defined(name)
 is 
false
.  
Function constants can be used in Metal: 
• To control code paths that get compiled,  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
98
174

---

• To specify the optional arguments of a function (graphics, kernel or user functions), or  
• To specify optional elements of a struct that is declared with the 
[[stage_in]]
 
attribute. 
4.10.1.1  
Function Constants to Control Code Paths to Compile 
Consider the following function which uses pre-processor macros for function constants: 
struct VertexOutput { 
float4 position [[position]]; 
float4 color; 
}; 
struct VertexInput { 
float4 position [[attribute(0)]]; 
float4 offset   [[attribute(1)]]; 
float4 color    [[attribute(2)]]; 
}; 
vertex VertexOutput 
myVertex(VertexInput vIn [[stage_in]]) 
{ 
VertexOutput vOut; 
vOut.position = vIn.position; 
#ifdef OFFSET_DEFINED 
vOut.position += vIn.offset; 
#endif 
#ifdef COLOR_DEFINED 
vOut.color = vIn.color; 
#else 
vOut.color = float4(0.0f); 
#endif 
return vOut; 
} 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
99
174

---