Protocol

MTLTexture

A memory allocation for storing formatted image data that is accessible to the GPU.

Overview

The MTLTexture protocol defines the interface for an object that represents an allocation of formatted image data. Textures are used as source data for a vertex shader, a fragment shader, or a compute kernel. They are also used as an attachment that acts as a rendering destination.

Do not use standard allocation and initialization techniques to create a MTLTexture object. The following methods create and return 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.

  • In iOS, 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 a block of pixels from the caller's pointer into the storage allocation for one texture slice.

Required.

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

Copies a block of pixels from the caller's pointer into the storage allocation for slice 0 of a texture.

Required.

Copying Data from a Texture Image

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

Copies a block of pixels from the storage allocation of a texture slice into system memory at a specified address.

Required.

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

Copies a block of pixels from the storage allocation of texture slice zero into system memory at a specified address.

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 calling texture object, 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 that shares the same storage allocation of the calling texture object, reinterpreting the data with a different format and type.

Querying Texture Attributes

var textureType: MTLTextureType

The dimension and arrangement of the texture image data.

Required.

var pixelFormat: MTLPixelFormat

Format that determines how a pixel is written to, stored as, and read from the storage allocation of 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 for this texture.

Required.

var arrayLength: Int

The number of array elements for a MTLTextureType.type1DArray, MTLTextureType.type2DArray, or MTLTextureType.typeCubeArray type texture object.

Required.

var sampleCount: Int

The number of samples in each fragment.

Required.

var isFramebufferOnly: Bool

A Boolean value that indicates whether the texture is restricted for use as an attachment. If true, this texture can only be used as an attachment for MTLRenderPassDescriptor and cannot be a texture argument for MTLRenderCommandEncoder, MTLBlitCommandEncoder, or MTLComputeCommandEncoder.

Required.

var rootResource: MTLResource?

A value that indicates the storage in a MTLResource object (a texture or buffer) was reused as image data for this texture. If the value is nil, then this texture image is not reusing the image data of another MTLResource object.

Required.

Deprecated
var usage: MTLTextureUsage

The description of the texture usage.

Required.

Querying IOSurface Attributes

var iosurface: IOSurfaceRef?

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

Required.

var iosurfacePlane: Int

The plane of the IOSurface referenced by iosurface, if any.

Required.

Querying Parent Texture Attributes

var parent: MTLTexture?

The parent texture this texture was created from, if any.

Required.

var parentRelativeLevel: Int

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

Required.

var parentRelativeSlice: Int

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

Required.

Querying Source Buffer Attributes

var buffer: MTLBuffer?

The source buffer this texture was created from, if any.

Required.

var bufferOffset: Int

The offset of the source buffer this texture was created from, if any.

Required.

var bufferBytesPerRow: Int

The bytes per row of the source buffer this texture was created from, if any.

Required.

Constants

enum MTLTextureType

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

struct MTLTextureUsage

The options that determine how a texture will be used.

Instance Properties

Relationships

Inherits From

See Also

Textures

Basic Texturing

Demonstrates how to load image data and texture a quad.

class MTLTextureDescriptor

An object that configures new MTLTexture objects.

enum MTLPixelFormat

The data formats that describe the organization and characteristics of individual pixels in a texture.

MetalKit Texture Loader

Load textures into your Metal app from a variety of sources.

About Color-Renderable Pixel Format Sizes

Know the size limits of pixel formats used by color render targets in iOS and tvOS GPUs.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software