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:
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 15..4 are unused (and should be zero) if bits 31..24 (color and transparency) together imply only 1 channel (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.
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.
The color field is encoded in 3 bits:
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.
When the color field (3 bits) encodes multiple options, the transparency field (3 bits) distinguishes them:
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:
For example, the value wuffs_base__pixel_format 0x40000565 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.
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.