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 newTextureWithDescriptor: 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 newTextureWithDescriptor:iosurface:plane: method instead.

  • The newTextureViewWithPixelFormat: and newTextureViewWithPixelFormat: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 newTextureWithDescriptor: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 MTLTextureType1D, MTLTextureType2D, MTLTextureType2DMultisample, or MTLTextureType3D texture type image and all its mipmaps. MTLTextureType1D, MTLTextureType2D, MTLTextureType2DMultisample, and MTLTextureType3D texture types have a single slice. A MTLTextureTypeCube texture always has six slices, one for each face. For a texture array object, such as MTLTextureType1DArray, MTLTextureType2DArray, or MTLTextureTypeCubeArray, every array element is one slice.

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

Topics

Copying Data into a Texture Image

- replaceRegion:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:

Copies pixel data into a section of a texture slice.

Required.

- replaceRegion:mipmapLevel:withBytes:bytesPerRow:

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

Required.

Copying Data from a Texture Image

- getBytes:bytesPerRow:bytesPerImage:fromRegion:mipmapLevel:slice:

Copies pixel data from a texture to memory.

Required.

- getBytes:bytesPerRow:fromRegion:mipmapLevel:

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

Required.

Creating Textures by Reusing Image Data

- newTextureViewWithPixelFormat:

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.

- newTextureViewWithPixelFormat:textureType:levels:slices:

Creates a new texture object that shares the same storage as part of another texture, reinterpreting the texture image data with a different pixel format.

Required.

Querying Texture Attributes

textureType

The dimension and arrangement of the texture image data.

Required.

pixelFormat

The format of pixels in the texture.

Required.

width

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

Required.

height

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

Required.

depth

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

Required.

mipmapLevelCount

The number of mipmap levels in the texture.

Required.

arrayLength

The number of slices in the texture array.

Required.

sampleCount

The number of samples in each pixel.

Required.

framebufferOnly

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

Required.

usage

A description of how the texture can be accessed in shaders.

Required.

allowGPUOptimizedContents

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

Required.

shareable

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

Required.

MTLTextureType

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

MTLTextureUsage

The options that determine how a texture will be used.

Getting Information about the IOSurface the Texture Was Created From

iosurface

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

Required.

iosurfacePlane

The plane of the IOSurface to reference if any.

Required.

Getting Information about Ancestor Resources

parentTexture

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

Required.

parentRelativeLevel

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

Required.

parentRelativeSlice

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

Required.

buffer

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

Required.

bufferOffset

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

Required.

bufferBytesPerRow

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

Required.

rootResource

The resource that owns the storage for this texture.

Required.

Deprecated

Creating a Shared Texture Handle

- newSharedTextureHandle

Creates a new texture handle from a shareable texture.

Required.

Relationships

Inherits From

See Also

Textures

Basic Texturing

Demonstrates how to load image data and texture a quad.

About Color-Renderable Pixel Format Sizes

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

MTLTextureDescriptor

An object that you use to configure new Metal texture objects.

MTKTextureLoader

An object that decodes common image formats into Metal textures for use in your app.

MTLSharedTextureHandle

A texture handle that can be shared across process address space boundaries.

MTLPixelFormat

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