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:

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

To copy pixel data back into system memory, call getBytes:bytesPerRow:bytesPerImage:fromRegion:mipmapLevel:slice: or getBytes:bytesPerRow:fromRegion:mipmapLevel:.

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 texture's storage allocation, reinterpreting the data using a different pixel format.

Required.

- newTextureViewWithPixelFormat:textureType:levels:slices:

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

Required.

- newTextureViewWithPixelFormat:textureType:levels:slices:swizzle:

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.

Required.

Beta

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

Options that determine how you can use the texture.

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.

swizzle

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

Required.

Beta
MTLTextureType

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

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

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.

Creating Views of Textures on Other GPUs

- newRemoteTextureViewForDevice:

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

Required.

remoteStorageTexture

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

Required.

Relationships

Inherits From

See Also

Textures

Creating and Sampling Textures

Load image data into a texture and apply it to a quadrangle.

About Color-Renderable Pixel Format Sizes

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

Optimizing Texture Data

Optimize a texture’s data to improve GPU or CPU access.

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.

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