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.

func MTLCreateSystemDefaultDevice() -> MTLDevice?

Returns a reference to the preferred system default Metal device.

func MTLCopyAllDevices() -> [MTLDevice]

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

func MTLCopyAllDevicesWithObserver(handler: MTLDeviceNotificationHandler) -> (devices: [MTLDevice], observer: NSObject)

Returns an array of references to all Metal devices in the system, with an observer to receive device notifications.

func MTLRemoveDeviceObserver(NSObjectProtocol)

Removes a registered observer of device notifications.

Querying Properties

var isHeadless: Bool

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

Required.

var isLowPower: Bool

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

Required.

var isRemovable: Bool

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

Required.

var registryID: UInt64

The registry ID value for the device.

Required.

var name: String

The name of the device.

Required.

Querying Features

enum MTLFeatureSet

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

func supportsFeatureSet(MTLFeatureSet) -> Bool

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

Required.

Creating a Command Queue

func makeCommandQueue() -> MTLCommandQueue?

Creates and return a command submission queue.

Required.

func makeCommandQueue(maxCommandBufferCount: Int) -> MTLCommandQueue?

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

Required.

Synchronizing Commands

func makeEvent() -> MTLEvent?

Creates a new, nonshareable event for this specific device.

Required.

func makeSharedEvent() -> MTLSharedEvent?

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

Required.

func makeSharedEvent(handle: MTLSharedEventHandle) -> MTLSharedEvent?

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

Required.

func makeFence() -> MTLFence?

Creates a new fence.

Required.

Acquiring Shader Functions

func makeDefaultLibrary() -> MTLLibrary?

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

Required.

func makeDefaultLibrary(bundle: Bundle) -> MTLLibrary

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

Required.

func makeLibrary(filepath: String) -> MTLLibrary

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

Required.

func makeLibrary(URL: URL) -> MTLLibrary

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

Required.

func makeLibrary(data: __DispatchData) -> MTLLibrary

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

Required.

func makeLibrary(source: String, options: MTLCompileOptions?, completionHandler: MTLNewLibraryCompletionHandler)

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

Required.

func makeLibrary(source: String, options: MTLCompileOptions?) -> MTLLibrary

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

Required.

Creating a Render Pipeline

func makeRenderPipelineState(descriptor: MTLRenderPipelineDescriptor, options: MTLPipelineOption, completionHandler: MTLNewRenderPipelineStateWithReflectionCompletionHandler)

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

Required.

func makeRenderPipelineState(descriptor: MTLRenderPipelineDescriptor) -> MTLRenderPipelineState

Synchronously creates and returns a render pipeline state object.

Required.

func makeRenderPipelineState(descriptor: MTLRenderPipelineDescriptor, options: MTLPipelineOption, reflection: AutoreleasingUnsafeMutablePointer<MTLAutoreleasedRenderPipelineReflection?>?) -> MTLRenderPipelineState

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

Required.

func makeRenderPipelineState(tileDescriptor: MTLTileRenderPipelineDescriptor, options: MTLPipelineOption, completionHandler: MTLNewRenderPipelineStateWithReflectionCompletionHandler)

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

Required.

Creating a Compute Pipeline

func makeComputePipelineState(descriptor: MTLComputePipelineDescriptor, options: MTLPipelineOption, completionHandler: MTLNewComputePipelineStateWithReflectionCompletionHandler)

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.

func makeComputePipelineState(function: MTLFunction, completionHandler: MTLNewComputePipelineStateCompletionHandler)

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

Required.

func makeComputePipelineState(function: MTLFunction, options: MTLPipelineOption, completionHandler: MTLNewComputePipelineStateWithReflectionCompletionHandler)

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

Required.

func makeComputePipelineState(descriptor: MTLComputePipelineDescriptor, options: MTLPipelineOption, reflection: AutoreleasingUnsafeMutablePointer<MTLAutoreleasedComputePipelineReflection?>?) -> MTLComputePipelineState

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.

func makeComputePipelineState(function: MTLFunction) -> MTLComputePipelineState

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

Required.

func makeComputePipelineState(function: MTLFunction, options: MTLPipelineOption, reflection: AutoreleasingUnsafeMutablePointer<MTLAutoreleasedComputePipelineReflection?>?) -> MTLComputePipelineState

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

Required.

Querying Memory Availability

var recommendedMaxWorkingSetSize: UInt64

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

Required.

var currentAllocatedSize: Int

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

Required.

var maxThreadgroupMemoryLength: Int

The maximum threadgroup memory available, in bytes.

Required.

var maxThreadsPerThreadgroup: MTLSize

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

Required.

var maxBufferLength: Int

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.

func makeBuffer(length: Int, options: MTLResourceOptions = []) -> MTLBuffer?

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

Required.

func makeBuffer(bytes: UnsafeRawPointer, length: Int, options: MTLResourceOptions = []) -> MTLBuffer?

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

Required.

Creating Textures and Samplers

func makeTexture(descriptor: MTLTextureDescriptor) -> MTLTexture?

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

Required.

func makeTexture(descriptor: MTLTextureDescriptor, iosurface: IOSurfaceRef, plane: Int) -> MTLTexture?

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

Required.

func makeSharedTexture(descriptor: MTLTextureDescriptor) -> MTLTexture?

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

Required.

func makeSharedTexture(handle: MTLSharedTextureHandle) -> MTLTexture?

Creates a texture object referencing an existing shared texture.

Required.

func makeSamplerState(descriptor: MTLSamplerDescriptor) -> MTLSamplerState?

Creates a sampler state object that contains the sampler state.

Required.

func supportsTextureSampleCount(Int) -> Bool

Determines whether a device supports a given texture sample count.

Required.

func minimumLinearTextureAlignment(for: MTLPixelFormat) -> Int

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

Required.

func minimumTextureBufferAlignment(for: MTLPixelFormat) -> Int

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

Required.

var readWriteTextureSupport: MTLReadWriteTextureTier

The device's read-write texture support tier.

Required.

Creating Argument Buffers

func makeArgumentEncoder(arguments: [MTLArgumentDescriptor]) -> MTLArgumentEncoder?

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

Required.

var argumentBuffersSupport: MTLArgumentBuffersTier

Determines the argument buffers tier supported by the device.

Required.

var maxArgumentBufferSamplerCount: Int

The maximum number of unique argument buffer samplers per app.

Required.

Creating Resource Heaps and Fences

func heapBufferSizeAndAlign(length: Int, options: MTLResourceOptions = []) -> MTLSizeAndAlign

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

Required.

func heapTextureSizeAndAlign(descriptor: MTLTextureDescriptor) -> MTLSizeAndAlign

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

Required.

Creating Depth and Stencil State

func makeDepthStencilState(descriptor: MTLDepthStencilDescriptor) -> MTLDepthStencilState?

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

Required.

var isDepth24Stencil8PixelFormatSupported: Bool

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

Required.

Querying Programmable Sample Positions

var areProgrammableSamplePositionsSupported: Bool

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

Required.

func getDefaultSamplePositions(sampleCount: Int) -> [MTLSamplePosition]

Returns the default sample positions for a specific sample count.

Querying Raster Order Groups Support

var areRasterOrderGroupsSupported: Bool

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.