Metal Shading Language Specification

constexpr sampler a(coord::normalized); 
constexpr sampler b(address::repeat); 
constexpr sampler s(address::clamp_to_zero, 
  
        filter::linear, 
                    compare_func::less); 
constexpr sampler s(address::clamp_to_zero, 
  
        filter::linear, 
                    compare_func::less, 
                    max_anisotropy(10), 
                    lod_clamp(0.0f, MAXFLOAT)); 
NOTE:  Samplers that are initialized in the Metal shading language source are declared 
with 
constexpr
.  
2.10 Imageblocks 
The imageblock is a 2-dimensional data structure (represented by width, height, and number of 
samples) allocated in threadgroup memory that is designed as an efficient mechanism for 
processing 2-dimensional image data. The data layout of the imageblock is opaque. The 
elements in the imageblock can be accessed using an (x, y) coordinate and optionally the 
sample index. The elements in the imageblock associated with a specific (x, y) are referred to as 
the per-thread imageblock data or as just the imageblock data.  
Imageblocks are only supported for 
ios-metal2.0
. Imageblocks are only used with fragment 
and kernel functions.  
For fragment functions, the imageblock dimensions are derived from the tile size. For kernel 
functions, the developer specifies the imageblock dimensions, which are typically derived from 
the threadgroup size. For fragment functions, only the fragment’s imageblock data (i.e., 
identified by the fragment’s pixel position in the tile) can be accessed. For kernel functions, all 
threads in the threadgroup can access the imageblock.  
The imageblock data is described as a struct. Each element of the struct can be a scalar or 
vector integer or floating-point data type, pixel data types (specified in Table 6 in section 2.6), 
an array of these types, or structs built using these types.  
Built-in functions for imageblocks are listed in section 5.15.  
An imageblock slice refers to a region in the imageblock that describes the values of a given 
element in the imageblock data struct for all pixel locations or threads in the imageblock. The 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
30
174

---

storage type of the imageblock slice must be compatible with the texture format of the target 
texture, as listed in Table 8.  
Table 8 Imageblock Data Type and Compatible Target Texture Format  
Pixel Storage Type Compatible Texture Formats
float
, 
half
R32Float
, 
R16Float
, 
A8Unorm
, 
R8Unorm
, 
R8Snorm
, 
R16Unorm
, 
R16Snorm
float2
, 
half2
RG32Float
, 
RG16Float
, 
RG8Unorm
, 
RG8Snorm
, 
RG16Unorm
, 
RG16Snorm
 
float4
, 
half4
RGBA32Float
, 
RGBA16Float
, 
RGBA8Unorm
, 
RGBA8Snorm
, 
RGBA16Unorm
, 
RGBA16Snorm
, 
RGB10A2Unorm
, 
RG11B10Float
, 
RGB9E5Float
int
, 
short
R32Sint
, 
R16Sint
, 
R8Sint
int2
, 
short2
RG32Sint
, 
RG16Sint
, 
RG8Sint
int4
, 
short4
RGBA32Sint
, 
RGBA16Sint
, 
RGBA8Sint
uint
, 
ushort
R32Uint
, 
R16Uint
, 
R8Uint
uint2
, 
ushort2
RG32Uint
, 
RG16Uint
, 
RG8Uint
uint4
, 
ushort4
RGBA32Uint
, 
RGBA16Uint
, 
RGBA8Uint
r8unorm
A8Unorm
, 
R8Unorm
r8snorm
R8Snorm
r16unorm
R16Unorm
r16snorm
R16Snorm
rg8unorm
RG8Unorm
rg8snorm
RG8Snorm
rg16unorm
RG16Unorm
rg16snorm
RG16Snorm
rgba8unorm
RGBA8Unorm
, 
BGRA8Unorm
srgba8unorm
RGBA8Unorm_sRGB
, 
BGRA8Unorm_sRGB
rgba8snorm
RGBA8Snorm
, 
BGRA8Unorm
rgba16unorm
RGBA16Unorm
rgba16snorm
RGBA16Snorm
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
31
174

---

Sections 2.10.1 and 2.10.2 describe how an imageblock is accessed in a fragment or kernel 
function, respectively.  
2.10.1  
Imageblocks in Fragment Functions  
In a fragment function, the imageblock can be accessed in two ways:  
• as a color attachment where the storage layout of the imageblock is not known in the 
fragment function (implicit imageblock layout). An implicit imageblock layout uses the 
existing color attachment attribute. See section 2.10.1.1.  
• or as a struct used to declare the imageblock data when the storage layout of the 
imageblock is explicitly specified in the fragment function (explicit imageblock layout). 
See section 2.10.1.2.  
2.10.1.1  
Implicit Imageblock Layout for Fragment Functions  
The imageblock data (i.e., all the data members in the imageblock associated with a pixel) can 
be accessed in a fragment function. Metal creates an implicit imageblock that matches the 
behavior of color attachments (for input to and output from a fragment function). In this mode, 
the types associated with the color attachments, as described in the fragment function, are the 
ALU types (i.e., the types used to perform computations in the fragment function). The Metal 
runtime defines the actual storage (i.e., pixel) format to be used.  
When accessing the imageblock data as color attachments, the pixel storage types described in 
section 2.6 cannot be declared in the imageblock slice struct.  
For an imageblock data implicit layout of type 
T
, 
T
 is a struct where each member satisfies one 
of the following:  
• have a color attachment (see the 
[[color(m)]]
 attribute in Table 12 of section 4.3.4). 
The color index 
m
 must be unique for each member (and sub-member) of 
T
.  
• be a struct type with members that satisfy the constraint on the list.  
2.10.1.2 
Explicit Imageblock Layout for Fragment Functions  
The imageblock data with explicit layout (i.e., the imageblock layout is declared in the shading 
function, not via the runtime as done for color attachments) is declared as a struct.  
Each data member of the per-fragment imageblock data can be a scalar or vector integer or 
floating-point data type, one of the pixel data types described in section 2.6, an array of these 
rgb10a2
RGB10A2Unorm
rg11b10f
RG11B10Float
rgb9e5
RGB9E5Float
Pixel Storage Type Compatible Texture Formats
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page    of  
32
174

---