Metal Shading Language Specification

vOut.color = float4(0.0f); 
return vOut; 
} 
4.10.1.4 
Function Constants for Resource Bindings 
Starting in Metal 2.0, arguments to a graphics or kernel functions that are a resource (buffer, 
texture, or sampler) can have their binding number be specified using a function constant. The 
function constant must be a scalar integer type.  
Example: 
constant int indexA [[function_constant(0)]]; 
constant int indexB = indexA + 2; 
constant int indexC [[function_constant(1)]]; 
constant int indexD [[function_constant(2)]];  
kernel void 
my_kernel(constant UserParams& params [[buffer(indexA)]], 
device T * p [[buffer(indexB)]], 
texture2d texA [[texture(indexC)]], 
sampler s [[sampler(indexD)]], …)     
{…}  
4.10.1.5 
Function Constants for Color Attachments and Raster Order Groups 
Starting in Metal 2.0, the 
[[color(n)]]
 and 
[[raster_order_group(index)]]
 indices can 
also be a function constant. The function constant specified as indices for color and raster order 
group attributes must be a scalar integer type.  
Example:  
constant int colorAttachment0 [[function_constant(0)]]; 
constant int colorAttachment1 [[function_constant(1)]]; 
constant int group0 [[function_constant(2)]]; 
constant int group1 [[function_constant(3)]];  
struct FragmentOutput { 
float4 color0 [[color(colorAttachment0)]];  
float4 color1 [[color(colorAttachment1)]]; 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
104
174

---

};  
fragment FragmentOutput 
my_fragment(texture2d texA [[texture(0), 
raster_order_group(group0)]], …)     
{…} 
4.10.1.6 
Function Constants with Elements of a Struct 
Starting in Metal 2.0, to identify that an element of a struct is optional, the 
[[function_constant(name)]]
 attribute can be declared with elements of a struct that are 
declared as a return type of a graphics or user function, or passed by value as an argument to a 
kernel, graphics, or user function. The behavior is similar to function constants for elements 
with the 
[[stage_in]]
 attribute, as described in section 4.10.1.3.  
name
 refers to a function constant variable. If the value of the function constant variable given 
by 
name
 is non-zero or 
true
 (determined when the render or compute pipeline state is created), 
the element in the struct is considered to be declared in the function signature. If the value of 
the function constant variable given by 
name
 is 0 or 
false
, the element is not considered to be 
declared in the struct. If 
name
 refers to a function constant variable that has not been defined, 
the behavior is the same as if 
is_function_constant_defined(name)
 is used and its value is 
false
.  
4.11 Per-Primitive Viewport and Scissor Rectangle Index 
Selection 
The 
[[viewport_array_index]]
 attribute supports built-in variables as both vertex output 
and fragment input. With this attribute, vertex function output is used to specify which viewport 
or scissor rectangle is used for rasterization from an array specified by the 
setViewports:count:
 or 
setScissorRects:count:
 framework calls. 
[[viewport_array_index]]
 is only available for macOS.  
The input value of 
[[viewport_array_index]]
 in the fragment function is the same as the 
value written to 
[[viewport_array_index]]
 in the vertex function, even if the value is out of 
range. If the vertex output does not specify 
[[viewport_array_index]]
, the default index 
value is 0. Specifying a value for 
[[viewport_array_index]]
 that is larger than the number of 
viewports passed in by 
setViewports:count:
 (or in the case of 
setViewport:
, larger than 0) 
is treated as if the 
[[viewport_array_index]]
 value is 0. Hardware that does not support this 
feature acts as if the maximum permitted viewport and scissor rectangle count is 1, and the 
maximum allowed 
[[viewport_array_index]]
 is 0. This effectively means that every 
primitive is rendered to viewport/scissor rectangle 0, regardless of the passed value. 
Specifying 
[[viewport_array_index]]
 in a post-tessellation vertex function is allowed. 
[[viewport_array_index]]
 cannot be specified in the tessellation factor buffer.  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
105
174

---

Specifying 
[[viewport_array_index]]
 as fragment function input counts against the number 
of varyings available and reduces the number of components that can be passed from vertex 
function to fragment function.  
In case the value of 
[[viewport_array_index]]
 differs for different vertices of the primitive, 
the value specified at the provoking vertex is used in the vertex function and is also passed to 
the fragment function. The same behavior applies to primitives generated by tessellation.  
4.12 Additional Restrictions 
• Writes to a buffer from a vertex function are not guaranteed to be visible to reads from 
the associated fragment function of a given primitive.  
• If a vertex function does writes to a buffer(s), its return type must be 
void
. 
• The return type of a vertex or fragment function cannot include an element that is a 
packed vector type, matrix type, a struct type, a reference or a pointer to a type. 
• The number of inputs to a fragment function declared with the 
stage_in
 attribute can 
be a maximum of 128 scalars. (This number does not include the built-in variables 
declared with one of the following attributes: 
[[color(m)]]
, 
[[front_facing]]
, 
[[sample_id]]
 and 
[[sample_mask]]
.) If an input to a fragment function is a vector 
then this counts as 
n
 scalars where 
n
 is the number of components in the vector.  
• The argument type for arguments to a graphics or kernel function cannot be a derived 
class. Also, the type of an argument to a graphics function that is declared with the 
stage_in
 attribute cannot be a derived class. 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
106
174

---