Metal Shading Language Specification

NOTE: Metal supports the standard 
f
 or 
F
 suffix to specify a single precision floating-
point literal value (e.g., 
0.5f
 or 
0.5F
). In addition, Metal supports the 
h
 or 
H
 suffix to 
specify a half precision floating-point literal value (e.g., 
0.5h
 or 
0.5H
). Metal also 
supports the 
u
 or 
U
 suffix for unsigned integer literals.  
Table 2 lists the size and alignment of most of the scalar data types. 
Table 2 Size and Alignment of Scalar Data Types 
2.2  Vector Data Types 
Metal supports a subset of the vector data types implemented by the system vector math 
library. 
ptrdiff_t
A signed integer type that is the result of subtracting two pointers. 
This is a 64-bit signed integer.
void
The 
void
 type comprises an empty set of values; it is an 
incomplete type that cannot be completed.
Type
Description
Type
Size (in bytes)
Alignment (in bytes)
bool
1
1
char


int8_t


unsigned char


uchar


uint8_t
1
1
short


int16_t


unsigned short


ushort


unit16_t
2
2
int


int32_t


unsigned int


uint


uint32_t
4
4
half
2
2
float
4
4
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
12
174

---

The vector type names supported are: 
booln
,  
charn
, 
shortn
, 
intn
, 
ucharn
, 
ushortn
, 
uintn
, 
halfn
 and 
floatn
   
n
 is 2, 3, or 4 representing a 2-, 3- or 4- component vector type. Table 3 lists the size and 
alignment of the vector data types. 
Table 3 Size and Alignment of Vector Data Types 
Type
Size (in bytes)
Alignment (in bytes)
bool2
2
2
bool3
4
4
bool4
4
4
char2


uchar2
2
2
char3


uchar3
4
4
char4


uchar4
4
4
short2


ushort2
4
4
short3


ushort3
8
8
short4


ushort4
8
8
int2


uint2
8
8
int3


uint3
16
16
int4


uint4
16
16
half2
4
4
half3
8
8
half4
8
8
float2
8
8
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
13
174

---

2.2.1   
Accessing Vector Components 
Vector components can be accessed using an array index. Array index 
0
 refers to the first 
component of the vector, index 
1
 to the second component, and so on. The following examples 
show various ways to access array components: 
pos = float4(1.0f, 2.0f, 3.0f, 4.0f); 
float x = pos[0]; // x = 1.0 
float z = pos[2]; // z = 3.0   
float4 vA = float4(1.0f, 2.0f, 3.0f, 4.0f); 
float4 vB; 
for (int i=0; i<4; i++) 
vB[i] = vA[i] * 2.0f // vB = (2.0, 4.0, 6.0, 8.0); 
Metal supports using the period (
.
) as a selection operator to access vector components, using 
letters that may indicate coordinate or color data: 
.xyzw 
.rgba
 
In the following code, the vector test is initialized, and then components are accessed using 
the 
.xyzw
 or 
.rgba
 selection syntax: 
int4 test = int4(0, 1, 2, 3); 
int a = test.x;  //  a = 0 
int b = test.y;  //  b = 1 
int c = test.z;  //  c = 2 
int d = test.w;  //  d = 3 
int e = test.r;  //  e = 0 
int f = test.g;  //  f = 1 
int g = test.b;  //  g = 2 
float3
16
16
float4
16
16
Type
Size (in bytes)
Alignment (in bytes)
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
14
174

---

int h = test.a;  //  h = 3 
The component selection syntax allows multiple components to be selected. 
float4 c; 
c.xyzw = float4(1.0f, 2.0f, 3.0f, 4.0f); 
c.z = 1.0f; 
c.xy = float2(3.0f, 4.0f); 
c.xyz = float3(3.0f, 4.0f, 5.0f); 
The component selection syntax also allows components to be permuted or replicated. 
float4 pos = float4(1.0f, 2.0f, 3.0f, 4.0f); 
float4 swiz = pos.wzyx; // swiz = (4.0f, 3.0f, 2.0f, 1.0f) 
float4 dup = pos.xxyy;  // dup = (1.0f, 1.0f, 2.0f, 2.0f) 
The component group notation can occur on the left hand side of an expression. To form the 
lvalue, swizzling may be applied. The resulting lvalue may be either the scalar or vector type, 
depending on number of components specified. Each component must be a supported scalar or 
vector type. The resulting lvalue of vector type must not contain duplicate components. 
float4 pos = float4(1.0f, 2.0f, 3.0f, 4.0f); 
// pos = (5.0, 2.0, 3.0, 6.0) 
pos.xw = float2(5.0f, 6.0f); 
// pos = (8.0, 2.0, 3.0, 7.0) 
pos.wx = float2(7.0f, 8.0f); 
// pos = (3.0, 5.0, 9.0, 7.0) 
pos.xyz = float3(3.0f, 5.0f, 9.0f); 
The following methods of vector component access are not permitted and result in a compile-
time error: 
• Accessing components beyond those declared for the vector type is an error. 2-
component vector data types can only access 
.xy
 or 
.rg
 elements. 3-component vector 
data types can only access 
.xyz
 or 
.rgb
 elements. For instance: 
float2 pos; 
pos.x = 1.0f; // is legal; so is y 
pos.z = 1.0f; // is illegal; so is w 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
15
174

---