Metal Shading Language Specification

gradientcube(float3 dPdx, float3 dPdy) 
The following member functions can be used to sample from a cube array depth texture. 
T sample(sampler s, float3 coord, uint array) const 
T sample(sampler s, float3 coord, uint array, lod_options options) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradientcube
. 
The following member functions can be used to sample from a cube depth texture and compare 
a single component against the specified comparison value 
T sample_compare(sampler s, float3 coord, uint array, float compare_value) 
const 
T sample_compare(sampler s, float3 coord, uint array, float compare_value, 
lod_options options) const 
lod_options
 must be one of the following types: 
bias
, 
level
 or 
gradientcube
. 
T
 must be a 
float
 type.  
The following member functions can be used to perform sampler-less reads from a cube depth 
texture array: 
T read(uint2 coord, uint face, uint array, uint lod = 0) const 
T read(ushort2 coord, ushort face, ushort array, ushort lod = 0) const 
The following member functions can be used to do a gather of four samples that would be used 
for bilinear interpolation when sampling a cube depth texture. 
T
v 
gather(sampler s, float3 coord, uint array) const 
The following member functions can be used do a gather of four samples that would be used 
for bilinear interpolation when sampling a cube texture and comparing these samples with a 
specified comparison value.  
T
v 
gather_compare(sampler s, float3 coord, uint array, float compare_value) 
const 
T
 must be a 
float
 type.  
The following cube depth texture query member functions are provided. 
uint  get_width(uint lod = 0) const 
uint  get_height(uint lod = 0) const 
uint  get_array_size() const 
uint  get_num_mip_levels() const 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
132
174

---

5.10.13 
2D Multisampled Depth Texture 
The following member functions can be used to perform sampler-less reads from a 2D 
multisampled depth texture: 
T read(uint2 coord, uint sample) const 
T read(ushort2 coord, ushort sample) const 
The following 2D multisampled depth texture query member functions are provided. 
uint  get_width() const 
uint  get_height() const 
uint  get_num_samples() const 
5.10.14 
Texture Fence Functions 
The following member function is supported by texture types that can be declared with the 
access::read_write
 attribute:  
void  fence() 
The texture 
fence
 function ensures that writes to the texture by a thread become visible to 
subsequent reads from that texture by the same thread (i.e. the thread performing the write).  
The following example show how the texture 
fence
 function can be used to make sure that 
writes to a texture by a thread are visible to later reads to the same location by the same thread.  
kernel void 
my_kernel(texture2d texA,  
…, 
ushort2 gid [[thread_position_in_grid]]) 
{ 
float4 clr = …; 
texA.write(gid, clr); 
… 
// fence to ensure that writes by thread become  
// visible to later reads by thread 
texA.fence(); 
clr_new = texA.read(gid); 
… 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
133
174

---

} 
5.10.15 
Null Texture Functions 
The following function can be used to determine if a texture is a null texture.  
bool is_null_texture(texture1d); 
bool is_null_texture(texture1d_array); 
bool is_null_texture(texture2d); 
bool is_null_texture(texture2d_array); 
bool is_null_texture(texture3d); 
bool is_null_texture(texturecube); 
bool is_null_texture(texturecube_array); 
bool is_null_texture(texture2d_ms); 
bool is_null_texture(depth2d); 
bool is_null_texture(depth2d_array); 
bool is_null_texture(depthcube); 
bool is_null_texture(depthcube_array); 
bool is_null_texture(depth2d_ms); 
Returns 
true
 if the texture is a null texture and 
false
 otherwise. The behavior of calling any 
texture member function with a null texture is undefined. 
5.11 Pack and Unpack Functions 
This section lists the Metal functions for converting a vector floating-point data to and from a 
packed integer value. The functions are defined in the header 

. Refer to section 
7.7 for details on how to convert from a 8-bit, 10-bit or 16-bit signed or unsigned integer value 
to a normalized single- or half-precision floating-point value and vice-versa.  
5.11.1  
Unpack Integer(s); Convert to a Floating-Point Vector 
Table 30 lists functions that unpack multiple values from a single unsigned integer and then 
converts them into floating-point values that are stored in a vector. 
Table 30 Unpack Functions 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
134
174

---

5.11.2  
Convert Floating-Point Vector to Integers, then Pack the Integers 
Table 31 lists functions that start with a floating-point vector, converts the components into 
integer values, and then packs the multiple values into a single unsigned integer. 
Table 31 Pack Functions 
Built-in unpack functions
Description
float4 unpack_unorm4x8_to_float(uint x)  
float4 unpack_snorm4x8_to_float(uint x)  
half4 unpack_unorm4x8_to_half(uint x)  
half4 unpack_snorm4x8_to_half(uint x) 
Unpack a 32-bit unsigned integer 
into four 8-bit signed or unsigned 
integers and then convert each 8-bit 
signed or unsigned integer value to a 
normalized single- or half-precision 
floating-point value to generate a 4-
component vector.
float4 unpack_unorm4x8_srgb_to_float(uint 
x)  
half4 unpack_unorm4x8_srgb_to_half(uint x)  
Unpack a 32-bit unsigned integer 
into four 8-bit signed or unsigned 
integers and then convert each 8-bit 
signed or unsigned integer value to a 
normalized single- or half-precision 
floating-point value to generate a 4-
component vector. The r, g, and b 
color values are converted from 
sRGB to linear RGB.
float2 unpack_unorm2x16_to_float(uint x)  
float2 unpack_snorm2x16_to_float(uint x)  
half2 unpack_unorm2x16_to_half(uint x)  
half2 unpack_snorm2x16_to_half(uint x) 
Unpack a 32-bit unsigned integer 
into two 16-bit signed or unsigned 
integers and then convert each 16-
bit signed or unsigned integer value 
to a normalized single- or half-
precision floating-point value to 
generate a 2-component vector.
float4 unpack_unorm10a2_to_float(uint x)  
float3 unpack_unorm565_to_float(ushort x)  
half4 unpack_unorm10a2_to_half(uint x)  
half3 unpack_unorm565_to_half(ushort x)
Convert a 1010102 (10a2), or 565 
color value to the corresponding 
normalized single- or half-precision 
floating-point vector.
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
135
174

---