Protocol

MTLDevice

The MTLDevice protocol defines the interface to a single graphics processor (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.

Overview

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.

Symbols

Identifying Properties

var isDepth24Stencil8PixelFormatSupported: Bool

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

var isHeadless: Bool

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

var isLowPower: Bool

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

var maxThreadsPerThreadgroup: MTLSize

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

var recommendedMaxWorkingSetSize: UInt64

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

var name: String?

A string that identifies the device.

func supportsFeatureSet(MTLFeatureSet)

Determines whether a device implements a particular feature set.

func supportsTextureSampleCount(Int)

Determines whether a device supports a given texture sample count.

Creating Metal Shader Libraries

func newDefaultLibrary()

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

func makeLibrary(filepath: String)

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

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

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

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

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

func makeLibrary(data: __DispatchData)

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

Creating Command Queues

func makeCommandQueue()

Creates and return a serial command submission queue.

func makeCommandQueue(maxCommandBufferCount: Int)

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

Creating Resources

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

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

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.

func makeTexture(descriptor: MTLTextureDescriptor)

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

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

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

func makeHeap(descriptor: MTLHeapDescriptor)

Creates a new heap with the given descriptor.

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

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

func heapTextureSizeAndAlign(descriptor: MTLTextureDescriptor)

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

func makeFence()

Creates a new fence.

func makeSamplerState(descriptor: MTLSamplerDescriptor)

Creates a sampler state object that contains the sampler state.

Creating Command Objects Needed to Render Graphics

func makeRenderPipelineState(descriptor: MTLRenderPipelineDescriptor)

Synchronously creates and returns a render pipeline state object.

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.

func makeDepthStencilState(descriptor: MTLDepthStencilDescriptor)

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

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.

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.

func makeComputePipelineState(function: MTLFunction)

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

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.

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.

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.

Constants

MTLNewLibraryCompletionHandler

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

MTLNewRenderPipelineStateCompletionHandler

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

MTLNewRenderPipelineStateWithReflectionCompletionHandler

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

MTLNewComputePipelineStateCompletionHandler

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

MTLNewComputePipelineStateWithReflectionCompletionHandler

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

MTLAutoreleasedRenderPipelineReflection

A convenience type alias for an autoreleased MTLRenderPipelineReflection object.

MTLAutoreleasedComputePipelineReflection

A convenience type alias for an autoreleased MTLComputePipelineReflection object.

MTLFeatureSet

Values that indicate specific Metal feature sets. Each feature set provides a different set of features, limits, and capabilities.

MTLPipelineOption

Controls which argument information is made available for reflection by the creation of the pipeline.

Relationships

Inherits From