MTLPixelFormat

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

Declaration

enum MTLPixelFormat

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 reading and writing pixel data applies sRGB gamma compression and decompression. The alpha component of sRGB pixel formats is always treated as a linear value. For compressed formats, the name of the pixel format specifies a compression family (such as ASTC, BC, EAC, ETC2, PVRTC).

Storage characteristics

The number and size of each pixel component determines the storage size of each pixel format. For example, the storage size of MTLPixelFormat.bgra8Unorm is 32 bits (four 8-bit components) and the storage size of MTLPixelFormat.bgr5A1Unorm is 16 bits (three 5-bit components and one 1-bit component).

For normalized signed integer formats (Snorm), values in the range [-1.0, 1.0] map to [MIN_INT, MAX_INT], where MIN_INT is the most negative integer and MAX_INT is the most positive integer for the number of bits in the storage size. Positive values and zero distribute uniformly in the range [0.0, 1.0], and negative integer values greater than (MIN_INT + 1) distribute uniformly in the range (-1.0, 0.0).

For normalized unsigned integer formats (Unorm), values in the range [0.0, 1.0] are uniformly mapped to [0, MAX_UINT], where MAX_UINT is the largest unsigned integer for the number of bits in the storage size.

Metal stores format data in little-endian byte order, with the least-significant byte at the lowest memory address. For formats with components that are themselves byte-aligned and more than one byte, Metal also stores each component in little-endian byte order.

See Table 7.7 in the Metal Shading Language Specification (PDF) for details on pixel format normalization.

Topics

Ordinary 8-bit pixel formats

Ordinary 16-bit pixel formats

Packed 16-bit pixel formats

Ordinary 32-bit pixel formats

Packed 32-bit pixel formats

Ordinary 64-bit pixel formats

Ordinary 128-bit pixel formats

Compressed PVRTC pixel formats

Compressed EAC/ETC pixel formats

Compressed ASTC pixel formats

Compressed BC pixel formats

YUV pixel formats

Depth and stencil pixel formats

Extended range and wide color pixel formats