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)[code]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 *)[code]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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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 *)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 *)[code]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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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 *)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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)[code]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 a

MTLComputeCommandEncoder

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