MTLDevice

Inherits From

---

Not Applicable

Conforms To

---

Not Applicable

Import Statement

---

OBJECTIVE-C

@import Metal;

Availability

---

Available in iOS 8.0 and later 

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.

Your app does not define classes that implement this protocol; it is used by Metal to provide a device object to your app. To obtain a system device, call the MTLCreateSystemDefaultDevice function or select a result from the MTLCopyAllDevices function.

Most objects in Metal that perform graphics rendering and computational work are associated directly with a specific device. For example, texture objects are created by a device object and can be used only with that device. Most methods on a MTLDevice object create non-transient objects, including command queues, resources (such as buffers and textures), and pipeline states. These objects can be expensive to create and you are encouraged to create them soon after your app launches and reuse them throughout the lifetime of your app. Avoid creating these objects in performance sensitive code.

Identifying Properties

• maxThreadsPerThreadgroup  Required  Property
• name  Required  Property
• - supportsFeatureSet:  Required
• - supportsTextureSampleCount:  Required

Creating Metal Shader Libraries

• - newDefaultLibrary  Required
• - newLibraryWithFile:error:  Required
• - newLibraryWithSource:options:completionHandler:  Required
• - newLibraryWithSource:options:error:  Required
• - newLibraryWithData:error:  Required

Creating Command Queues

• - newCommandQueue  Required
• - newCommandQueueWithMaxCommandBufferCount:  Required

Creating Resources

• - newBufferWithLength:options:  Required
• - newBufferWithBytes:length:options:  Required
• - newBufferWithBytesNoCopy:length:options:deallocator:  Required
• - newTextureWithDescriptor:  Required
• - newSamplerStateWithDescriptor:  Required

Creating Command Objects Needed to Render Graphics

• - newDepthStencilStateWithDescriptor:  Required
• - newRenderPipelineStateWithDescriptor:completionHandler:  Required
  Asynchronously creates and returns a render pipeline state object.

  Declaration

  OBJECTIVE-C

  - (void)newRenderPipelineStateWithDescriptor:(MTLRenderPipelineDescriptor *)descriptor
                           completionHandler:(MTLNewRenderPipelineStateCompletionHandler)completionHandler


  Parameters

  descriptor	A descriptor object that contains graphics rendering state properties, including rasterization, visibility, function, and blend state.
  completionHandler	A block of code that is invoked when the logic to create the render pipeline state object is completed.

  Discussion

  To use the graphics rendering pipeline state for a rendering pass, call the setRenderPipelineState: method of a MTLRenderCommandEncoder object with the MTLRenderPipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newRenderPipelineStateWithDescriptor:options:completionHandler:  Required
• - newRenderPipelineStateWithDescriptor:error:  Required
  Synchronously creates and returns a render pipeline state object.

  Declaration

  OBJECTIVE-C

  - (id<MTLRenderPipelineState>)newRenderPipelineStateWithDescriptor:(MTLRenderPipelineDescriptor *)descriptor
                                                             error:(NSError * _Nullable *)error


  Parameters

  descriptor	A descriptor object that contains graphics rendering state properties, including rasterization, visibility, programmable shader, and blend state.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object with the compiled graphics rendering pipeline state.

  Discussion

  To use the graphics rendering pipeline state for a rendering pass, call the setRenderPipelineState: method of a MTLRenderCommandEncoder object with the MTLRenderPipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newRenderPipelineStateWithDescriptor:options:reflection:error:  Required

Creating Command Objects Needed to Perform Computational Tasks

• - newComputePipelineStateWithFunction:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object that represents a compiled compute function.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                          completionHandler:(MTLNewComputePipelineStateCompletionHandler)completionHandler


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:options:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                    options:(MTLPipelineOption)options
                          completionHandler:(MTLNewComputePipelineStateWithReflectionCompletionHandler)completionHandler


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  options	The type of reflection information that should be returned.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:error:  Required
  Synchronously creates a new compute pipeline state object that represents a compiled compute function.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                                             error:(NSError * _Nullable *)error


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object that can be used as a compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:options:reflection:error:  Required
  Synchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                                           options:(MTLPipelineOption)options
                                                        reflection:(MTLAutoreleasedComputePipelineReflection *)reflection
                                                             error:(NSError * _Nullable *)error


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  options	The type of reflection information that should be returned.
  reflection	Reflection data about the compute function, including details about function arguments.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object that can be used as a compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithDescriptor:options:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithDescriptor:(MTLComputePipelineDescriptor *)descriptor
                                      options:(MTLPipelineOption)options
                            completionHandler:(MTLNewComputePipelineStateWithReflectionCompletionHandler)completionHandler


  Parameters

  descriptor	A descriptor object that contains compute properties.
  options	The type of reflection information that should be returned.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 9.0 and later.

• - newComputePipelineStateWithDescriptor:options:reflection:error:  Required
  Synchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithDescriptor:(MTLComputePipelineDescriptor *)descriptor
                                                             options:(MTLPipelineOption)options
                                                          reflection:(MTLAutoreleasedComputePipelineReflection *)reflection
                                                               error:(NSError * _Nullable *)error


  Parameters

  descriptor	A descriptor object that contains compute properties.
  options	The type of reflection information that should be returned.
  reflection	Reflection data about the compute function, including details about function arguments.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object with the compiled compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 9.0 and later.

Data Types

• MTLNewLibraryCompletionHandler
• MTLNewRenderPipelineStateCompletionHandler
  A block of code that is invoked when the logic to create a MTLRenderPipelineState object is completed.

  Declaration

  OBJECTIVE-C

  typedef void (^MTLNewRenderPipelineStateCompletionHandler)(id <MTLRenderPipelineState> __nullable renderPipelineState, NSError * __nullable error)

  Discussion

  The completion handler takes the following parameters:

  renderPipelineState	A new render pipeline state object that contains the compiled graphics rendering state, or nil if an error occurred.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Import Statement

  OBJECTIVE-C

  @import Metal;

  Availability

  Available in iOS 9.0 and later.

• MTLNewRenderPipelineStateWithReflectionCompletionHandler
• MTLNewComputePipelineStateCompletionHandler
  A block of code that is invoked when the logic to create a MTLComputePipelineState object is completed.

  Declaration

  OBJECTIVE-C

  typedef void (^MTLNewComputePipelineStateCompletionHandler)(id <MTLComputePipelineState> __nullable computePipelineState, NSError * __nullable error)

  Discussion

  The completion handler takes the following parameters:

  computePipelineState	A new compute pipeline state object that contains the compiled compute pipeline state, or nil if an error occurred.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Import Statement

  OBJECTIVE-C

  @import Metal;

  Availability

  Available in iOS 9.0 and later.

• MTLNewComputePipelineStateWithReflectionCompletionHandler
• MTLAutoreleasedRenderPipelineReflection
• MTLAutoreleasedComputePipelineReflection

Constants

• MTLFeatureSet
• MTLPipelineOption
• 
  

Inherits From

---

Not Applicable

Conforms To

---

Not Applicable

Import Statement

---

OBJECTIVE-C

@import Metal;

Availability

---

Available in iOS 8.0 and later 

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.

Your app does not define classes that implement this protocol; it is used by Metal to provide a device object to your app. To obtain a system device, call the MTLCreateSystemDefaultDevice function or select a result from the MTLCopyAllDevices function.

Most objects in Metal that perform graphics rendering and computational work are associated directly with a specific device. For example, texture objects are created by a device object and can be used only with that device. Most methods on a MTLDevice object create non-transient objects, including command queues, resources (such as buffers and textures), and pipeline states. These objects can be expensive to create and you are encouraged to create them soon after your app launches and reuse them throughout the lifetime of your app. Avoid creating these objects in performance sensitive code.

Identifying Properties

• maxThreadsPerThreadgroup  Required  Property
• name  Required  Property
• - supportsFeatureSet:  Required
• - supportsTextureSampleCount:  Required

Creating Metal Shader Libraries

• - newDefaultLibrary  Required
• - newLibraryWithFile:error:  Required
• - newLibraryWithSource:options:completionHandler:  Required
• - newLibraryWithSource:options:error:  Required
• - newLibraryWithData:error:  Required

Creating Command Queues

• - newCommandQueue  Required
• - newCommandQueueWithMaxCommandBufferCount:  Required

Creating Resources

• - newBufferWithLength:options:  Required
• - newBufferWithBytes:length:options:  Required
• - newBufferWithBytesNoCopy:length:options:deallocator:  Required
• - newTextureWithDescriptor:  Required
• - newSamplerStateWithDescriptor:  Required

Creating Command Objects Needed to Render Graphics

• - newDepthStencilStateWithDescriptor:  Required
• - newRenderPipelineStateWithDescriptor:completionHandler:  Required
  Asynchronously creates and returns a render pipeline state object.

  Declaration

  OBJECTIVE-C

  - (void)newRenderPipelineStateWithDescriptor:(MTLRenderPipelineDescriptor *)descriptor
                           completionHandler:(MTLNewRenderPipelineStateCompletionHandler)completionHandler


  Parameters

  descriptor	A descriptor object that contains graphics rendering state properties, including rasterization, visibility, function, and blend state.
  completionHandler	A block of code that is invoked when the logic to create the render pipeline state object is completed.

  Discussion

  To use the graphics rendering pipeline state for a rendering pass, call the setRenderPipelineState: method of a MTLRenderCommandEncoder object with the MTLRenderPipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newRenderPipelineStateWithDescriptor:options:completionHandler:  Required
• - newRenderPipelineStateWithDescriptor:error:  Required
  Synchronously creates and returns a render pipeline state object.

  Declaration

  OBJECTIVE-C

  - (id<MTLRenderPipelineState>)newRenderPipelineStateWithDescriptor:(MTLRenderPipelineDescriptor *)descriptor
                                                             error:(NSError * _Nullable *)error


  Parameters

  descriptor	A descriptor object that contains graphics rendering state properties, including rasterization, visibility, programmable shader, and blend state.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object with the compiled graphics rendering pipeline state.

  Discussion

  To use the graphics rendering pipeline state for a rendering pass, call the setRenderPipelineState: method of a MTLRenderCommandEncoder object with the MTLRenderPipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newRenderPipelineStateWithDescriptor:options:reflection:error:  Required

Creating Command Objects Needed to Perform Computational Tasks

• - newComputePipelineStateWithFunction:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object that represents a compiled compute function.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                          completionHandler:(MTLNewComputePipelineStateCompletionHandler)completionHandler


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:options:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                    options:(MTLPipelineOption)options
                          completionHandler:(MTLNewComputePipelineStateWithReflectionCompletionHandler)completionHandler


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  options	The type of reflection information that should be returned.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:error:  Required
  Synchronously creates a new compute pipeline state object that represents a compiled compute function.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                                             error:(NSError * _Nullable *)error


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object that can be used as a compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithFunction:options:reflection:error:  Required
  Synchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithFunction:(id<MTLFunction>)function
                                                           options:(MTLPipelineOption)options
                                                        reflection:(MTLAutoreleasedComputePipelineReflection *)reflection
                                                             error:(NSError * _Nullable *)error


  Parameters

  function	A function object to be compiled into a compute pipeline state object.
  options	The type of reflection information that should be returned.
  reflection	Reflection data about the compute function, including details about function arguments.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object that can be used as a compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 8.0 and later.

• - newComputePipelineStateWithDescriptor:options:completionHandler:  Required
  Asynchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (void)newComputePipelineStateWithDescriptor:(MTLComputePipelineDescriptor *)descriptor
                                      options:(MTLPipelineOption)options
                            completionHandler:(MTLNewComputePipelineStateWithReflectionCompletionHandler)completionHandler


  Parameters

  descriptor	A descriptor object that contains compute properties.
  options	The type of reflection information that should be returned.
  completionHandler	A block of code that is invoked when the logic to create the compute pipeline state object is completed.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  Availability

  Available in iOS 9.0 and later.

• - newComputePipelineStateWithDescriptor:options:reflection:error:  Required
  Synchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

  Declaration

  OBJECTIVE-C

  - (id<MTLComputePipelineState>)newComputePipelineStateWithDescriptor:(MTLComputePipelineDescriptor *)descriptor
                                                             options:(MTLPipelineOption)options
                                                          reflection:(MTLAutoreleasedComputePipelineReflection *)reflection
                                                               error:(NSError * _Nullable *)error


  Parameters

  descriptor	A descriptor object that contains compute properties.
  options	The type of reflection information that should be returned.
  reflection	Reflection data about the compute function, including details about function arguments.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Return Value

  A new object with the compiled compute pipeline state.

  Discussion

  To use the compute pipeline state for a compute pass, call the setComputePipelineState: method of aMTLComputeCommandEncoder object with the MTLComputePipelineState object.

  HANDLING ERRORS IN SWIFT:

  In Swift, this method returns a nonoptional result and is marked with the throws keyword to indicate that it throws an error in cases of failure.

  You call this method in a try expression and handle any errors in the catch clauses of a do statement, as described in Error Handling in The Swift Programming Language (Swift 2.1) and Error Handling in Using Swift with Cocoa and Objective-C (Swift 2.1).

  Availability

  Available in iOS 9.0 and later.

Data Types

• MTLNewLibraryCompletionHandler
• MTLNewRenderPipelineStateCompletionHandler
  A block of code that is invoked when the logic to create a MTLRenderPipelineState object is completed.

  Declaration

  OBJECTIVE-C

  typedef void (^MTLNewRenderPipelineStateCompletionHandler)(id <MTLRenderPipelineState> __nullable renderPipelineState, NSError * __nullable error)

  Discussion

  The completion handler takes the following parameters:

  renderPipelineState	A new render pipeline state object that contains the compiled graphics rendering state, or nil if an error occurred.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Import Statement

  OBJECTIVE-C

  @import Metal;

  Availability

  Available in iOS 9.0 and later.

• MTLNewRenderPipelineStateWithReflectionCompletionHandler
• MTLNewComputePipelineStateCompletionHandler
  A block of code that is invoked when the logic to create a MTLComputePipelineState object is completed.

  Declaration

  OBJECTIVE-C

  typedef void (^MTLNewComputePipelineStateCompletionHandler)(id <MTLComputePipelineState> __nullable computePipelineState, NSError * __nullable error)

  Discussion

  The completion handler takes the following parameters:

  computePipelineState	A new compute pipeline state object that contains the compiled compute pipeline state, or nil if an error occurred.
  error	An error object that describes the problem, or nil if the operation succeeded.

  Import Statement

  OBJECTIVE-C

  @import Metal;

  Availability

  Available in iOS 9.0 and later.

• MTLNewComputePipelineStateWithReflectionCompletionHandler
• MTLAutoreleasedRenderPipelineReflection
• MTLAutoreleasedComputePipelineReflection

Constants

• MTLFeatureSet
• MTLPipelineOption
•