Protocol

MTLTexture

A resource that holds formatted image data.

Declaration

protocol MTLTexture

Overview

Don’t implement this protocol yourself; instead, use one of the following methods to create a MTLTexture object:

Create an MTLTextureDescriptor object to describe the texture's properties and then call the makeTexture(descriptor:) method of the MTLDevice protocol to create the texture.
To create a texture that uses an existing IOSurface to hold the texture data, create an MTLTextureDescriptor object to describe the image data in the surface and then call the makeTexture(descriptor:iosurface:plane:) method to create the texture.
To create a texture that reinterprets another texture's data as if it had a different format, call the makeTextureView(pixelFormat:) or makeTextureView(pixelFormat:textureType:levels:slices:) method on a texture object. You must choose a pixel format for the new texture compatible with the source texture's pixel format. The new texture shares the same storage allocation as the source texture. If you make changes to the new texture, those changes are reflected in the source texture, and vice versa.
To create a texture that uses an MTLBuffer object's contents to hold pixel data, create an MTLTextureDescriptor object to describe the texture's properties and then call the makeTexture(descriptor:offset:bytesPerRow:) method on the buffer object. The new texture object shares the storage allocation of the source buffer object. If you make changes to the texture, those changes are reflected in the buffer, and vice versa.

After you create a MTLTexture object, most of its characteristics, such as its size, type, and pixel format, are all immutable and can't be changed. Only the texture's pixel data is mutable.

To copy pixel data from system memory into the texture, call replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:) or replace(region:mipmapLevel:withBytes:bytesPerRow:).

To copy pixel data back into system memory, call getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:) or getBytes(_:bytesPerRow:from:mipmapLevel:).

Topics

Copying Data into a Texture Image

func replace(region: MTLRegion, mipmapLevel: Int, slice: Int, withBytes: UnsafeRawPointer, bytesPerRow: Int, bytesPerImage: Int)

Copies pixel data into a section of a texture slice.

Required.

func replace(region: MTLRegion, mipmapLevel: Int, withBytes: UnsafeRawPointer, bytesPerRow: Int)

Copies a block of pixels into a section of texture slice 0.

Required.

Copying Data from a Texture Image

func getBytes(UnsafeMutableRawPointer, bytesPerRow: Int, bytesPerImage: Int, from: MTLRegion, mipmapLevel: Int, slice: Int)

Copies pixel data from a texture to memory.

Required.

func getBytes(UnsafeMutableRawPointer, bytesPerRow: Int, from: MTLRegion, mipmapLevel: Int)

Copies pixel data from slice 0 of a texture to memory.

Required.

Creating Textures by Reusing Image Data

func makeTextureView(pixelFormat: MTLPixelFormat) -> MTLTexture?

Creates a new texture object that shares the texture's storage allocation, reinterpreting the data using a different pixel format.

Required.

func makeTextureView(pixelFormat: MTLPixelFormat, textureType: MTLTextureType, levels: Range<Int>, slices: Range<Int>) -> MTLTexture?

Creates a new texture object that shares the texture's storage allocation, reinterpreting the texture image data with a different pixel format.

func makeTextureView(pixelFormat: MTLPixelFormat, textureType: MTLTextureType, levels: Range<Int>, slices: Range<Int>, swizzle: MTLTextureSwizzleChannels) -> MTLTexture?

Creates a new texture object that shares the texture's storage allocation, reinterpreting the texture image data with a different pixel format and sampling pattern.

Querying Texture Attributes

var textureType: MTLTextureType

The dimension and arrangement of the texture image data.

Required.

var pixelFormat: MTLPixelFormat

The format of pixels in the texture.

Required.

var width: Int

The width of the texture image for the base level mipmap, in pixels.

Required.

var height: Int

The height of the texture image for the base level mipmap, in pixels.

Required.

var depth: Int

The depth of the texture image for the base level mipmap, in pixels.

Required.

var mipmapLevelCount: Int

The number of mipmap levels in the texture.

Required.

var arrayLength: Int

The number of slices in the texture array.

Required.

var sampleCount: Int

The number of samples in each pixel.

Required.

var isFramebufferOnly: Bool

A Boolean value that indicates whether the texture can only be used as a render target.

Required.

var usage: MTLTextureUsage

Options that determine how you can use the texture.

Required.

var allowGPUOptimizedContents: Bool

A Boolean value indicating whether the GPU is allowed to adjust the contents of the texture to improve GPU performance.

Required.

var isShareable: Bool

A Boolean indicating whether this texture can be shared with other processes.

Required.

var swizzle: MTLTextureSwizzleChannels

The pattern that the GPU applies to pixels when you read or sample pixels from the texture.

Required.

enum MTLTextureType

The dimension of each image, including whether multiple images are arranged into an array or a cube.

struct MTLTextureUsage

An enumeration for the various options that determine how you can use a texture.

Getting Information about the IOSurface the Texture Was Created From

var iosurface: IOSurfaceRef?

A reference to the IOSurface the texture was created from, if any.

Required.

var iosurfacePlane: Int

The plane of the IOSurface to reference if any.

Required.

Getting Information about Ancestor Resources

var parent: MTLTexture?

The parent texture that the texture was created from, if any.

Required.

var parentRelativeLevel: Int

The base level of the parent texture that the texture was created from, if any.

Required.

var parentRelativeSlice: Int

The base slice of the parent texture that the texture was created from, if any.

Required.

var buffer: MTLBuffer?

The source buffer that the texture was created from, if any.

Required.

var bufferOffset: Int

The offset in the source buffer where the texture's data comes from.

Required.

var bufferBytesPerRow: Int

The bytes per row of the of the data in the source buffer used to create this texture, if any.

Required.

var rootResource: MTLResource?

The resource that owns the storage for this texture.

Required.

Deprecated

Creating a Shared Texture Handle

func makeSharedTextureHandle() -> MTLSharedTextureHandle?

Creates a new texture handle from a shareable texture.

Required.

Creating Views of Textures on Other GPUs

func makeRemoteTextureView(MTLDevice) -> MTLTexture?

Creates a remote texture view for another GPU in the same peer group.

Required.

var remoteStorageTexture: MTLTexture?

The texture on another GPU that the texture was created from, if any.

Required.

Querying Sparse Properties

var isSparse: Bool

A Boolean value that indicates whether this is a sparse texture.

Required.

var firstMipmapInTail: Int

The index of the first mipmap in the tail.

Required.

var tailSizeInBytes: Int

The size of the sparse texture tail, in bytes.

Required.

Relationships

Inherits From

MTLResource

MTLTexture

Declaration

Overview

Topics

Copying Data into a Texture Image

Copying Data from a Texture Image

Creating Textures by Reusing Image Data

Querying Texture Attributes

Getting Information about the IOSurface the Texture Was Created From

Getting Information about Ancestor Resources

Creating a Shared Texture Handle

Creating Views of Textures on Other GPUs

Querying Sparse Properties

Relationships

Inherits From

See Also

Working with Textures