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 single graphics processor unit (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.

Topics

Identifying Properties

var isDepth24Stencil8PixelFormatSupported: Bool

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

Required.

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 maxThreadsPerThreadgroup: MTLSize

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

Required.

var recommendedMaxWorkingSetSize: UInt64

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

Required.

var name: String

A string that identifies the device.

Required.

func supportsFeatureSet(MTLFeatureSet)

Determines whether a device supports a particular feature set.

Required.

func supportsTextureSampleCount(Int)

Determines whether a device supports a given texture sample count.

Required.

Creating Metal Shader Libraries

func makeDefaultLibrary()

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

Required.

func makeLibrary(filepath: String)

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

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?)

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

Required.

func makeLibrary(data: __DispatchData)

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

Required.

Creating Command Queues

func makeCommandQueue()

Creates and return a serial command submission queue.

Required.

func makeCommandQueue(maxCommandBufferCount: Int)

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

Required.

Creating Resources

func makeBuffer(length: Int, options: MTLResourceOptions = [])

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

Required.

func makeBuffer(bytes: UnsafeRawPointer, length: Int, options: MTLResourceOptions = [])

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

Required.

func makeTexture(descriptor: MTLTextureDescriptor)

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

Required.

func makeTexture(descriptor: MTLTextureDescriptor, iosurface: IOSurfaceRef, plane: Int)

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

Required.

func makeHeap(descriptor: MTLHeapDescriptor)

Creates a new heap with the given descriptor.

Required.

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

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

Required.

func heapTextureSizeAndAlign(descriptor: MTLTextureDescriptor)

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

Required.

func makeFence()

Creates a new fence.

Required.

func makeSamplerState(descriptor: MTLSamplerDescriptor)

Creates a sampler state object that contains the sampler state.

Required.

Creating Command Objects Needed to Render Graphics

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)

Synchronously creates and returns a render pipeline state object.

Required.

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

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

Required.

func makeDepthStencilState(descriptor: MTLDepthStencilDescriptor)

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

Required.

Creating Command Objects Needed to Perform Computational Tasks

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(function: MTLFunction)

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

Required.

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

Synchronously 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, 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(descriptor: MTLComputePipelineDescriptor, options: MTLPipelineOption, reflection: AutoreleasingUnsafeMutablePointer<MTLAutoreleasedComputePipelineReflection?>?)

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.

Using Argument Buffers

var argumentBuffersSupport: MTLArgumentBuffersTier

Determines the argument buffers tier supported by the device.

Required.

Beta
enum MTLArgumentBuffersTier

The values that determine the limits and capabilities of argument buffers.

Beta
func newArgumentEncoder(withArguments: [MTLArgumentDescriptor])

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

Required.

Beta

Using Programmable Sample Positions

var areProgrammableSamplePositionsSupported: Bool

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

Required.

Beta
func getDefaultSamplePositions(UnsafeMutablePointer<MTLSamplePosition>, count: Int)

Retrieves the default sample positions for a specific sample count.

Required.

Beta

Observing Device Notifications

var isRemovable: Bool

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

Required.

Beta
func MTLCopyAllDevicesWithObserver(AutoreleasingUnsafeMutablePointer<NSObjectProtocol?>, MTLDeviceNotificationHandler)

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

Beta
typealias MTLDeviceNotificationHandler

A block of code invoked when a device observer receives a notification.

Beta
func MTLRemoveDeviceObserver(NSObjectProtocol)

Removes a registered observer of device notifications.

Beta

Constants

typealias MTLNewLibraryCompletionHandler

A block of code that is invoked when a MTLLibrary object has completed loading.

typealias MTLNewComputePipelineStateCompletionHandler

A block of code that is invoked when the logic to create a MTLComputePipelineState object is completed.

typealias MTLNewComputePipelineStateWithReflectionCompletionHandler

A block of code that is invoked when the logic to create a MTLComputePipelineState object is completed.

typealias MTLNewRenderPipelineStateCompletionHandler

A block of code that is invoked when the logic to create a MTLRenderPipelineState object is completed.

typealias MTLNewRenderPipelineStateWithReflectionCompletionHandler

A block of code that is invoked when the logic to create a MTLRenderPipelineState object is completed.

typealias MTLAutoreleasedRenderPipelineReflection

A convenience type alias for an autoreleased MTLRenderPipelineReflection object.

typealias MTLAutoreleasedComputePipelineReflection

A convenience type alias for an autoreleased MTLComputePipelineReflection object.

enum MTLFeatureSet

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

struct MTLPipelineOption

Compilation options that determine what pipeline information is made available for reflection.

struct MTLSizeAndAlign

The size and alignment of a resource, in bytes, typically used when creating a heap.

Functions

func MTLCreateSystemDefaultDevice()

Returns a reference to the preferred system default Metal device.

func MTLCopyAllDevices()

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

Relationships

Inherits From

See Also

GPU 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