<!--
{
  "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/MTLTextureDescriptor",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Metal"
    ],
    "preciseIdentifier" : "c:objc(cs)MTLTextureDescriptor"
  },
  "title" : "MTLTextureDescriptor"
}
-->

# MTLTextureDescriptor

An instance that you use to configure new Metal texture instances.

```
class MTLTextureDescriptor
```

## Overview

To create a new texture, first create an [`MTLTextureDescriptor`](/documentation/Metal/MTLTextureDescriptor) instance and set its property values. Then, call either the [`makeTexture(descriptor:)`](/documentation/Metal/MTLDevice/makeTexture(descriptor:)) or [`makeTexture(descriptor:iosurface:plane:)`](/documentation/Metal/MTLDevice/makeTexture(descriptor:iosurface:plane:)) method of an [`MTLDevice`](/documentation/Metal/MTLDevice) instance, or the [`makeTexture(descriptor:offset:bytesPerRow:)`](/documentation/Metal/MTLBuffer/makeTexture(descriptor:offset:bytesPerRow:)) method of an [`MTLBuffer`](/documentation/Metal/MTLBuffer) instance.

When you create a texture, Metal copies property values from the descriptor into the new texture. You can reuse an [`MTLTextureDescriptor`](/documentation/Metal/MTLTextureDescriptor) instance, modifying its property values as needed, to create more [`MTLTexture`](/documentation/Metal/MTLTexture) instances, without affecting any textures you already created.

## Topics

### Creating texture descriptors

[`texture2DDescriptor(pixelFormat:width:height:mipmapped:)`](/documentation/Metal/MTLTextureDescriptor/texture2DDescriptor(pixelFormat:width:height:mipmapped:))

Creates a texture descriptor object for a 2D texture.

[`textureCubeDescriptor(pixelFormat:size:mipmapped:)`](/documentation/Metal/MTLTextureDescriptor/textureCubeDescriptor(pixelFormat:size:mipmapped:))

Creates a texture descriptor object for a cube texture.

[`textureBufferDescriptor(with:width:resourceOptions:usage:)`](/documentation/Metal/MTLTextureDescriptor/textureBufferDescriptor(with:width:resourceOptions:usage:))

Creates a texture descriptor object for a texture buffer.

### Specifying texture attributes

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

The dimension and arrangement of texture image data.

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

The size and bit layout of all pixels in the texture.

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

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

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

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

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

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

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

The number of mipmap levels for this texture.

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

The number of samples in each fragment.

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

The number of array elements for this texture.

[`resourceOptions`](/documentation/Metal/MTLTextureDescriptor/resourceOptions)

The behavior of a new memory allocation.

[`cpuCacheMode`](/documentation/Metal/MTLTextureDescriptor/cpuCacheMode)

The CPU cache mode used for the CPU mapping of the texture.

[`storageMode`](/documentation/Metal/MTLTextureDescriptor/storageMode)

The location and access permissions of the texture.

[`hazardTrackingMode`](/documentation/Metal/MTLTextureDescriptor/hazardTrackingMode)

The texture’s hazard tracking mode.

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

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

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

Options that determine how you can use the texture.

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

The pattern you want the GPU to apply to pixels when you read or sample pixels from the texture.

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

A pattern that modifies the data read or sampled from a texture by rearranging or duplicating the elements of a vector.

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

Creates a new swizzle pattern.

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

A set of options to choose from when creating a texture swizzle pattern.

[`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.


---

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)