Protocol

MTLDevice

A GPU that you use to draw graphics or do parallel computation.

Declaration

@protocol MTLDevice

Overview

The MTLDevice protocol defines the interface to a GPU. You can query a GPU device for the unique capabilities it offers your Metal app, and use the GPU device to issue all of your Metal commands. Don't implement this protocol yourself; instead, request a GPU from the system at runtime using MTLCreateSystemDefaultDevice on iOS or tvOS, and on macOS, get a list of available GPU devices using MTLCopyAllDevicesWithObserver(handler:). See Getting the Default GPU for a full discussion on choosing the right GPU(s).

GPU devices are your go-to object to do anything in Metal, so all of the Metal objects your app interacts with come from the MTLDevice instances you acquire at runtime. Device-created objects are expensive but persistent; many of them are designed to be initialized once and reused through the lifetime of your app. However, GPU device-created objects are specific to the GPU that issued them, so if you switch mid run to using different GPU(s), then you create a new suite of command objects from the new GPU device(s), too.

Topics

Acquiring Devices

iOS and tvOS Devices

Learn how to develop Metal apps for specific types of iOS and tvOS devices.

macOS Devices

Learn how to develop Metal apps for specific types of macOS devices.

MTLCreateSystemDefaultDevice

Returns a reference to the preferred system default Metal device.

MTLCopyAllDevices

Returns an array of references to all Metal devices in the system.

MTLCopyAllDevicesWithObserver

Returns an array of the available Metal devices and registers a notification observer for them.

MTLRemoveDeviceObserver

Removes a registered observer of device notifications.

CGDirectDisplayCopyCurrentMetalDevice

Returns a reference to the Metal device currently driving a given display.

Querying Properties

headless

A Boolean value that indicates whether a device is configured as headless.

Required.

lowPower

A Boolean value that indicates whether a device is low-power.

Required.

removable

A Boolean value that determines whether or not a GPU is removable.

Required.

registryID

The registry ID value for the device.

Required.

name

The name of the device.

Required.

Querying Features

MTLFeatureSet

The device feature sets that define specific platform, hardware, and software configurations.

supportsFeatureSet:

Returns a Boolean value that indicates whether a device supports a particular feature set.

Required.

Creating a Command Queue

newCommandQueue

Creates and return a command submission queue.

Required.

newCommandQueueWithMaxCommandBufferCount:

Creates and returns a command submission queue with a maximum number of uncompleted command buffers.

Required.

Synchronizing Commands

newEvent

Creates a new, nonshareable event for this specific device.

Required.

newSharedEvent

Creates a new, shareable event for multiple devices, processors, and processes.

Required.

newSharedEventWithHandle:

Creates a new, shareable event from a shareable event handle.

Required.

newFence

Creates a new fence.

Required.

Acquiring Shader Functions

newDefaultLibrary

Creates a new library that contains the functions stored in the app’s default Metal library.

Required.

newDefaultLibraryWithBundle:error:

Creates a new library that contains the functions stored in the specified bundle.

Required.

newLibraryWithFile:error:

Creates a new library that contains the functions stored in the specified Metal library.

Required.

newLibraryWithURL:error:

Creates a new library that contains the functions from a Metal library file at a specified URL.

Required.

newLibraryWithData:error:

Creates a new library that contains the functions stored in the specified binary data object.

Required.

newLibraryWithSource:options:completionHandler:

Asynchronously creates a new library by compiling the functions stored in the specified source string.

Required.

newLibraryWithSource:options:error:

Synchronously creates a new library that contains the functions stored in the specified source string.

Required.

Creating a Render Pipeline

newRenderPipelineStateWithDescriptor:completionHandler:

Asynchronously creates and returns a render pipeline state object.

Required.

newRenderPipelineStateWithDescriptor:options:completionHandler:

Asynchronously creates and returns a render pipeline state object and the associated reflection information.

Required.

newRenderPipelineStateWithDescriptor:error:

Synchronously creates and returns a render pipeline state object.

Required.

newRenderPipelineStateWithDescriptor:options:reflection:error:

Synchronously creates a render pipeline state object that contains compiled graphics rendering pipeline state and returns additional reflection information.

Required.

newRenderPipelineStateWithTileDescriptor:options:completionHandler:

Asynchronously creates and returns a tile shading pipeline state object and the associated reflection information.

Required.

newRenderPipelineStateWithTileDescriptor:options:reflection:error:

Asynchronously creates and returns a tile shading pipeline state object.

Required.

Creating a Compute Pipeline

newComputePipelineStateWithDescriptor:options:completionHandler:

Asynchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

Required.

newComputePipelineStateWithFunction:completionHandler:

Asynchronously creates a new compute pipeline state object that represents a compiled compute function.

Required.

newComputePipelineStateWithFunction:options:completionHandler:

Asynchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

Required.

newComputePipelineStateWithDescriptor:options:reflection:error:

Synchronously creates a new compute pipeline state object, from a compute pipeline descriptor, that represents a compiled compute function and returns additional reflection information.

Required.

newComputePipelineStateWithFunction:error:

Synchronously creates a new compute pipeline state object that represents a compiled compute function.

Required.

newComputePipelineStateWithFunction:options:reflection:error:

Synchronously creates a new compute pipeline state object that represents a compiled compute function and returns additional reflection information.

Required.

Querying Memory Availability

recommendedMaxWorkingSetSize

Returns an approximation of how much memory, in bytes, this device can use with good performance.

Required.

currentAllocatedSize

The current size, in bytes, of all resources allocated on this device for this process.

Required.

maxThreadgroupMemoryLength

The maximum threadgroup memory available, in bytes.

Required.

maxThreadsPerThreadgroup

The maximum number of threads along each dimension of a threadgroup.

Required.

maxBufferLength

The maximum size of a buffer, in bytes.

Required.

Creating Buffers

Fill buffers with arbitrary data structures that you design and send as arguments to your shader functions on the GPU.

newBufferWithLength:options:

Allocates a new zero-filled buffer of a given length.

Required.

newBufferWithBytes:length:options:

Allocates a new buffer of a given length and initializes its contents by copying existing data into it.

Required.

newBufferWithBytesNoCopy:length:options:deallocator:

Creates a buffer by wrapping an existing contiguous memory allocation.

Required.

Creating Textures and Samplers

newTextureWithDescriptor:

Creates a texture object with privately owned storage that contains texture state.

Required.

newTextureWithDescriptor:iosurface:plane:

Creates a texture object, from an IOSurface, with privately owned storage that contains texture state.

Required.

newSharedTextureWithDescriptor:

Create a new texture that can be shared across process boundaries.

Required.

newSharedTextureWithHandle:

Creates a texture object referencing an existing shared texture.

Required.

newSamplerStateWithDescriptor:

Creates a sampler state object that contains the sampler state.

Required.

supportsTextureSampleCount:

Determines whether a device supports a given texture sample count.

Required.

minimumLinearTextureAlignmentForPixelFormat:

Returns the minimum alignment required for creating a linear texture with a given pixel format.

Required.

minimumTextureBufferAlignmentForPixelFormat:

Returns the minimum alignment required when creating a texture buffer from a buffer.

Required.

readWriteTextureSupport

The device's read-write texture support tier.

Required.

Creating Argument Buffers

newArgumentEncoderWithArguments:

Creates a new argument encoder for a specific array of arguments.

Required.

argumentBuffersSupport

Determines the argument buffers tier supported by the device.

Required.

maxArgumentBufferSamplerCount

The maximum number of unique argument buffer samplers per app.

Required.

Creating Indirect Command Buffers

newIndirectCommandBufferWithDescriptor:maxCommandCount:options:

Creates a new indirect command buffer.

Required.

Creating Resource Heaps and Fences

newHeapWithDescriptor:

Creates a new heap.

Required.

heapBufferSizeAndAlignWithLength:options:

Returns the size and alignment, in bytes, of a buffer that will be sub-allocated from a heap.

Required.

heapTextureSizeAndAlignWithDescriptor:

Returns the size and alignment, in bytes, of a texture that will be sub-allocated from a heap.

Required.

Creating Depth and Stencil State

newDepthStencilStateWithDescriptor:

Creates a new object that contains the depth and stencil test state.

Required.

depth24Stencil8PixelFormatSupported

A Boolean value that indicates whether a device supports a packed depth/stencil buffer.

Required.

Querying Programmable Sample Positions

programmableSamplePositionsSupported

A Boolean that indicates whether a device supports programmable sample positions.

Required.

getDefaultSamplePositions:count:

Retrieves the default sample positions for a specific sample count.

Required.

Querying Raster Order Groups Support

rasterOrderGroupsSupported

A Boolean value that indicates whether a device supports raster order groups.

Required.

Relationships

Inherits From

See Also

GPU Devices

Getting the Default GPU

Select the system's default GPU device on which to run your Metal code.

Choosing GPUs on Mac

Select one or more GPUs on which to run your Metal code by considering GPU capabilities, power, or performance characteristics.