Framework

Metal

Render advanced 3D graphics and perform data-parallel computations. Get fine-grained access to the GPU while minimizing CPU overhead.

Overview

The Metal Framework provides extremely low-overhead access to the GPU, enabling incredibly high performance for your sophisticated graphics rendering and computational tasks. Metal eliminates many performance bottlenecks—such as costly state validation—that are found in traditional graphics APIs. Metal moves all expensive state translation and compilation operations out of the critical path of your most performance sensitive rendering code. It provides precompiled shaders, state objects, and explicit command scheduling to ensure that your application achieves the highest possible performance and efficiency.

Graphics, compute, and blit commands can be used together seamlessly and efficiently. Metal is specifically designed to exploit modern architectural considerations, such as multiprocessing and shared memory, to make it easy to parallelize the creation of GPU commands.

Symbols

Classes

MTLArgument

A MTLArgument object describes a single argument to a Metal function. Your app uses the MTLArgument properties to read details about a function argument as it was defined in the Metal Shading Language. You can determine the argument’s data type, access restrictions, and its associated resource type. For buffer, texture, and threadgroup memory arguments, additional properties can be read to determine more details about the argument.

MTLArray​Type

A MTLArray​Type object provides details about a MTLStruct​Member object that is an array. Your app does not create a MTLArray​Type or MTLStruct​Member object directly. A reflection object, MTLRender​Pipeline​Reflection or MTLCompute​Pipeline​Reflection, can contain a MTLStruct​Member object, if one of its arguments is a struct (that is, if the buffer​Data​Type property of MTLArgument is struct). If the data​Type property of MTLStruct​Member is array, then the MTLStruct​Member object is an array, and the array​Type() method of MTLStruct​Member returns a MTLArray​Type object that contains array details such as length, stride, and element type.

MTLAttribute

An object which represents the attributes of a function.

MTLAttribute​Descriptor

An object that determines how attribute data is stored in memory and how it is mapped to arguments for a function.

MTLAttribute​Descriptor​Array

An array of objects that define how attribute data is formatted and assigned to an index in the attribute argument table.

MTLBuffer​Layout​Descriptor

An object that is used to configure how function input and attribute data are fetched by a function.

MTLBuffer​Layout​Descriptor​Array

An array of buffer layout states.

MTLCompile​Options

A MTLCompile​Options object is used to specify how a new Metal shader library should be compiled. If you want to set the following options, use standard allocation and initialization techniques to create a MTLCompile​Options object and then set any or all of these properties:

MTLCompute​Pipeline​Descriptor

The MTLCompute​Pipeline​Descriptor object specifies the compute configuration state used during a compute operation pass. Use standard allocation and initialization techniques to create a MTLCompute​Pipeline​Descriptor object. A MTLCompute​Pipeline​Descriptor object is later used to create a MTLCompute​Pipeline​State object.

MTLCompute​Pipeline​Reflection

A MTLCompute​Pipeline​Reflection object provides access to the arguments of the compute function used in a MTLCompute​Pipeline​State object. A MTLCompute​Pipeline​Reflection object can be created along with a MTLCompute​Pipeline​State object. Do not use standard allocation and initialization techniques to create a MTLCompute​Pipeline​Reflection object.

MTLDepth​Stencil​Descriptor

A MTLDepth​Stencil​Descriptor object is used to define a specific configuration of the depth and stencil stages of a rendering pipeline. To create a MTLDepth​Stencil​Descriptor object, use standard allocation and initialization techniques.

MTLFunction​Constant

A MTLFunction​Constant object describes a function constant referenced in a graphics or compute function.

MTLFunction​Constant​Values

A MTLFunction​Constant​Values object contains a set of constant values that specialize a graphics or compute function.

MTLHeap​Descriptor

A MTLHeap​Descriptor object is used to configure new MTLHeap objects.

MTLRender​Pass​Attachment​Descriptor

A MTLRender​Pass​Attachment​Descriptor object is used to configure an individual render target of a framebuffer. Each MTLRender​Pass​Attachment​Descriptor object specifies one texture that a graphics rendering pass can write into.

MTLRender​Pass​Color​Attachment​Descriptor

A MTLRender​Pass​Color​Attachment​Descriptor object is used to configure an individual render target whose texture has a color-renderable pixel format.

MTLRender​Pass​Depth​Attachment​Descriptor

A MTLRender​Pass​Depth​Attachment​Descriptor object is used to configure an individual render target whose texture has a depth-renderable pixel format.

MTLRender​Pass​Descriptor

A MTLRender​Pass​Descriptor object contains a collection of attachments that are the rendering destination for pixels generated by a rendering pass. The MTLRender​Pass​Descriptor class is also used to set the destination buffer for visibility information generated by a rendering pass.

MTLRender​Pass​Stencil​Attachment​Descriptor

A MTLRender​Pass​Stencil​Attachment​Descriptor object is used to configure an individual render target that has a texture with a stencil-renderable pixel format.

MTLRender​Pipeline​Color​Attachment​Descriptor

A MTLRender​Pipeline​Color​Attachment​Descriptor object defines the configuration of a color attachment associated with a rendering pipeline.

MTLRender​Pipeline​Color​Attachment​Descriptor​Array

A MTLRender​Pipeline​Color​Attachment​Descriptor​Array object contains an array of render pipeline states for an array of color attachments. The methods of MTLRender​Pipeline​Color​Attachment​Descriptor​Array set the render pipeline state or retrieve a copy of the render pipeline state for one of the color attachments in the array.

MTLRender​Pipeline​Descriptor

The MTLRender​Pipeline​Descriptor object specifies the rendering configuration state used during a rendering pass, including rasterization (such as multisampling), visibility, blending, tessellation, and graphics function state. Use standard allocation and initialization techniques to create a MTLRender​Pipeline​Descriptor object. A MTLRender​Pipeline​Descriptor object is later used to create a MTLRender​Pipeline​State object.

MTLRender​Pipeline​Reflection

A MTLRender​Pipeline​Reflection object provides access to the arguments of a vertex or fragment function of a MTLRender​Pipeline​State object. A MTLRender​Pipeline​Reflection object can be created along with a MTLRender​Pipeline​State object. Do not use standard allocation and initialization techniques to create a MTLRender​Pipeline​Reflection object.

MTLSampler​Descriptor

MTLSampler​Descriptor objects are used to define a specific configuration of a MTLSampler​State object.

MTLStage​Input​Output​Descriptor

An object that describes the inputs, outputs, and attribute data to Metal vertex, fragment or compute functions.

MTLStencil​Descriptor

A MTLStencil​Descriptor object is used to configure a stencil test operation.

MTLStruct​Member

MTLStruct​Member is part of the reflection API that allows Metal framework code to query details about an argument of a Metal shading language function. A MTLStruct​Member object describes the data type of one field in a struct that is passed as a MTLFunction argument, which is represented by MTLArgument.

MTLStruct​Type

MTLStruct​Type is part of the reflection API that allows Metal framework code to query details of a struct that is passed as an argument of a Metal shading language function. You do not allocate or initialize MTLStruct​Type objects. To obtain a MTLStruct​Type object, you can query the buffer​Struct​Type property of a MTLArgument object, or call the struct​Type() method for a MTLStruct​Member object. To examine the details of the struct, you can recursively drill down the members property of the MTLStruct​Type object, which contains details about struct members, each of which is represented by a MTLStruct​Member object.

MTLTexture​Descriptor

A MTLTexture​Descriptor object is used to configure new texture objects.

MTLVertex​Attribute

A MTLVertex​Attribute object represents an attribute for per-vertex input in a vertex function. You use vertex attribute objects to inspect the inputs of a vertex function by examining the vertex​Attributes property of the corresponding MTLFunction object.

MTLVertex​Attribute​Descriptor

MTLVertex​Attribute​Descriptor determines how vertex attribute data is stored in memory and how it is mapped to arguments for a vertex shader function.

MTLVertex​Attribute​Descriptor​Array

A MTLVertex​Attribute​Descriptor​Array object is an array of objects that defines how vertex attribute data is formatted and assigned to an index in the attribute argument table. The methods of MTLVertex​Attribute​Descriptor​Array set or retrieve the attribute formatting information from the array.

MTLVertex​Buffer​Layout​Descriptor

A MTLVertex​Buffer​Layout​Descriptor object is used to configure how vertex and attribute data are fetched by a vertex function.

MTLVertex​Buffer​Layout​Descriptor​Array

A MTLVertex​Buffer​Layout​Descriptor​Array holds an array of vertex buffer layout states. The methods of MTLVertex​Buffer​Layout​Descriptor​Array set the vertex buffer layout state in the array or retrieve the state from the array.

MTLVertex​Descriptor

A MTLVertex​Descriptor object is used to configure how vertex data stored in memory is mapped to attributes in a vertex shader.

Protocols

MTLBlit​Command​Encoder

The MTLBlit​Command​Encoder protocol is used to define the interface for objects that can encode resource-copying commands into a command buffer. Use these commands to manage the contents of textures and buffers.

MTLBuffer

The MTLBuffer protocol defines the interface for objects that represent an allocation of unformatted, device-accessible memory that can contain any type of data. Your app does not define classes that implement this protocol.

MTLCommand​Buffer

A transient, single-use buffer that stores encoded commands which are committed to and executed by the GPU.

MTLCommand​Encoder

The MTLCommand​Encoder protocol defines the common interface for objects that can write commands into a command buffer.

MTLCommand​Queue

The MTLCommand​Queue protocol defines the interface for an object that can queue an ordered list of command buffers for a Metal device to execute. In general, command queues are thread-safe and allow multiple outstanding command buffers to be encoded simultaneously.

MTLCompute​Command​Encoder

Methods that allow the encoding of commands that specify the data-parallel compute processing state and execute the compute function.

MTLCompute​Pipeline​State

The MTLCompute​Pipeline​State protocol defines the interface for a lightweight object used to encode a reference to a compiled compute program. A MTLCompute​Pipeline​State object is fully thread-safe and can be used by many MTLCompute​Command​Encoder objects, even if they are associated with different command buffers.

MTLDepth​Stencil​State

The MTLDepth​Stencil​State protocol defines the interface for a lightweight object used to encode how a graphics rendering pass should perform depth and stencil operations. The MTLRender​Command​Encoder uses a MTLDepth​Stencil​State object to set the depth and stencil state for a rendering pass.

MTLDevice

The MTLDevice protocol defines the interface to a single graphics processor (GPU). You use an object that conforms to this protocol to query the capabilities of the processor and to allocate objects used to access those capabilities.

MTLDrawable

A displayable resource that can be rendered or written to.

MTLFence

The MTLFence protocol defines the interface for an object that can track and manage resource dependencies across command encoders.

MTLFunction

The MTLFunction protocol defines the interface for an object that represents a single graphics or compute function.

MTLHeap

The MTLHeap protocol defines the interface for an object that represents an abstract memory pool.

MTLLibrary

The MTLLibrary protocol defines the interface for an object that represents a library of graphics or compute functions.

MTLParallel​Render​Command​Encoder

The MTLParallel​Render​Command​Encoder protocol is used to define the interface for objects that can break up a single graphics rendering pass so that it can be encoded from multiple threads simultaneously.

MTLRender​Command​Encoder

The MTLRender​Command​Encoder protocol is used to define the interface for objects that encode graphics rendering state and commands into a command buffer. Your app does not define classes that implement this protocol.

MTLRender​Pipeline​State

The MTLRender​Pipeline​State protocol defines the interface for a lightweight object used to encode the state for a configured graphics rendering pipeline.

MTLResource

The MTLResource protocol defines the interface for any resource object that represents an allocation of memory.

MTLSampler​State

The MTLSampler​State protocol defines the interface for a lightweight object used to encode how a shader or compute kernel should sample a texture. To create a sampler state object:

MTLTexture

The MTLTexture protocol defines the interface for an object that represents an allocation of formatted image data. Textures are used as source data for a vertex shader, a fragment shader, or a compute kernel. They are also used as an attachment that acts as a rendering destination.

Structures

MTLBlit​Option

Options for controlling a blit operation.

MTLColor​Write​Mask

Values used to specify a mask to permit or restrict writing to color channels of a color value. The values red, green, blue, and alpha select one color channel each, and they can be bitwise combined.

MTLCommand​Buffer​ErrorMTLLibrary​Error
MTLPipeline​Option

Controls which argument information is made available for reflection by the creation of the pipeline.

MTLRender​Pipeline​ErrorMTLRender​Stages
MTLResource​Options

Optional arguments used to create and influence behavior of buffer and texture objects.

MTLTexture​Usage

The options that describe how a texture will be used in your app.