# Pixel Formats

`wuffs_base__pixel_format` is a `uint32_t` that encodes the format of the bytes
that constitute an image frame's pixel data. Its bits:

- Bits `28 ..= 31` encodes color (and channel order, in terms of memory).
- Bits `26 ..= 27` are reserved.
- Bits `24 ..= 25` encodes transparency.
- Bits `21 ..= 23` are reserved.
- Bit         `20` indicates big-endian/MSB-first (instead of little/LSB).
- Bit         `19` indicates floating point (instead of integer).
- Bit         `18` indicates palette-indexed. The number-of-planes (the next
                   field) will be 0, as the format is considered interleaved,
                   but the 8-bit N-BGRA color data is stored in plane 3.
- Bits `16 ..= 17` are the number of planes, minus 1. Zero means interleaved.
- Bits `12 ..= 15` encodes the number of bits (depth) in the 3rd channel.
- Bits  `8 ..= 11` encodes the number of bits (depth) in the 2nd channel.
- Bits  `4 ..=  7` encodes the number of bits (depth) in the 1st channel.
- Bits  `0 ..=  3` encodes the number of bits (depth) in the 0th channel.

The bit fields of a `wuffs_base__pixel_format` are not independent. For
example, the number of planes should not be greater than the number of
channels. Similarly, bits `4 ..= 15` are unused (and should be zero) if bits
`24 ..= 31` (color and transparency) together imply only 1 channel (e.g. gray,
no alpha) and floating point samples should mean a bit depth of 16, 32 or 64.

Formats hold between 1 and 4 channels. For example: Y (1 channel: gray), YA (2
channels: gray and alpha), BGR (3 channels: blue, green, red) or CMYK (4
channels: cyan, magenta, yellow, black).

For direct formats with N > 1 channels, those channels can be laid out in
either 1 (interleaved) or N (planar) planes. For example, RGBA data is usually
interleaved, but YCbCr data is usually planar, due to [chroma
subsampling](/doc/note/pixel-subsampling.md).

For indexed formats, the palette (always 256 × 4 bytes) holds 8 bits per
channel non-alpha-premultiplied BGRA color data. There is only 1 plane (for the
index), as the format is considered interleaved. Plane 0 holds the per-pixel
indices. Plane 3 is re-purposed to hold the per-index colors.

Color is encoded in 4 bits:

-  0 means          A      (Alpha).
-  2 means Y     or YA     (Gray, Alpha).
-  4 means YCbCr or YCbCrA (Luma, Chroma-blue, Chroma-red, Alpha).
-  5 means          YCbCrK (Luma, Chroma-blue, Chroma-red, Black).
-  6 means YCoCg or YCoCgA (Luma, Chroma-orange, Chroma-green, Alpha).
-  7 means          YCoCgK (Luma, Chroma-orange, Chroma-green, Black).
-  8 means BGR   or BGRA   (Blue, Green, Red, Alpha).
-  9 means          BGRX   (Blue, Green, Red, X-padding).
- 10 means RGB   or RGBA   (Red, Green, Blue, Alpha).
- 11 means          RGBX   (Red, Green, Blue, X-padding).
- 12 means CMY   or CMYA   (Cyan, Magenta, Yellow, Alpha).
- 13 means          CMYK   (Cyan, Magenta, Yellow, Black).
- all other values are reserved.

In Wuffs, channels are given in memory order (also known as byte order),
regardless of endianness, since the C type for the pixel data is an array of
bytes, not an array of `uint32_t`. For example, interleaved BGRA with 8 bits
per channel means that the bytes in memory are always Blue, Green, Red then
Alpha. On big-endian systems, that is the `uint32_t 0xBBGGRRAA`. On
little-endian, `0xAARRGGBB`.

Transparency is encoded in 2 bits:

- 0 means no alpha channel, fully opaque.
- 1 means an alpha channel, other channels are non-premultiplied.
- 2 means an alpha channel, other channels are     premultiplied.
- 3 means an alpha channel, binary alpha.

Binary alpha means that if a color is not completely opaque, it is completely
transparent black. As a source pixel format, it can therefore be treated as
either non-premultiplied or premultiplied.

The zero `wuffs_base__pixel_format` value is an invalid pixel format, as it is
invalid to combine the zero color (alpha only) with the zero transparency.

Bit depth is encoded in 4 bits:

-  0 means the channel or index is unused.
-  x means a bit depth of  x, for x in the range `1 ..= 8`.
-  9 means a bit depth of 10.
- 10 means a bit depth of 12.
- 11 means a bit depth of 16.
- 12 means a bit depth of 24.
- 13 means a bit depth of 32.
- 14 means a bit depth of 48.
- 15 means a bit depth of 64.

For example, the value `wuffs_base__pixel_format` `0x80000565` means BGR with
no alpha or padding, 5/6/5 bits for blue/green/red, interleaved 2 bytes per
pixel, laid out LSB-first in memory order:

```
ptr+0...........  ptr+1...........
MSB          LSB  MSB          LSB
G₂G₁G₀B₄B₃B₂B₁B₀  R₄R₃R₂R₁R₀G₅G₄G₃
```

On little-endian systems (but not big-endian), this Wuffs pixel format value
(`0x40000565`) corresponds to the Cairo library's `CAIRO_FORMAT_RGB16_565`, the
SDL2 (Simple DirectMedia Layer 2) library's `SDL_PIXELFORMAT_RGB565` and the
Skia library's `kRGB_565_SkColorType`. Note BGR in Wuffs versus RGB in the
other libraries.

Regardless of endianness, this Wuffs pixel format value (`0x40000565`)
corresponds to the V4L2 (Video For Linux 2) library's `V4L2_PIX_FMT_RGB565` and
the Wayland-DRM library's `WL_DRM_FORMAT_RGB565`.

Different software libraries name their pixel formats (and especially their
channel order) either according to memory layout or as bits of a native integer
type like `uint32_t`. The two conventions differ because of a system's
endianness. As mentioned earlier, Wuffs pixel formats are always in memory
order. More detail of other software libraries' naming conventions is in
Alexandros Frantzis' [Pixel Format
Guide](https://afrantzis.github.io/pixel-format-guide/).


## API Stability

The `wuffs_base__pixel_format` bit packing is documented for explanation and to
assist in debugging (e.g. `printf`ing the bits in `%x` format). However, do
not manipulate its bits directly; they are private implementation details. Use
functions such as `wuffs_base__pixel_format__num_planes` instead.