<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.11.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/MTLTexture",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Metal"
    ],
    "preciseIdentifier" : "c:objc(pl)MTLTexture"
  },
  "title" : "MTLTexture"
}
-->

# MTLTexture

A resource that holds formatted image data.

```
protocol MTLTexture : MTLResource
```

## Overview

Don’t implement this protocol yourself; instead, use one of the following methods to create an [`MTLTexture`](/documentation/Metal/MTLTexture) instance:

- Create an ``doc://com.apple.metal/documentation/Metal/MTLTextureDescriptor`` instance to describe the texture’s properties and then call the ``doc://com.apple.metal/documentation/Metal/MTLDevice/makeTexture(descriptor:)`` method of the ``doc://com.apple.metal/documentation/Metal/MTLDevice`` protocol to create the texture.
- To create a texture that uses an existing
  <doc://com.apple.documentation/documentation/IOSurface/IOSurface> to hold the texture data,
  create an ``doc://com.apple.metal/documentation/Metal/MTLTextureDescriptor`` instance to describe the image data in the surface.
  Call the ``doc://com.apple.metal/documentation/Metal/MTLDevice/makeTexture(descriptor:iosurface:plane:)`` method to create the texture.
- To create a texture that reinterprets another texture’s data as if it has a different format,
  call one of the following texture methods:
  - ``doc://com.apple.metal/documentation/Metal/MTLTexture/makeTextureView(pixelFormat:)``
  - ``doc://com.apple.metal/documentation/Metal/MTLTexture/makeTextureView(pixelFormat:textureType:levels:slices:)`` (Swift)
  - ``doc://com.apple.metal/documentation/Metal/MTLTexture/newTextureViewWithPixelFormat:textureType:levels:slices:`` (Objective-C)
  
  You need to 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, the source texture reflects those changes, and vice versa.
- To create a texture that uses an ``doc://com.apple.metal/documentation/Metal/MTLBuffer`` instance’s contents to hold pixel data,
  create an ``doc://com.apple.metal/documentation/Metal/MTLTextureDescriptor`` instance to describe the texture’s properties.
  Then call the ``doc://com.apple.metal/documentation/Metal/MTLBuffer/makeTexture(descriptor:offset:bytesPerRow:)`` method on the buffer instance. The new texture instance shares the storage allocation of the source buffer instance.
  If you make changes to the texture, the buffer reflects those changes, and vice versa.

After you create an [`MTLTexture`](/documentation/Metal/MTLTexture) instance, most of its characteristics,
such as its size, type, and pixel format are all immutable.
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:)`](/documentation/Metal/MTLTexture/replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:)) or [`replace(region:mipmapLevel:withBytes:bytesPerRow:)`](/documentation/Metal/MTLTexture/replace(region:mipmapLevel:withBytes:bytesPerRow:)).

To copy pixel data back to system memory, call [`getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:)`](/documentation/Metal/MTLTexture/getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:)) or [`getBytes(_:bytesPerRow:from:mipmapLevel:)`](/documentation/Metal/MTLTexture/getBytes(_:bytesPerRow:from:mipmapLevel:)).

## Topics

### Copying data into a texture image

[`replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:)`](/documentation/Metal/MTLTexture/replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:))

Copies pixel data into a section of a texture slice.

[`replace(region:mipmapLevel:withBytes:bytesPerRow:)`](/documentation/Metal/MTLTexture/replace(region:mipmapLevel:withBytes:bytesPerRow:))

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

### Copying data from a texture image

[`getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:)`](/documentation/Metal/MTLTexture/getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:))

Copies pixel data from the texture to a buffer in system memory.

[`getBytes(_:bytesPerRow:from:mipmapLevel:)`](/documentation/Metal/MTLTexture/getBytes(_:bytesPerRow:from:mipmapLevel:))

Copies pixel data from the first slice of the texture to a buffer in system memory.

### Creating textures by reinterpreting existing texture data

[`makeTextureView(pixelFormat:)`](/documentation/Metal/MTLTexture/makeTextureView(pixelFormat:))

Creates a new view of the texture, reinterpreting its data using a different pixel format.

[`makeTextureView(pixelFormat:textureType:levels:slices:)`](/documentation/Metal/MTLTexture/makeTextureView(pixelFormat:textureType:levels:slices:))

Creates a new view of the texture, reinterpreting a subset of its data using a different type and pixel format.

[`makeTextureView(pixelFormat:textureType:levels:slices:swizzle:)`](/documentation/Metal/MTLTexture/makeTextureView(pixelFormat:textureType:levels:slices:swizzle:))

Creates a new view of the texture, reinterpreting a subset of its data using a different type, pixel format, and swizzle pattern.

[`newTextureViewWithPixelFormat:textureType:levels:slices:`](/documentation/Metal/MTLTexture/newTextureViewWithPixelFormat:textureType:levels:slices:)

Creates a new view of the texture, reinterpreting a subset of its data using a different type and pixel format.

[`newTextureViewWithPixelFormat:textureType:levels:slices:swizzle:`](/documentation/Metal/MTLTexture/newTextureViewWithPixelFormat:textureType:levels:slices:swizzle:)

Creates a new view of the texture, reinterpreting a subset of its data using a different type, pixel format, and swizzle pattern.

### Querying texture attributes

[`textureType`](/documentation/Metal/MTLTexture/textureType)

The dimension and arrangement of the texture image data.

[`pixelFormat`](/documentation/Metal/MTLTexture/pixelFormat)

The format of pixels in the texture.

[`width`](/documentation/Metal/MTLTexture/width)

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

[`height`](/documentation/Metal/MTLTexture/height)

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

[`depth`](/documentation/Metal/MTLTexture/depth)

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

[`mipmapLevelCount`](/documentation/Metal/MTLTexture/mipmapLevelCount)

The number of mipmap levels in the texture.

[`arrayLength`](/documentation/Metal/MTLTexture/arrayLength)

The number of slices in the texture array.

[`sampleCount`](/documentation/Metal/MTLTexture/sampleCount)

The number of samples in each pixel.

[`isFramebufferOnly`](/documentation/Metal/MTLTexture/isFramebufferOnly)

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

[`usage`](/documentation/Metal/MTLTexture/usage)

Options that determine how you can use the texture.

[`allowGPUOptimizedContents`](/documentation/Metal/MTLTexture/allowGPUOptimizedContents)

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

[`isShareable`](/documentation/Metal/MTLTexture/isShareable)

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

[`swizzle`](/documentation/Metal/MTLTexture/swizzle)

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

[`MTLTextureType`](/documentation/Metal/MTLTextureType)

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

[`MTLTextureUsage`](/documentation/Metal/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`](/documentation/Metal/MTLTexture/iosurface)

A reference to the underlying surface instance for the texture, if applicable.

[`iosurfacePlane`](/documentation/Metal/MTLTexture/iosurfacePlane)

The number of a plane within the underlying surface instance for the texture, if applicable.

### Getting information about ancestor resources

[`parent`](/documentation/Metal/MTLTexture/parent)

The parent texture used to create this texture, if any.

[`parentRelativeLevel`](/documentation/Metal/MTLTexture/parentRelativeLevel)

The base level of the parent texture used to create this texture.

[`parentRelativeSlice`](/documentation/Metal/MTLTexture/parentRelativeSlice)

The base slice of the parent texture used to create this texture.

[`buffer`](/documentation/Metal/MTLTexture/buffer)

The source buffer used to create this texture, if any.

[`bufferOffset`](/documentation/Metal/MTLTexture/bufferOffset)

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

[`bufferBytesPerRow`](/documentation/Metal/MTLTexture/bufferBytesPerRow)

The number of bytes in each row of the texture’s source buffer.

[`rootResource`](/documentation/Metal/MTLTexture/rootResource)

The resource that owns the storage for this texture.

### Creating a shared texture handle

[`makeSharedTextureHandle()`](/documentation/Metal/MTLTexture/makeSharedTextureHandle())

Creates a new texture handle from a shareable texture.

### Creating views of textures on other GPUs

[`makeRemoteTextureView(_:)`](/documentation/Metal/MTLTexture/makeRemoteTextureView(_:))

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

[`remoteStorageTexture`](/documentation/Metal/MTLTexture/remoteStorageTexture)

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

### Querying sparse properties

[`isSparse`](/documentation/Metal/MTLTexture/isSparse)

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

[`firstMipmapInTail`](/documentation/Metal/MTLTexture/firstMipmapInTail)

The index of the first mipmap in the tail.

[`tailSizeInBytes`](/documentation/Metal/MTLTexture/tailSizeInBytes)

The size of the sparse texture tail, in bytes.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)