Protocol

MTLDevice

The Metal interface to 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 MTLDevice for the unique capabilities it offers your Metal app, and use the MTLDevice to issue all of your Metal commands. Don't implement this protocol yourself; instead, request a GPU from the system at runtime using MTLCreateSystemDefaultDevice in iOS or tvOS, and in macOS, get a list of available MTLDevice objects using MTLCopyAllDevicesWithObserver(handler:). See Getting the Default GPU for a full discussion on choosing the right GPU(s).

MTLDevice objects 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. MTLDevice-created objects are expensive but persistent; many of them are designed to be initialized once and reused through the lifetime of your app. However, these objects are specific to the MTLDevice that issued them. If you use multiple MTLDevice instances or want to switch from one MTLDevice to another, you need to create a separate set of objects for each MTLDevice.

Topics

Acquiring Device Objects

MTLCreateSystemDefaultDevice

Returns a reference to the preferred default Metal device object.

MTLCopyAllDevices

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

MTLCopyAllDevicesWithObserver

Fetches the available Metal devices and registers a notification observer for changes to the list.

MTLRemoveDeviceObserver

Removes a registered observer of device notifications.

CGDirectDisplayCopyCurrentMetalDevice

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

Querying GPU Properties

name

The name of the device.

Required.

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.

location

The physical location of the GPU relative to the host computer.

Required.

locationNumber

A more detailed specifier for the GPU's location.

Required.

maxTransferRate

The highest theoretical rate of transfer between system RAM and dedicated GPU memory (VRAM), measured in bytes per second.

Required.

hasUnifiedMemory

A Boolean that indicates whether the GPU shares all of its memory with the CPU.

Required.

Beta
MTLDeviceLocation

Options describing possible locations for the GPU.

Finding Groups of Connected GPUs

Transferring Data Between Connected GPUs

Use high-speed connections between GPUs to transfer data quickly.

peerGroupID

The peer group, if any, that the GPU belongs to.

Required.

peerCount

The number of GPUs in the peer group.

Required.

peerIndex

The unique identifier for a GPU in a peer group.

Required.

Querying Features

Detecting GPU Features and Metal Software Versions

Use the device object’s properties to determine how you perform tasks in Metal.

- supportsVersion:

Determines whether the device object supports a particular Metal version.

Required.

Beta
- supportsFamily:

Determines whether the device object supports the feature set of a particular GPU family.

Required.

Beta
- supportsFeatureSet:

Determines whether a device supports a particular feature set.

Required.

MTLSoftwareVersion

Options for different versions of the Metal software.

Beta
MTLGPUFamily

Options for families of GPUs.

Beta
MTLFeatureSet

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

Querying Memory Availability and Limits

recommendedMaxWorkingSetSize

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 to a compute kernel, in bytes.

Required.

Querying Threadgroup Limits

maxThreadsPerThreadgroup

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

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.

Querying Depth and Stencil Support

depth24Stencil8PixelFormatSupported

A Boolean value that indicates whether a device supports a packed depth-and-stencil pixel format.

Required.

Querying Barycentric Coordinate Support

barycentricCoordsSupported

A Boolean value indicating whether the GPU supports barycentric coordinates.

Required.

Beta

Creating a Command Queue

- newCommandQueue

Creates a command submission queue.

Required.

- newCommandQueueWithMaxCommandBufferCount:

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

Required.

Creating Events and Fences

- newEvent

Creates a new event whose use is limited to the device object.

Required.

- newSharedEvent

Creates a shareable event.

Required.

- newSharedEventWithHandle:

Re-creates a shareable event from a shareable event handle.

Required.

- newFence

Creates a new fence.

Required.

Creating Shader Libraries

- newDefaultLibrary

Creates a library object containing the functions in the app’s default Metal library.

Required.

- newDefaultLibraryWithBundle:error:

Creates a library object containing the functions stored in the default Metal library in the specified bundle.

Required.

- newLibraryWithFile:error:

Creates a library object containing the functions in a Metal library file at a specified path.

Required.

- newLibraryWithURL:error:

Creates a library object containing the functions in a Metal library file at a specified URL.

Required.

- newLibraryWithData:error:

Creates a library object containing the functions stored in a binary data object created from a precompiled Metal library.

Required.

- newLibraryWithSource:options:completionHandler:

Creates a library object asynchronously by compiling the functions stored in the specified source string.

Required.

- newLibraryWithSource:options:error:

Creates a library object synchronously by compiling the functions stored in the specified source string.

Required.

Creating a Render Pipeline

- newRenderPipelineStateWithDescriptor:completionHandler:

Asynchronously creates a render pipeline state object.

Required.

- newRenderPipelineStateWithDescriptor:options:completionHandler:

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

Required.

- newRenderPipelineStateWithDescriptor:error:

Synchronously creates a render pipeline state object.

Required.

- newRenderPipelineStateWithDescriptor:options:reflection:error:

Synchronously creates a render pipeline state object and associated reflection information.

Required.

- newRenderPipelineStateWithTileDescriptor:options:completionHandler:

Asynchronously creates a render pipeline state object, and associated reflection information, for a tile shader.

Required.

- newRenderPipelineStateWithTileDescriptor:options:reflection:error:

Synchronously creates a render pipeline state object, and associated reflection information, for a tile shader.

Required.

Creating a Compute Pipeline

- newComputePipelineStateWithDescriptor:options:completionHandler:

Asynchronously creates a compute pipeline state object, and associated reflection information, using a compute pipeline descriptor.

Required.

- newComputePipelineStateWithFunction:completionHandler:

Asynchronously creates a new compute pipeline state object using a function object.

Required.

- newComputePipelineStateWithFunction:options:completionHandler:

Asynchronously creates a new compute pipeline state object, and associated reflection information, using a function object.

Required.

- newComputePipelineStateWithDescriptor:options:reflection:error:

Synchronously creates a compute pipeline state object, and associated reflection information, using a compute pipeline descriptor.

Required.

- newComputePipelineStateWithFunction:error:

Synchronously creates a new compute pipeline state object using a function object.

Required.

- newComputePipelineStateWithFunction:options:reflection:error:

Synchronously creates a new compute pipeline state object, and associated reflection information, using a function object.

Required.

Creating Buffers

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

maxBufferLength

The maximum size of a buffer, in bytes.

Required.

- 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.

Querying Texture Support

- supportsTextureSampleCount:

Determines whether a device supports a given texture sample count.

Required.

- minimumLinearTextureAlignmentForPixelFormat:

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

Required.

- minimumTextureBufferAlignmentForPixelFormat:

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

Required.

readWriteTextureSupport

The device objects's read-write texture support tier.

Required.

Creating Textures and Samplers

- newTextureWithDescriptor:

Creates a texture.

Required.

- newTextureWithDescriptor:iosurface:plane:

Creates a texture using an IOSurface to store the texture data.

Required.

- newSharedTextureWithDescriptor:

Create a texture that can be shared across process boundaries.

Required.

- newSharedTextureWithHandle:

Creates a texture referencing an existing shared texture.

Required.

- newSamplerStateWithDescriptor:

Creates a sampler state object.

Required.

Querying Argument Buffer Support

argumentBuffersSupport

Determines the argument buffers tier supported by the device.

Required.

maxArgumentBufferSamplerCount

The maximum number of unique argument buffer samplers per app.

Required.

Creating Argument Buffer Encoders

- newArgumentEncoderWithArguments:

Creates an argument encoder for a specific array of arguments.

Required.

Creating Indirect Command Buffers

- newIndirectCommandBufferWithDescriptor:maxCommandCount:options:

Creates an indirect command buffer.

Required.

Creating Resource Heaps

- newHeapWithDescriptor:

Creates a heap.

Required.

- heapBufferSizeAndAlignWithLength:options:

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

Required.

- heapTextureSizeAndAlignWithDescriptor:

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

Required.

Creating Depth and Stencil State

- newDepthStencilStateWithDescriptor:

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

Required.

Creating Counter Sample Buffers

counterSets

The counter sets supported by the device object.

Required.

Beta
- newCounterSampleBufferWithDescriptor:error:

Creates a counter sample buffer.

Required.

Beta

Reading Sample Timestamps

- sampleTimestamps:gpuTimestamp:

Samples the CPU and GPU timestamps.

Required.

Beta

Relationships

Inherits From

See Also

GPUs

Getting the Default GPU

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

GPU Selection in macOS

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

GPU Features

Find feature information for specific GPU families.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software