Protocol

MTLDevice

An abstract representation of the GPU that serves as the primary interface for a Metal app.

Overview

The MTLDevice protocol defines the interface to a GPU. You use a specific device to query the features of the GPU and allocate Metal objects for your app.

You create many Metal objects, such as command queues, libraries, pipelines, and resources, from your device. Device-created objects are expensive but persistent; you can initialize them once and reuse them often, instead of creating new objects at the beginning of every render or compute loop (or any other performance-sensitive code). After you create an object from your device, that object can be used only with that device.

Topics

Device Functions

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.

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

Feature Sets

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.

Command Queues

func makeCommandQueue() -> MTLCommandQueue?

Creates and return a serial command submission queue.

Required.

func makeCommandQueue(maxCommandBufferCount: Int) -> MTLCommandQueue?

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

Required.

Synchronization Events

func makeEvent() -> MTLEvent?

Creates a new, nonshareable event for this specific device.

Required.

Beta
func makeSharedEvent() -> MTLSharedEvent?

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

Required.

Beta
func makeSharedEvent(handle: MTLSharedEventHandle) -> MTLSharedEvent?

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

Required.

Beta

Libraries

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.

Render Pipelines

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.

Compute Pipelines

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.

Resource and Threadgroup Memory

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.

Standard Buffers

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.

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

Linear Textures

func minimumLinearTextureAlignment(for: MTLPixelFormat) -> Int

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

Required.

Read-Write Textures

var readWriteTextureSupport: MTLReadWriteTextureTier

The read-write texture support tier.

Required.

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.

Resource Heaps and Fences

func makeHeap(descriptor: MTLHeapDescriptor) -> MTLHeap?

Creates a new heap with the given descriptor.

Required.

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

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

Required.

func heapTextureSizeAndAlign(descriptor: MTLTextureDescriptor) -> MTLSizeAndAlign

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

Required.

func makeFence() -> MTLFence?

Creates a new fence.

Required.

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.

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.

Raster Order Groups

var areRasterOrderGroupsSupported: Bool

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

Required.

Instance Properties

Relationships

Inherits From

See Also

GPU Devices

Devices and Commands

Demonstrates how to access and interact with the GPU.

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.

enum MTLFeatureSet

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

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