Metal Shading Language Specification - Apple Developer

1 Metal Shading Language Specification Version Developer 2022-03-16 | Copyright 2022 Apple Inc. | All Rights Reserved. Page 2 of 248 Contents 1 Introduction .. 9 Purpose of This Document .. 9 Organization of This Specification .. 9 References .. 9 Metal and C++14 .. 10 Overloading .. 10 Templates .. 10 Preprocessing Directives .. 10 Restrictions .. 10 Compiler and Preprocessor .. 11 Preprocessor Compiler Options .. 11 Preprocessor Definitions .. 11 Math Intrinsics Compiler Options .. 12 Invariance Compiler Options .. 12 Texture Write Rounding Mode .. 13 Compiler Options to Enable Modules .. 13 Compiler Options Controlling the Language Version .. 14 Compiler Options to Request or Suppress Warnings.

2 15 Target Conditionals .. 15 Dynamic Library Linker options .. 15 Metal Coordinate Systems .. 16 2 Data Types .. 18 Scalar Data Types .. 18 Vector Data Types .. 20 Accessing Vector Components .. 22 Vector Constructors .. 24 Packed Vector Types .. 26 Matrix Data Types .. 28 Accessing Matrix Components .. 29 Matrix Constructors .. 30 SIMD-group Matrix Data Types .. 31 Alignment of Data Types .. 31 Atomic Data Types .. 31 Pixel Data Types .. 32 Buffers .. 33 Textures .. 34 Texture Buffers .. 36 Samplers .. 37 Imageblocks .. 39 2022-03-16 | Copyright 2022 Apple Inc. | All Rights Reserved. Page 3 of 248 Aggregate Types .. 41 Arrays of Textures, Texture Buffers, and Samplers.

3 41 Array Element Access with its Operator .. 42 Array Capacity .. 42 Constructors for Templated Arrays .. 43 Structures of Buffers, Textures, and Samplers .. 44 Argument Buffers .. 45 Tier 2 Hardware Support for Argument Buffers .. 46 Uniform Type .. 48 The Need for a Uniform Type .. 48 Behavior of the Uniform Type .. 49 Uniform Control Flow .. 50 Visible Function Table .. 50 Function Group Attribute .. 51 Ray Tracing Types .. 52 Ray Tracing Intersection Tags .. 52 Ray Type .. 54 Intersection Function Table .. 55 Intersection Result Type .. 55 Intersector Type .. 56 Acceleration Structure Type .. 56 Intersection Query Type .. 58 Interpolant Type .. 59 Type Conversions and Re-interpreting Data.

4 59 Implicit Type Conversions .. 60 3 Operators .. 62 Scalar and Vector Operators .. 62 Matrix Operators .. 65 4 Address Spaces .. 68 device Address Space .. 68 constant Address Space .. 69 thread Address Space .. 69 threadgroup Address Space .. 70 SIMD-groups and Quad-groups .. 70 threadgroup_imageblock Address Space .. 71 ray_data Address Space .. 71 5 Function and Variable Declarations .. 72 Functions .. 72 Vertex Functions .. 72 Post-Tessellation Vertex Functions .. 73 Patch Type and Number of Control Points Per-Patch .. 73 2022-03-16 | Copyright 2022 Apple Inc. | All Rights Reserved. Page 4 of 248 Fragment Functions .. 74 Compute Functions (Kernels) .. 75 Visible Functions.

5 75 Stitchable Functions .. 75 Intersection Functions .. 76 Tile Functions .. 77 Host Name Attribute .. 77 Templated Qualified Functions .. 78 Function Arguments and Variables .. 78 Locating Buffer, Texture, and Sampler Arguments .. 79 Vertex Function Example with Resources and Outputs to Device Memory .. 80 Raster Order Groups .. 81 Attributes to Locate Per-Vertex Inputs .. 82 Attributes for Built-in Variables .. 85 Vertex Function Input Attributes .. 85 Post-Tessellation Vertex Function Input Attributes .. 86 Vertex Function Output Attributes .. 87 Fragment Function Input Attributes .. 89 Fragment Function Output Attributes .. 95 Kernel Function Input Attributes .. 96 Intersection Function Input Attributes.

6 101 Intersection Function Output Attributes .. 104 Input Assembly Attribute .. 106 Vertex Function Output Example .. 106 Fragment Function Input Example .. 107 Kernel Function Per-Thread Input Example .. 108 Storage Class Specifiers .. 109 Sampling and Interpolation Attributes .. 109 Per-Fragment Function versus Per-Sample Function .. 110 Imageblock Attributes .. 111 Matching Data Members of Master and View Imageblocks .. 111 Imageblocks and Raster Order Groups .. 114 Imageblock Layouts for Fragment Functions .. 116 Implicit Imageblock Layout for Fragment Functions .. 116 Explicit Imageblock Layout for Fragment Functions .. 116 Imageblock Layouts in Kernel Functions .. 118 Aliasing Explicit and Implicit Imageblocks.

7 119 Imageblocks and Function Constants .. 120 Graphics Function Signature Matching .. 120 Vertex Fragment Signature Matching .. 120 Program Scope Function Constants .. 124 Specifying Program Scope Function Constants .. 124 2022-03-16 | Copyright 2022 Apple Inc. | All Rights Reserved. Page 5 of 248 Function Constants to Control Code Paths to Compile .. 125 Function Constants when Declaring the Arguments of Functions .. 126 Function Constants for Elements of an Input Assembly Structure .. 128 Function Constants for Resource Bindings .. 129 Function Constants for Color Attachments and Raster Order Groups .. 129 Function Constants with Elements of a Structure .. 130 Per-Primitive Viewport and Scissor Rectangle Index Selection.

8 130 Additional Restrictions .. 131 6 Metal Standard Library .. 132 Namespace and Header Files .. 132 Common Functions .. 132 Integer Functions .. 133 Relational Functions .. 135 Math Functions .. 136 Matrix Functions .. 141 SIMD-group Matrix Functions .. 142 Creating, Loading, and Storing Matrix Elements .. 142 Matrix Operations .. 143 Geometric Functions .. 144 Synchronization and SIMD-group Functions .. 145 Threadgroup and SIMD-group Synchronization Functions .. 145 SIMD-group Functions .. 146 Examples .. 151 Quad-group Functions .. 155 Graphics Functions .. 162 Fragment Functions .. 163 Fragment Functions Derivatives .. 163 Fragment Functions Samples .. 163 Fragment Functions Flow Control.

9 164 Pull-Model interpolation .. 164 Texture Functions .. 165 1D Texture .. 169 1D Texture Array .. 169 2D Texture .. 170 2D Texture Sampling Example .. 173 2D Texture Array .. 173 3D Texture .. 175 Cube Texture .. 177 Cube Texture Array .. 179 2D Multisampled Texture .. 182 2D Multisampled Texture Array .. 182 2022-03-16 | Copyright 2022 Apple Inc. | All Rights Reserved. Page 6 of 248 2D Depth Texture .. 183 2D Depth Texture Array .. 186 2D Multisampled Depth Texture .. 190 2D Multisampled Depth Texture Array .. 190 Cube Depth Texture .. 191 Cube Depth Texture Array .. 193 Texture Buffer Functions .. 196 Texture Synchronization Functions .. 197 Null Texture Functions.

10 198 Imageblock Functions .. 198 Functions for Imageblocks with Implicit Layout .. 199 Functions for Imageblocks with Explicit Layout .. 200 Writing an Imageblock Slice to a Region in a Texture .. 201 Pack and Unpack Functions .. 205 Unpack and Convert Integers to a Floating-Point Vector .. 205 Convert Floating-Point Vector to Integers, then Pack the Integers .. 206 Atomic Functions .. 207 Memory Order .. 207 Atomic Functions .. 207 Atomic Store Functions .. 208 Atomic Load Functions .. 208 Atomic Exchange Functions .. 208 Atomic Compare and Exchange Functions .. 209 Atomic Fetch and Modify Functions .. 209 Encoding Commands for Indirect Command Buffers .. 210 Encoding Render Commands in Indirect Command Buffers.