What's new in Metal — iOS & macOS 27 SDK

New

var

`auxiliaryPlanes`

NewiOSmacOStvOS

open var auxiliaryPlanes: [MTLTensorAuxiliaryPlaneType] { get }

The auxiliary planes that this tensor reference requires.

Returns an array of MTLTensorAuxiliaryPlaneType objects describing each auxiliary plane the shader expects. Empty if the tensor has no auxiliary planes.

var

`auxiliaryPlanes`

NewiOSmacOStvOS

open var auxiliaryPlanes: MTLTensorAuxiliaryPlaneDescriptorMap?

The auxiliary plane configurations for this tensor.

Set this property with a populated MTLTensorAuxiliaryPlaneDescriptorMap to create a multi-plane tensor. When nil, the tensor has only a data plane.

Multi-plane tensors do not support MTLTensorUsageMachineLearning. Use MTLTensorUsageCompute or MTLTensorUsageRender.

Multi-plane tensors do not support data types larger than one byte as the data plane type

The default value is nil.

protocol

`MTLTensorAuxiliaryPlane`

NewiOSmacOStvOS

public protocol MTLTensorAuxiliaryPlane : NSObjectProtocol

A type that represents the configuration and storage of an auxiliary plane in a multi-plane tensor.

Declaration

public protocol MTLTensorAuxiliaryPlane : NSObjectProtocol {

    /// The data format of all elements in the plane.
    var dataType: MTLTensorDataType { get }

    /// Describes how many data plane elements correspond to one element in this plane.
    var blockFactors: MTLTensorExtents { get }

    /// The buffer that provides the underlying storage for this plane, or `nil` if no buffer was provided at initialization.
    var buffer: (any MTLBuffer)? { get }

    /// Byte offset into `buffer` where this plane's data begins, or 0 if no buffer was provided at initialization.
    var bufferOffset: Int { get }

    /// The type of information this plane stores.
    var planeType: MTLTensorPlaneType { get }
}

enum

`MTLTensorPlaneType`

NewiOSmacOStvOS

public enum MTLTensorPlaneType : Int, @unchecked Sendable

The possible tensor plane types.

Declaration

public enum MTLTensorPlaneType : Int, @unchecked Sendable {

    /// The data plane. This is the main plane of a tensor. Tensors always have a data plane.
    case data = 0

    /// The scale auxiliary plane. Contains scale factors for elements in the data plane.
    case scales = 1
}

func

`MTL4ComputeCommandEncoder.copy`

NewiOSmacOStvOS

func copy(sourceTensor: any MTLTensor, sourceOrigin: MTLTensorExtents, sourceDimensions: MTLTensorExtents, sourcePlane: MTLTensorPlaneType, destinationTensor: any MTLTensor, destinationOrigin: MTLTensorExtents, destinationDimensions: MTLTensorExtents, destinationPlane: MTLTensorPlaneType)

Encodes a command to copy data from a slice of a plane of a tensor into a slice of a plane of another tensor.

If sourceTensor and destinationTensor are not aliasable, this command applies a reshape operation. For auxiliary planes, specify origin and dimensions in plane coordinates by applying the corresponding auxiliary plane's block factors.

Ensure the first dimension of sourceOrigin, sourceDimensions, destinationOrigin, and destinationDimensions is byte aligned.

Parameters

sourceTensor: A tensor instance the method copies data from.
sourceOrigin: An array of per-dimension offsets that together locate the first element to copy in sourceTensor. Each element in this array corresponds to the dimension at the same index in sourceDimensions. Each offset value represents the number of elements from the start of that dimension.
sourceDimensions: An array of per-dimension sizes that together define the extent of the slice to copy from sourceTensor. Each element in this array corresponds to the dimension at the same index in sourceOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in sourceOrigin.
sourcePlane: The plane the method copies data from.
destinationTensor: A tensor instance the method copies data to.
destinationOrigin: An array of per-dimension offsets that together locate the first element to write in destinationTensor. Each element in this array corresponds to the dimension at the same index in destinationDimensions. Each offset value represents the number of elements from the start of that dimension.
destinationDimensions: An array of per-dimension sizes that together define the extent of the slice to write in destinationTensor. Each element in this array corresponds to the dimension at the same index in destinationOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in destinationOrigin.
destinationPlane: The plane the method copies data to.

func

`MTLBlitCommandEncoder.copy`

NewiOSmacOStvOS

func copy(from sourceTensor: any MTLTensor, sourceOrigin: MTLTensorExtents, sourceDimensions: MTLTensorExtents, sourcePlane: MTLTensorPlaneType, to destinationTensor: any MTLTensor, destinationOrigin: MTLTensorExtents, destinationDimensions: MTLTensorExtents, destinationPlane: MTLTensorPlaneType)

Encodes a command to copy data from a slice of a plane of a tensor into a slice of a plane of another tensor.

Ensure the first dimension of sourceOrigin, sourceDimensions, destinationOrigin, and destinationDimensions is byte aligned.

Parameters

sourceTensor: A tensor instance the method copies data from.
sourceOrigin: An array of per-dimension offsets that together locate the first element to copy in sourceTensor. Each element in this array corresponds to the dimension at the same index in sourceDimensions. Each offset value represents the number of elements from the start of that dimension.
sourceDimensions: An array of per-dimension sizes that together define the extent of the slice to copy from sourceTensor. Each element in this array corresponds to the dimension at the same index in sourceOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in sourceOrigin.
sourcePlane: The plane the method copies data from.
destinationTensor: A tensor instance the method copies data to.
destinationOrigin: An array of per-dimension offsets that together locate the first element to write in destinationTensor. Each element in this array corresponds to the dimension at the same index in destinationDimensions. Each offset value represents the number of elements from the start of that dimension.
destinationDimensions: An array of per-dimension sizes that together define the extent of the slice to write in destinationTensor. Each element in this array corresponds to the dimension at the same index in destinationOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in destinationOrigin.
destinationPlane: The plane the method copies data to.

func

`MTLDevice.makeTensor`

NewiOSmacOStvOS

func makeTensor(descriptor: MTLTensorDescriptor, attachments: MTLTensorBufferAttachments) throws -> any MTLTensor

Creates a tensor with the specified descriptor and per-plane buffer backing storage.

This method validates the constraints documented on MTLTensorDescriptor and MTLTensorBufferAttachments, and additionally requires that every plane configured in descriptor (data plane and all auxiliary planes) has a corresponding entry in attachments.

Parameters

descriptor: The tensor descriptor configuring the data plane and auxiliary planes.
attachments: The per-plane buffer backing storage. Must not be nil.
error: On failure, an NSError instance that describes the validation failure.

ReturnsA tensor, or nil if validation fails.

case

`MTLLanguageVersion.version4_1`

NewiOSmacOStvOS

case version4_1 = 262145

var

`MTLTensor.auxiliaryPlanes`

NewiOSmacOStvOS

var auxiliaryPlanes: [any MTLTensorAuxiliaryPlane] { get }

The auxiliary planes of this tensor.

Returns an array of MTLTensorAuxiliaryPlane objects describing each auxiliary plane configured on this tensor. For single-plane tensors, this array is empty.

func

`MTLTensor.getBytes`

NewiOSmacOStvOS

func getBytes(_ bytes: UnsafeMutableRawPointer, strides: MTLTensorExtents, sliceOrigin: MTLTensorExtents, sliceDimensions: MTLTensorExtents, plane: MTLTensorPlaneType)

Copies data from a slice of a plane of this tensor into a pointer you provide.

When reading from auxiliary planes, specify sliceOrigin and sliceDimensions in plane coordinates by applying the auxiliary plane's block factors.

Create the tensor with MTLResourceStorageModeShared for CPU access via this method. Strides must be monotonically non-decreasing: for any i > 0, strides[i] >= strides[i-1] * dimensions[i-1].

The first dimension of sliceOrigin and sliceDimensions must be byte aligned.

Parameters

bytes: A pointer to bytes of data that this method copies the slice into.
strides: An array of strides, in elements, that describes the layout of the data in bytes.
sliceOrigin: An array of per-dimension offsets that together locate the first element to copy in the tensor. Each element in this array corresponds to the dimension at the same index in sliceDimensions. Each offset value represents the number of elements from the start of that dimension.
sliceDimensions: An array of per-dimension sizes that together define the extent of the slice to copy from the tensor. Each element in this array corresponds to the dimension at the same index in sliceOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in sliceOrigin.
plane: The plane the method reads data from.

func

`MTLTensor.replace`

NewiOSmacOStvOS

func replace(sliceOrigin: MTLTensorExtents, sliceDimensions: MTLTensorExtents, plane: MTLTensorPlaneType, withBytes bytes: UnsafeRawPointer, strides: MTLTensorExtents)

Replaces a slice of a plane of this tensor with data from a pointer you provide.

When writing to auxiliary planes, specify sliceOrigin and sliceDimensions in plane coordinates by applying the auxiliary plane's block factors.

Create the tensor with MTLResourceStorageModeShared for CPU access via this method. Strides must be monotonically non-decreasing: for any i > 0, strides[i] >= strides[i-1] * dimensions[i-1].

The first dimension of sliceOrigin and sliceDimensions must be byte aligned.

Parameters

sliceOrigin: An array of per-dimension offsets that together locate the first element to write to in the tensor. Each element in this array corresponds to the dimension at the same index in sliceDimensions. Each offset value represents the number of elements from the start of that dimension.
sliceDimensions: An array of per-dimension sizes that together define the extent of the slice to write to in the tensor. Each element in this array corresponds to the dimension at the same index in sliceOrigin. Each size value represents the number of elements to include along that dimension, starting from the corresponding offset in sliceOrigin.
plane: The plane the method writes data to.
bytes: A pointer to bytes of data to copy into the slice.
strides: An array of strides, in elements, that describes the layout of the data in bytes.

var

`MTLTensorBinding.auxiliaryPlanes`

NewiOSmacOStvOS

var auxiliaryPlanes: [MTLTensorAuxiliaryPlaneType] { get }

An array of the tensor's auxiliary planes.

case

`MTLTensorDataType.float4e2m1`

NewiOSmacOStvOS

case float4e2m1 = 148

A 4-bit floating point format data type with 2 exponent bits, 1 mantissa bit and 1 sign bit.

case

`MTLTensorDataType.float8e4m3`

NewiOSmacOStvOS

case float8e4m3 = 142

An 8-bit floating point format data type with 4 exponent bits, 3 mantissa bits and 1 sign bit.

case

`MTLTensorDataType.float8e5m2`

NewiOSmacOStvOS

case float8e5m2 = 141

An 8-bit floating point format data type with 5 exponent bits, 2 mantissa bits and 1 sign bit.

case

`MTLTensorDataType.float8ue8m0`

NewiOSmacOStvOS

case float8ue8m0 = 145

An 8-bit floating point format data type with 8 exponent bits.

case

`MTLTensorDataType.int2`

NewiOSmacOStvOS

case int2 = 150

A 2-bit signed integer format data type.

case

`MTLTensorDataType.uint2`

NewiOSmacOStvOS

case uint2 = 149

A 2-bit unsigned integer format data type.

Deprecated

enum

`MTLDeviceLocation`

DeprecatedmacOS

public enum MTLDeviceLocation : UInt, @unchecked Sendable

DeprecatedNot applicable on Apple Silicon

Declaration

public enum MTLDeviceLocation : UInt, @unchecked Sendable {

    case builtIn = 0

    case slot = 1

    case external = 2

    case unspecified = 18446744073709551615
}

typealias

`MTLDeviceNotificationHandler`

DeprecatedmacOS

public typealias MTLDeviceNotificationHandler = @Sendable (any MTLDevice, MTLDeviceNotificationName) -> Void

DeprecatedDevice notifications are not applicable on Apple Silicon

struct

`MTLDeviceNotificationName`

DeprecatedmacOS

public struct MTLDeviceNotificationName : Hashable, Equatable, RawRepresentable, @unchecked Sendable

DeprecatedDevice notifications are not applicable on Apple Silicon

Declaration

public struct MTLDeviceNotificationName : Hashable, Equatable, RawRepresentable, @unchecked Sendable {

    public init(rawValue: String)
}

func

`MTLRemoveDeviceObserver`

DeprecatedmacOS

public func MTLRemoveDeviceObserver(_ observer: any NSObjectProtocol)

DeprecatedDevice notifications are not applicable on Apple Silicon

var

`MTL4CommandQueueError.deviceRemoved`

DeprecatediOSmacOStvOSvisionOS

public static var deviceRemoved: MTL4CommandQueueError.Code { get }

DeprecatedMTL4CommandQueueErrorDeviceRemoved cannot occur on Apple Silicon

Indicates the physical removal of the GPU before the command buffer completed.

case

`MTL4CommandQueueError.Code.deviceRemoved`

DeprecatediOSmacOStvOSvisionOS

case deviceRemoved = 4

DeprecatedMTL4CommandQueueErrorDeviceRemoved cannot occur on Apple Silicon

Indicates the physical removal of the GPU before the command buffer completed.

func

`MTLBlitCommandEncoder.synchronize`

DeprecatedmacOS

func synchronize(resource: any MTLResource)

DeprecatedManaged storage has no effect on Apple Silicon, use Shared storage instead

func

`MTLBlitCommandEncoder.synchronize`

DeprecatedmacOS

func synchronize(texture: any MTLTexture, slice: Int, level: Int)

DeprecatedManaged storage has no effect on Apple Silicon, use Shared storage instead

func

`MTLBuffer.makeRemoteBufferView`

DeprecatedmacOS

func makeRemoteBufferView(_ device: any MTLDevice) -> (any MTLBuffer)?

DeprecatedNot applicable on Apple Silicon

var

`MTLBuffer.remoteStorageBuffer`

DeprecatedmacOS

var remoteStorageBuffer: (any MTLBuffer)? { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLCommandBufferError.deviceRemoved`

DeprecatedmacOS

public static var deviceRemoved: MTLCommandBufferError.Code { get }

DeprecatedMTLCommandBufferErrorDeviceRemoved cannot occur on Apple Silicon

case

`MTLCommandBufferError.Code.deviceRemoved`

DeprecatedmacOS

case deviceRemoved = 11

DeprecatedMTLCommandBufferErrorDeviceRemoved cannot occur on Apple Silicon

var

`MTLDevice.isDepth24Stencil8PixelFormatSupported`

DeprecatedmacOS

var isDepth24Stencil8PixelFormatSupported: Bool { get }

DeprecatedNever supported on Apple Silicon

var

`MTLDevice.isHeadless`

DeprecatedmacOS

var isHeadless: Bool { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.isLowPower`

DeprecatedmacOS

var isLowPower: Bool { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.isRemovable`

DeprecatedmacOS

var isRemovable: Bool { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.location`

DeprecatedmacOS

var location: MTLDeviceLocation { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.locationNumber`

DeprecatedmacOS

var locationNumber: Int { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.maxTransferRate`

DeprecatedmacOS

var maxTransferRate: UInt64 { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.peerCount`

DeprecatedmacOS

var peerCount: UInt32 { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.peerGroupID`

DeprecatedmacOS

var peerGroupID: UInt64 { get }

DeprecatedNot applicable on Apple Silicon

var

`MTLDevice.peerIndex`

DeprecatedmacOS

var peerIndex: UInt32 { get }

DeprecatedNot applicable on Apple Silicon

let

`MTLDeviceNotificationName.removalRequested`

DeprecatedmacOS

public static let removalRequested: MTLDeviceNotificationName

DeprecatedDevice notifications are not applicable on Apple Silicon

let

`MTLDeviceNotificationName.wasAdded`

DeprecatedmacOS

public static let wasAdded: MTLDeviceNotificationName

DeprecatedDevice notifications are not applicable on Apple Silicon

let

`MTLDeviceNotificationName.wasRemoved`

DeprecatedmacOS

public static let wasRemoved: MTLDeviceNotificationName

DeprecatedDevice notifications are not applicable on Apple Silicon

case

`MTLGPUFamily.common1`

DeprecatediOSmacOStvOSvisionOS

case common1 = 3001

DeprecatedMTLGPUFamily.apple1

case

`MTLGPUFamily.common2`

DeprecatediOSmacOStvOSvisionOS

case common2 = 3002

DeprecatedMTLGPUFamily.apple3

case

`MTLGPUFamily.common3`

DeprecatediOSmacOStvOSvisionOS

case common3 = 3003

DeprecatedMTLGPUFamily.apple5

case

`MTLGPUFamily.mac2`

DeprecatediOSmacOStvOSvisionOS

case mac2 = 2002

DeprecatedMTLGPUFamily.apple7

case

`MTLPixelFormat.depth24Unorm_stencil8`

DeprecatedmacOS

case depth24Unorm_stencil8 = 255

DeprecatedUse MTLPixelFormatDepth32Float_Stencil8 instead

case

`MTLPixelFormat.x24_stencil8`

DeprecatedmacOS

case x24_stencil8 = 262

DeprecatedUse MTLPixelFormatX32_Stencil8 instead

var

`MTLResourceOptions.storageModeManaged`

DeprecatedmacOS

public static var storageModeManaged: MTLResourceOptions { get }

DeprecatedManaged storage has no effect on Apple Silicon, use Shared storage instead

case

`MTLStorageMode.managed`

DeprecatedmacOS

case managed = 1

DeprecatedManaged storage has no effect on Apple Silicon, use Shared storage instead

func

`MTLTexture.makeRemoteTextureView`

DeprecatedmacOS

func makeRemoteTextureView(_ device: any MTLDevice) -> (any MTLTexture)?

DeprecatedNot applicable on Apple Silicon

var

`MTLTexture.remoteStorageTexture`

DeprecatedmacOS

var remoteStorageTexture: (any MTLTexture)? { get }

DeprecatedNot applicable on Apple Silicon

No APIs match your filter.

← More in Graphics & Metal