Enumeration

MTLPixelFormat

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

Overview

There are three varieties of pixel formats: ordinary, packed, and compressed. For ordinary and packed formats, the name of the pixel format specifies the order of components (such as R, RG, RGB, RGBA, BGRA), bits per component (such as 8, 16, 32), and data type for the component (such as Float, Sint, Snorm, Uint, Unorm). If the pixel format name has the _sRGB suffix, then sRGB gamma compression and decompression are applied during the reading and writing of color values in the pixel. For compressed formats, the name of the pixel format specifies a compression family (such as ASTC, BC, EAC, ETC2, PVRTC).

Storage Characteristics

The storage size of each pixel format is determined by the sum of its components. For example, the storage size of BGRA8Unorm is 32 bits (four 8-bit components) and the storage size of BGR5A1Unorm is 16 bits (three 5-bit components and one 1-bit component).

For normalized signed integer formats (Snorm), component values in the range [-1.0, 1.0] are stored as [MIN_INT, MAX_INT], where MIN_INT is the greatest negative integer and MAX_INT is the greatest positive integer that can be stored, given the bit size of the component. For normalized unsigned integer formats (Unorm), component values in the range [0.0, 1.0] are stored as [0, MAX_UINT], where MAX_UINT is the greatest unsigned integer that can be stored, given the bit size of the component.

Format data is stored in little-endian order (that is, the least-significant byte in the least-significant address). For formats with components that are themselves byte-aligned and more than one byte, the components are little-endian.

Topics

Ordinary 8-Bit Pixel Formats

case a8Unorm

Ordinary format with one 8-bit normalized unsigned integer component.

case r8Unorm

Ordinary format with one 8-bit normalized unsigned integer component.

case r8Unorm_srgb

Ordinary format with one 8-bit normalized unsigned integer component with conversion between sRGB and linear space.

case r8Snorm

Ordinary format with one 8-bit normalized signed integer component.

case r8Uint

Ordinary format with one 8-bit unsigned integer component.

case r8Sint

Ordinary format with one 8-bit signed integer component.

Ordinary 16-Bit Pixel Formats

case r16Unorm

Ordinary format with one 16-bit normalized unsigned integer component.

case r16Snorm

Ordinary format with one 16-bit normalized signed integer component.

case r16Uint

Ordinary format with one 16-bit unsigned integer component.

case r16Sint

Ordinary format with one 16-bit signed integer component.

case r16Float

Ordinary format with one 16-bit floating-point component.

case rg8Unorm

Ordinary format with two 8-bit normalized unsigned integer components.

case rg8Unorm_srgb

Ordinary format with two 8-bit normalized unsigned integer components with conversion between sRGB and linear space.

case rg8Snorm

Ordinary format with two 8-bit normalized signed integer components.

case rg8Uint

Ordinary format with two 8-bit unsigned integer components.

case rg8Sint

Ordinary format with two 8-bit signed integer components.

Packed 16-Bit Pixel Formats

case b5g6r5Unorm

Packed 16-bit format with normalized unsigned integer color components: 5 bits for blue, 6 bits for green, 5 bits for red, packed into 16 bits.

case a1bgr5Unorm

Packed 16-bit format with normalized unsigned integer color components: 5 bits each for BGR and 1 for alpha, packed into 16 bits.

case abgr4Unorm

Packed 16-bit format with normalized unsigned integer color components: 4 bits each for ABGR, packed into 16 bits.

case bgr5A1Unorm

Packed 16-bit format with normalized unsigned integer color components: 5 bits each for BGR and 1 for alpha, packed into 16 bits.

Ordinary 32-Bit Pixel Formats

case r32Uint

Ordinary format with one 32-bit unsigned integer component.

case r32Sint

Ordinary format with one 32-bit signed integer component.

case r32Float

Ordinary format with one 32-bit floating-point component.

case rg16Unorm

Ordinary format with two 16-bit normalized unsigned integer components.

case rg16Snorm

Ordinary format with two 16-bit normalized signed integer components.

case rg16Uint

Ordinary format with two 16-bit unsigned integer components.

case rg16Sint

Ordinary format with two 16-bit signed integer components.

case rg16Float

Ordinary format with two 16-bit floating-point components.

case rgba8Unorm

Ordinary format with four 8-bit normalized unsigned integer components in RGBA order.

case rgba8Unorm_srgb

Ordinary format with four 8-bit normalized unsigned integer components in RGBA order with conversion between sRGB and linear space.

case rgba8Snorm

Ordinary format with four 8-bit normalized signed integer components in RGBA order.

case rgba8Uint

Ordinary format with four 8-bit unsigned integer components in RGBA order.

case rgba8Sint

Ordinary format with four 8-bit signed integer components in RGBA order.

case bgra8Unorm

Ordinary format with four 8-bit normalized unsigned integer components in BGRA order.

case bgra8Unorm_srgb

Ordinary format with four 8-bit normalized unsigned integer components in BGRA order with conversion between sRGB and linear space.

Packed 32-Bit Pixel Formats

case rgb10a2Unorm

A 32-bit packed pixel format with four normalized unsigned integer components: 10-bit red, 10-bit green, 10-bit blue, and 2-bit alpha.

case rgb10a2Uint

A 32-bit packed pixel format with four unsigned integer components: 10-bit red, 10-bit green, 10-bit blue, and 2-bit alpha.

case rg11b10Float

Packed 32-bit format with floating-point color components: 11 bits each for red and green and 10 bits for blue, packed into 32 bits. The components have no sign bit. The 10-bit float has 5 bits of mantissa and 5 bits of exponent. The 11-bit floats have 6 bits of mantissa and 5 bits of exponent.

case rgb9e5Float

Packed 32-bit format with floating-point color components: 9 bits each for RGB and 5 bits for an exponent shared by RGB, packed into 32 bits.

Ordinary 64-Bit Pixel Formats

case rg32Uint

Ordinary format with two 32-bit unsigned integer components.

case rg32Sint

Ordinary format with two 32-bit signed integer components.

case rg32Float

Ordinary format with two 32-bit floating-point components.

case rgba16Unorm

Ordinary format with four 16-bit normalized unsigned integer components in RGBA order.

case rgba16Snorm

Ordinary format with four 16-bit normalized signed integer components in RGBA order.

case rgba16Uint

Ordinary format with four 16-bit unsigned integer components in RGBA order.

case rgba16Sint

Ordinary format with four 16-bit signed integer components in RGBA order.

case rgba16Float

Ordinary format with four 16-bit floating-point components in RGBA order.

Ordinary 128-Bit Pixel Formats

case rgba32Uint

Ordinary format with four 32-bit unsigned integer components in RGBA order.

case rgba32Sint

Ordinary format with four 32-bit signed integer components in RGBA order.

case rgba32Float

Ordinary format with four 32-bit floating-point components in RGBA order.

Compressed PVRTC Pixel Formats

case pvrtc_rgb_2bpp

Compressed format using PVRTC compression and 2bpp for RGB components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgb_2bpp_srgb

Compressed format using PVRTC compression and 2bpp for RGB components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgb_4bpp

Compressed format using PVRTC compression and 4bpp for RGB components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgb_4bpp_srgb

Compressed format using PVRTC compression and 4bpp for RGB components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgba_2bpp

Compressed format using PVRTC compression and 2bpp for RGBA components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgba_2bpp_srgb

Compressed format using PVRTC compression and 2bpp for RGBA components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgba_4bpp

Compressed format using PVRTC compression and 4bpp for RGBA components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

case pvrtc_rgba_4bpp_srgb

Compressed format using PVRTC compression and 4bpp for RGBA components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported. Subimages are not supported.

Compressed EAC/ETC Pixel Formats

case eac_r11Unorm

Compressed format using EAC compression with one normalized unsigned integer component. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case eac_r11Snorm

Compressed format using EAC compression with one normalized signed integer component. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case eac_rg11Unorm

Compressed format using EAC compression with two normalized unsigned integer components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case eac_rg11Snorm

Compressed format using EAC compression with two normalized signed integer components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case eac_rgba8

Compressed format using EAC compression with four 8-bit components.

case eac_rgba8_srgb

Compressed format using EAC compression with four 8-bit components with conversion between sRGB and linear space.

case etc2_rgb8

Compressed format using ETC2 compression with three 8-bit components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case etc2_rgb8_srgb

Compressed format using ETC2 compression with three 8-bit components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case etc2_rgb8a1

Compressed format using ETC2 compression with four 8-bit components. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

case etc2_rgb8a1_srgb

Compressed format using ETC2 compression with four 8-bit components with conversion between sRGB and linear space. Only MTLTextureType2D, MTLTextureType2DArray, and MTLTextureTypeCube textures are supported.

Compressed ASTC Pixel Formats

case astc_4x4_srgb

Compressed format using ASTC compression low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 4, the block height of 4, and a bit rate of 8.0 bits per pixel.

case astc_5x4_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 5, the block height of 4, and a bit rate of 6.4 bits per pixel.

case astc_5x5_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 5, the block height of 5, and a bit rate of 5.12 bits per pixel.

case astc_6x5_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 6, the block height of 5, and a bit rate of 4.27 bits per pixel.

case astc_6x6_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 6, the block height of 6, and a bit rate of 3.56 bits per pixel.

case astc_8x5_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 8, the block height of 5, and a bit rate of 3.2 bits per pixel.

case astc_8x6_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 8, the block height of 6, and a bit rate of 2.67 bits per pixel.

case astc_8x8_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 8, the block height of 8, and a bit rate of 2.0 bits per pixel.

case astc_10x5_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 10, the block height of 5, and a bit rate of 2.56 bits per pixel.

case astc_10x6_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 10, the block height of 6, and a bit rate of 2.13 bits per pixel.

case astc_10x8_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 10, the block height of 8, and a bit rate of 1.6 bits per pixel.

case astc_10x10_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 10, the block height of 10, and a bit rate of 1.28 bits per pixel.

case astc_12x10_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 12, the block height of 10, and a bit rate of 1.07 bits per pixel.

case astc_12x12_srgb

Compressed format using ASTC compression with low-dynamic range content and conversion between sRGB and linear space. The image is encoded with the block width of 12, the block height of 12, and a bit rate of 0.89 bits per pixel.

case astc_4x4_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 4, the block height of 4, and a bit rate of 8.0 bits per pixel.

case astc_5x4_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 5, the block height of 4, and a bit rate of 6.4 bits per pixel.

case astc_5x5_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 5, the block height of 5, and a bit rate of 5.12 bits per pixel.

case astc_6x5_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 6, the block height of 5, and a bit rate of 4.27 bits per pixel.

case astc_6x6_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 6, the block height of 6, and a bit rate of 3.56 bits per pixel.

case astc_8x5_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 8, the block height of 5, and a bit rate of 3.2 bits per pixel.

case astc_8x6_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 8, the block height of 6, and a bit rate of 2.67 bits per pixel.

case astc_8x8_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 8, the block height of 8, and a bit rate of 2.0 bits per pixel.

case astc_10x5_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 10, the block height of 5, and a bit rate of 2.56 bits per pixel.

case astc_10x6_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 10, the block height of 6, and a bit rate of 2.13 bits per pixel.

case astc_10x8_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 10, the block height of 8, and a bit rate of 1.6 bits per pixel.

case astc_10x10_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 10, the block height of 10, and a bit rate of 1.28 bits per pixel.

case astc_12x10_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 12, the block height of 10, and a bit rate of 1.07 bits per pixel.

case astc_12x12_ldr

Compressed format using ASTC compression with low-dynamic range content that is encoded with the block width of 12, the block height of 12, and a bit rate of 0.89 bits per pixel.

Compressed BC Pixel Formats

case bc1_rgba

Compressed format with two 16-bit color components and one 32-bit descriptor component.

case bc1_rgba_srgb

Compressed format with two 16-bit color components and one 32-bit descriptor component, with conversion between sRGB and linear space.

case bc2_rgba

Compressed format with two 64-bit chunks. The first chunk contains two 8-bit alpha components and one 48-bit descriptor component. The second chunk contains two 16-bit color components and one 32-bit descriptor component.

case bc2_rgba_srgb

Compressed format with two 64-bit chunks, with conversion between sRGB and linear space. The first chunk contains two 8-bit alpha components and one 48-bit descriptor component. The second chunk contains two 16-bit color components and one 32-bit descriptor component.

case bc3_rgba

Compressed format with two 64-bit chunks. The first chunk contains two 8-bit alpha components and one 48-bit descriptor component. The second chunk contains two 16-bit color components and one 32-bit descriptor component.

case bc3_rgba_srgb

Compressed format with two 64-bit chunks, with conversion between sRGB and linear space. The first chunk contains two 8-bit alpha components and one 48-bit descriptor component. The second chunk contains two 16-bit color components and one 32-bit descriptor component.

case bc4_rUnorm

Compressed format with one normalized unsigned integer component.

case bc4_rSnorm

Compressed format with one normalized signed integer component.

case bc5_rgUnorm

Compressed format with two normalized unsigned integer components.

case bc5_rgSnorm

Compressed format with two normalized signed integer components.

case bc6H_rgbFloat

Compressed format with four floating-point components.

case bc6H_rgbuFloat

Compressed format with four unsigned floating-point components.

case bc7_rgbaUnorm

Compressed format with four normalized unsigned integer components.

case bc7_rgbaUnorm_srgb

Compressed format with four normalized unsigned integer components, with conversion between sRGB and linear space.

YUV Pixel Formats

case gbgr422

A pixel format where the red and green components are subsampled horizontally. Two pixels are stored in 32 bits, with shared red and blue values, and unique green values. The component arrangement is the same as it is in YUY2, YUYV, yuvs, and kYUVS pixel formats, except there is no implicit format conversion from a YUV to RGB color space. Only 2D non-mipmapped textures can be created with this pixel format, and the width must be a multiple of 2. Neither MTLTextureType2DArray nor MTLTextureTypeCube textures are supported. This format is a compressed format with a block size of 2x1 in a 32-bit block. During sampling, the address mode must be set to MTLSamplerAddressMode.clampToEdge.

case bgrg422

A pixel format where the red and green components are subsampled horizontally. Two pixels are stored in 32 bits, with shared red and blue values, and unique green values. The component arrangement is the same as it is in UYVY, 2vuy, and k2vuy pixel formats, except there is no implicit format conversion from a YUV to RGB color space. Only 2D non-mipmapped textures can be created with this pixel format, and the width must be a multiple of 2. Neither MTLTextureType2DArray nor MTLTextureTypeCube textures are supported. This format is a compressed format with a block size of 2x1 in a 32-bit block.

Depth and Stencil Pixel Formats

case depth16Unorm

A 16-bit depth pixel format with one normalized unsigned integer component, typically used for a depth render target.

case depth32Float

A 32-bit depth pixel format with one 32-bit floating-point component, typically used for a depth render target.

case stencil8

An 8-bit stencil pixel format with one 8-bit floating-point component, typically used for a stencil render target.

case depth24Unorm_stencil8

A packed 32-bit combined depth and stencil pixel format with two normalized unsigned integer components: 24 bits, typically used for a depth render target, and 8 bits, typically used for a stencil render target.

case depth32Float_stencil8

A 64-bit combined depth and stencil pixel format with two floating-point components: 32 bits, typically used for a depth render target, and 8 bits, typically used for a stencil render target.

case x32_stencil8

A stencil pixel format used for a stencil texture view, typically created from a parent texture with the MTLPixelFormat.depth32Float_stencil8 pixel format.

case x24_stencil8

A stencil pixel format used for a stencil texture view, typically created from a parent texture with the MTLPixelFormat.depth24Unorm_stencil8 pixel format.

Extended Range and Wide Color Pixel Formats

case bgra10_xr

A 64-bit extended range pixel format with four fixed-point components: 10-bit blue, 10-bit green, 10-bit red, and 10-bit alpha.

case bgra10_xr_srgb

A 64-bit extended range pixel format with sRGB conversion and four fixed-point components: 10-bit blue, 10-bit green, 10-bit red, and 10-bit alpha.

case bgr10_xr

A 32-bit extended range pixel format with three fixed-point components: 10-bit blue, 10-bit green, and 10-bit red.

case bgr10_xr_srgb

A 32-bit extended range pixel format with sRGB conversion and three fixed-point components: 10-bit blue, 10-bit green, and 10-bit red.

case bgr10a2Unorm

A 32-bit packed pixel format with four normalized unsigned integer components: 10-bit blue, 10-bit green, 10-bit red, and 2-bit alpha.

Invalid Pixel Format

case invalid

The default value of the pixel format for the MTLRenderPipelineState. You cannot create a texture with this value.

Enumeration Cases

See Also

Textures

Basic Texturing

Demonstrates how to load image data and texture a quad.

protocol MTLTexture

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

class MTLTextureDescriptor

An object that configures new MTLTexture objects.

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