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 maxThreadgroupMemoryLength: Int

The maximum threadgroup memory available, in bytes.

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)

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

Required.

func supportsTextureSampleCount(Int)

Determines whether a device supports a given texture sample count.

Required.

var areRasterOrderGroupsSupported: Bool

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

Required.

var readWriteTextureSupport: MTLReadWriteTextureTier

The read-write texture support tier.

Required.

var registryID: UInt64

The registry ID value for the device.

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 makeDefaultLibrary(bundle: Bundle)

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

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.

func makeLibrary(URL: URL)

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

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.

Using Resources

var currentAllocatedSize: Int

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

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 makeRenderPipelineState(tileDescriptor: MTLTileRenderPipelineDescriptor, options: MTLPipelineOption, completionHandler: MTLNewRenderPipelineStateWithReflectionCompletionHandler)

Asynchronously creates and returns a tile shading pipeline state object and the associated 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.

enum MTLArgumentBuffersTier

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

func makeArgumentEncoder(arguments: [MTLArgumentDescriptor])

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

Required.

Using Linear Textures

func minimumLinearTextureAlignment(for: MTLPixelFormat)

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

Required.

Using Programmable Sample Positions

var areProgrammableSamplePositionsSupported: Bool

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

Required.

func getDefaultSamplePositions(sampleCount: Int)

Returns the default sample positions for a specific sample count.

Observing Device Notifications

var isRemovable: Bool

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

Required.

struct MTLDeviceNotificationName

The notifications posted when a GPU supported by Metal is added to or removed from the system.

typealias MTLDeviceNotificationHandler

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

func MTLRemoveDeviceObserver(NSObjectProtocol)

Removes a registered observer of device notifications.

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.

enum MTLReadWriteTextureTier

The support level for read-write texture formats.

struct MTLPipelineOption

The compilation options that determine which argument information is provided 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.

func MTLCopyAllDevicesWithObserver(handler: MTLDeviceNotificationHandler)

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

Relationships

Inherits From

See Also

GPU Devices

Devices and Commands

Demonstrates how to access and interact with the GPU.

enum MTLFeatureSet

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