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:

The makeTexture(descriptor:) method of the MTLDevice protocol creates a texture object with a new storage allocation for the texture image data, using a MTLTextureDescriptor object to describe the texture’s properties. To further specify an IOSurface from which to create the texture, use the makeTexture(descriptor:iosurface:plane:) method instead.
The makeTextureView(pixelFormat:) and makeTextureView(pixelFormat:textureType:levels:slices:) methods of the MTLTexture protocol create and return a new texture object that shares the same storage allocation as the source texture object. Because they share the same storage, any changes to the pixels of the new texture are reflected in the source texture, and vice versa. For the newly created texture, these methods reinterpret the existing texture image data in the storage allocation of the source texture as if this data were stored in the new specified pixel format. The pixel format of the new texture must be compatible with the pixel format of the source texture.
The makeTexture(descriptor:offset:bytesPerRow:) method of the MTLBuffer protocol creates and returns a new texture object that shares the storage allocation of the source buffer object as its texture image data. Because they share the same storage, any changes to the pixels of the new texture are reflected in the source buffer, and vice versa.

The textureType property identifies how the image data is organized. Image data is arranged in one or more slices, and each slice is a single MTLTextureType.type1D, MTLTextureType.type2D, MTLTextureType.type2DMultisample, or MTLTextureType.type3D texture type image and all its mipmaps. MTLTextureType.type1D, MTLTextureType.type2D, MTLTextureType.type2DMultisample, and MTLTextureType.type3D texture types have a single slice. A MTLTextureType.typeCube texture always has six slices, one for each face. For a texture array object, such as MTLTextureType.type1DArray, MTLTextureType.type2DArray, or MTLTextureType.typeCubeArray, every array element is one slice.

After you create a texture, you can call replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:) or replace(region:mipmapLevel:withBytes:bytesPerRow:) to populate the storage allocation of the texture object with image data from system memory. Call getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:) or getBytes(_:bytesPerRow:from:mipmapLevel:) to copy image data from a texture object and store the copied data into system memory.

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 same storage allocation of the texture, reinterpreting the texture image data with 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 same storage allocation of the texture, reinterpreting the texture image data with a different pixel format.