Metal Shading Language Specification - Apple Developer

Metal Shading Language Specification

Version 3.1

Developer

Contents

1 Introduction ...................................................................................................10

1.1 Purpose of This Document......................................................................................................10

1.2 Organization of This Specification ......................................................................................... 10

1.3 References ................................................................................................................................ 10

1.4 Metal and C++14 ...................................................................................................................... 11

1.4.1

Overloading ........................................................................................................................ 11

1.4.2

Templates ........................................................................................................................... 11

1.4.3

Preprocessing Directives .................................................................................................. 11

1.4.4

Restrictions......................................................................................................................... 11

1.5 Compiler and Preprocessor .................................................................................................... 12

1.5.1

Preprocessor Compiler Options ....................................................................................... 12

1.5.2

Preprocessor Definitions................................................................................................... 13

1.5.3

Math Intrinsics Compiler Options.....................................................................................13

1.5.4

Invariance Compiler Options ............................................................................................ 14

1.5.5

Optimization Compiler Options ........................................................................................ 14

1.5.6

Max Total Threadgroup Size Option................................................................................ 15

1.5.7

Texture Write Rounding Mode ......................................................................................... 15

1.5.8

Compiler Options to Enable Modules .............................................................................. 16

1.5.9

Compiler Options Controlling the Language Version .................................................... 16

1.5.10 Compiler Options to Request or Suppress Warnings .................................................... 18

1.5.11 Target Conditionals ........................................................................................................... 18

1.5.12 Dynamic Library Linker options........................................................................................18

1.5.13 Options for Compiling to GPU binaries ........................................................................... 18

1.5.14 Options for Generating Metal Library Symbol Files ....................................................... 19

1.6 Metal Coordinate Systems ...................................................................................................... 19

2 Data Types .................................................................................................... 22

2.1 Scalar Data Types ................................................................................................................... 22

2.2 Vector Data Types .................................................................................................................. 24

2.2.1

Accessing Vector Components....................................................................................... 26

2.2.2

Vector Constructors ......................................................................................................... 29

2.2.3

Packed Vector Types ....................................................................................................... 30

2.3 Matrix Data Types ................................................................................................................... 32

2.3.1

Accessing Matrix Components ....................................................................................... 33

2.3.2

Matrix Constructors .......................................................................................................... 34

2.4 SIMD-group Matrix Data Types............................................................................................. 35

2.5 Alignment of Data Types ........................................................................................................ 35

2.6 Atomic Data Types.................................................................................................................. 36

2.7 Pixel Data Types...................................................................................................................... 36

2.8 Buffers ...................................................................................................................................... 38

2023-06-02 | Copyright ? 2023 Apple Inc. | All Rights Reserved. Page 2 of 287

2.9 Textures ................................................................................................................................... 38

2.9.1

Texture Buffers ................................................................................................................. 40

2.10 Samplers ................................................................................................................................... 41

2.11 Imageblocks............................................................................................................................. 43

2.12 Aggregate Types..................................................................................................................... 45

2.12.1 Arrays of Textures, Texture Buffers, and Samplers ...................................................... 45

2.12.1.1

Array Element Access with its Operator .................................................................. 46

2.12.1.2

Array Capacity ............................................................................................................ 47

2.12.1.3

Constructors for Templated Arrays.......................................................................... 47

2.12.2 Structures of Buffers, Textures, and Samplers ............................................................. 48

2.13 Argument Buffers .................................................................................................................... 49

2.13.1 Tier 2 Hardware Support for Argument Buffers ............................................................. 51

2.14 Uniform Type ........................................................................................................................... 52

2.14.1 The Need for a Uniform Type .......................................................................................... 52

2.14.2 Behavior of the Uniform Type ......................................................................................... 53

2.14.3 Uniform Control Flow ....................................................................................................... 54

2.15 Visible Function Table ............................................................................................................ 55

2.16 Function Group Attribute........................................................................................................ 56

2.17 Ray Tracing Types .................................................................................................................. 56

2.17.1 Ray Tracing Intersection Tags......................................................................................... 56

2.17.2 Ray Type ............................................................................................................................ 60

2.17.3 Intersection Function Table ............................................................................................. 60

2.17.4 Intersection Result Type .................................................................................................. 62

2.17.5 Intersector Type................................................................................................................ 63

2.17.6 Acceleration Structure Type............................................................................................ 63

2.17.7 Intersection Query Type................................................................................................... 66

2.18 Interpolant Type ...................................................................................................................... 66

2.19 Mesh Shader Types ................................................................................................................ 67

2.19.1 Mesh Grid Property Type ................................................................................................. 67

2.19.2 Mesh Type ......................................................................................................................... 67

2.20 Type Conversions and Re-interpreting Data ........................................................................ 71

2.21 Implicit Type Conversions.......................................................................................................72

3 Operators ...................................................................................................... 73

3.1 Scalar and Vector Operators ................................................................................................. 73

3.2 Matrix Operators ..................................................................................................................... 76

4 Address Spaces ............................................................................................ 79

4.1 device Address Space ............................................................................................................ 79

4.2 constant Address Space ........................................................................................................ 80

4.3 thread Address Space ............................................................................................................ 80

4.4 threadgroup Address Space ................................................................................................... 81

4.4.1

SIMD-groups and Quad-groups ..................................................................................... 82

2023-06-02 | Copyright ? 2023 Apple Inc. | All Rights Reserved. Page 3 of 287

4.5 threadgroup_imageblock Address Space............................................................................ 82

4.6 ray_data Address Space ........................................................................................................ 82

4.7 object_data Address Space................................................................................................... 83

5 Function and Variable Declarations .............................................................. 84

5.1 Functions.................................................................................................................................. 84

5.1.1

Vertex Functions ............................................................................................................... 85

5.1.1.1

Post-Tessellation Vertex Functions ......................................................................... 85

5.1.1.2

Patch Type and Number of Control Points Per-Patch ........................................... 85

5.1.2

Fragment Functions.......................................................................................................... 86

5.1.3

Compute Functions (Kernels).......................................................................................... 87

5.1.4

Visible Functions............................................................................................................... 87

5.1.5

Stitchable Functions ......................................................................................................... 88

5.1.6

Intersection Functions...................................................................................................... 88

5.1.7

Object Functions............................................................................................................... 89

5.1.8

Mesh Functions................................................................................................................. 90

5.1.9

Tile Functions ..................................................................................................................... 91

5.1.10 Host Name Attribute..........................................................................................................91

5.1.11 Templated Qualified Functions ....................................................................................... 92

5.2 Function Arguments and Variables ....................................................................................... 92

5.2.1

Locating Buffer, Texture, and Sampler Arguments....................................................... 93

5.2.1.1

Vertex Function Example with Resources and Outputs to Device Memory......... 94

5.2.1.2

Raster Order Groups .................................................................................................. 95

5.2.2

Attributes to Locate Per-Vertex Inputs .......................................................................... 96

5.2.3

Attributes for Built-in Variables ....................................................................................... 99

5.2.3.1

Vertex Function Input Attributes............................................................................... 99

5.2.3.2

Post-Tessellation Vertex Function Input Attributes ............................................. 100

5.2.3.3

Vertex Function Output Attributes .......................................................................... 101

5.2.3.4

Fragment Function Input Attributes ....................................................................... 103

5.2.3.5

Fragment Function Output Attributes .................................................................... 109

5.2.3.6

Kernel Function Input Attributes .............................................................................. 110

5.2.3.7

Intersection Function Input Attributes .................................................................... 116

5.2.3.8

Intersection Function Output Attributes .................................................................120

5.2.3.9

Object Function Input Attributes ............................................................................. 121

5.2.3.10

Mesh Function Input Attributes ...............................................................................125

5.2.4

Input Assembly Attribute ................................................................................................128

5.2.4.1

Vertex Function Output Example.............................................................................128

5.2.4.2

Fragment Function Input Example...........................................................................129

5.2.4.3

Kernel Function Per-Thread Input Example .......................................................... 130

5.3 Storage Class Specifiers ....................................................................................................... 131

5.4 Sampling and Interpolation Attributes ................................................................................. 131

5.5 Per-Fragment Function versus Per-Sample Function .......................................................133

5.6 Imageblock Attributes .......................................................................................................... 134

2023-06-02 | Copyright ? 2023 Apple Inc. | All Rights Reserved. Page 4 of 287

5.6.1

Matching Data Members of Master and View Imageblocks ...................................... 134

5.6.2

Imageblocks and Raster Order Groups .........................................................................137

5.6.3

Imageblock Layouts for Fragment Functions .............................................................. 139

5.6.3.1

Implicit Imageblock Layout for Fragment Functions ............................................ 139

5.6.3.2

Explicit Imageblock Layout for Fragment Functions ............................................ 139

5.6.4 Imageblock Layouts in Kernel Functions....................................................................... 141

5.6.5 Aliasing Explicit and Implicit Imageblocks ....................................................................142

5.6.6 Imageblocks and Function Constants ...........................................................................142

5.7 Graphics Function ? Signature Matching ........................................................................... 143

5.7.1

Vertex ? Fragment Signature Matching ....................................................................... 143

5.7.2

Mesh ? Fragment Signature Matching ..........................................................................147

5.8 Program Scope Function Constants ....................................................................................147

5.8.1

Specifying Program Scope Function Constants.......................................................... 148

5.8.1.1

Function Constants to Control Code Paths to Compile ....................................... 149

5.8.1.2

Function Constants when Declaring the Arguments of Functions ......................150

5.8.1.3

Function Constants for Elements of an Input Assembly Structure ......................152

5.8.1.4

Function Constants for Resource Bindings ............................................................152

5.8.1.5

Function Constants for Color Attachments and Raster Order Groups................153

5.8.1.6

Function Constants with Elements of a Structure .................................................153

5.9 Program Scope Global Built-ins .......................................................................................... 154

5.10 Per-Primitive Viewport and Scissor Rectangle Index Selection....................................... 154

5.11 Additional Restrictions...........................................................................................................155

6 Metal Standard Library ................................................................................156

6.1 Namespace and Header Files .............................................................................................. 156

6.2 Common Functions ............................................................................................................... 156

6.3 Integer Functions ...................................................................................................................157

6.4 Relational Functions.............................................................................................................. 159

6.5 Math Functions ...................................................................................................................... 160

6.6 Matrix Functions .................................................................................................................... 166

6.7 SIMD-group Matrix Functions...............................................................................................167

6.7.1

Creating, Loading, and Storing Matrix Elements..........................................................167

6.7.2

Matrix Operations ........................................................................................................... 168

6.8 Geometric Functions............................................................................................................. 169

6.9 Synchronization and SIMD-group Functions ......................................................................170

6.9.1

Threadgroup and SIMD-group Synchronization Functions ........................................170

6.9.2 SIMD-group Functions .................................................................................................... 171

6.9.2.1

Examples .................................................................................................................... 177

6.9.3 Quad-group Functions ................................................................................................... 180

6.10 Graphics Functions ............................................................................................................... 188

6.10.1 Fragment Functions........................................................................................................ 188

6.10.1.1

Fragment Functions ? Derivatives .......................................................................... 188

2023-06-02 | Copyright ? 2023 Apple Inc. | All Rights Reserved. Page 5 of 287

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download