Add doc/note/pixel-formats.md

This commit is contained in:
Nigel Tao committed 2019-12-02 20:34:55 +11:00
1 parent a4f7761182
commit 5362ca7573
7 files changed
+142 -240

No files matched your search

+119
View File
@@ -0,0 +1,119 @@
# 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:
- bit 31 is reserved.
- bits 30 .. 28 encodes color (and channel order, in terms of memory).
- bit 27 is reserved.
- bits 26 .. 24 encodes transparency.
- bits 23 .. 21 are reserved.
- bit 20 indicates big-endian/MSB-first (as opposed to little/LSB).
- bit 19 indicates floating point (as opposed to 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 17 .. 16 are the number of planes, minus 1. Zero means interleaved.
- bits 15 .. 12 encodes the number of bits (depth) in the 3rd channel.
- bits 11 .. 8 encodes the number of bits (depth) in the 2nd channel.
- bits 7 .. 4 encodes the number of bits (depth) in the 1st channel.
- bits 3 .. 0 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 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](/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.
The color field is encoded in 3 bits:
- 0 means A (Alpha).
- 1 means Y or YA (Gray, Alpha).
- 2 means YCbCr or YCbCrA (Luma, Chroma-blue, Chroma-red, Alpha).
- 3 means YCoCg or YCoCgA (Luma, Chroma-orange, Chroma-green, Alpha).
- 4 means BGR, BGRX or BGRA (Blue, Green, Red, X-padding or Alpha).
- 5 means RGB, RGBX or RGBA (Red, Green, Blue, X-padding or Alpha).
- 6 means CMY or 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`.
When the color field (3 bits) encodes multiple options, the transparency field
(3 bits) distinguishes them:
- 0 means fully opaque, no extra channels
- 1 means fully opaque, one extra channel (X or K, padding or black).
- 5 means one extra alpha channel, other channels are non-premultiplied.
- 6 means one extra alpha channel, other channels are premultiplied.
- 7 means one extra alpha channel, binary alpha.
- all other values are reserved.
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` `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](https://afrantzis.github.io/pixel-format-guide/).
Do not manipulate a `wuffs_base__pixel_format`'s bits directly; they are
private implementation details. Use functions such as
`wuffs_base__pixel_format__num_planes` instead.
+3 -1
View File
@@ -36,6 +36,8 @@ TODO: standardize the various dictionary APIs, after Wuffs v0.2 is released.
- [example/zcat](/example/zcat)
---
## Related Documentation
- [I/O (Input / Output)](/doc/note/io-input-output.md)
See also the general remarks on [Wuffs' standard library](/doc/std/README.md).
+3 -1
View File
@@ -27,6 +27,8 @@ reset the state.
- [example/crc32](/example/crc32)
---
## Related Documentation
- [I/O (Input / Output)](/doc/note/io-input-output.md)
See also the general remarks on [Wuffs' standard library](/doc/std/README.md).
+6 -1
View File
@@ -126,6 +126,11 @@ caller can go back to the `decode_image_config` method.
- [GIF decoder quirks](/std/gif/decode_quirks.wuffs)
---
## Related Documentation
- [I/O (Input / Output)](/doc/note/io-input-output.md)
- [Pixel Formats](/doc/note/pixel-formats.md)
- [Pixel Subsampling](/doc/note/pixel-subsampling.md)
- [Ranges and Rects](/doc/note/ranges-and-rects.md)
See also the general remarks on [Wuffs' standard library](/doc/std/README.md).
+3 -113
View File
@@ -24,121 +24,11 @@ typedef uint32_t wuffs_base__color_u32_argb_premul;
// --------
// wuffs_base__pixel_format encodes the format of the bytes that constitute an
// image frame's pixel data. Its bits:
// - bit 31 is reserved.
// - bits 30 .. 28 encodes color (and channel order, in terms of memory).
// - bit 27 is reserved.
// - bits 26 .. 24 encodes transparency.
// - bits 23 .. 21 are reserved.
// - bit 20 indicates big-endian/MSB-first (as opposed to little/LSB).
// - bit 19 indicates floating point (as opposed to 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 17 .. 16 are the number of planes, minus 1. Zero means interleaved.
// - bits 15 .. 12 encodes the number of bits (depth) in the 3rd channel.
// - bits 11 .. 8 encodes the number of bits (depth) in the 2nd channel.
// - bits 7 .. 4 encodes the number of bits (depth) in the 1st channel.
// - bits 3 .. 0 encodes the number of bits (depth) in the 0th channel.
// image frame's pixel data.
//
// 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.
// See https://github.com/google/wuffs/blob/master/doc/note/pixel-formats.md
//
// 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 details, see the wuffs_base__pixel_subsampling type).
//
// 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:
// - 0 means A (Alpha).
// - 1 means Y or YA (Gray, Alpha).
// - 2 means YCbCr or YCbCrA (Luma, Chroma-blue, Chroma-red, Alpha).
// - 3 means YCoCg or YCoCgA (Luma, Chroma-orange, Chroma-green, Alpha).
// - 4 means BGR, BGRX or BGRA (Blue, Green, Red, X-padding or Alpha).
// - 5 means RGB, RGBX or RGBA (Red, Green, Blue, X-padding or Alpha).
// - 6 means CMY or 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.
//
// When the color field (3 bits) encodes multiple options, the transparency
// field (3 bits) distinguishes them:
// - 0 means fully opaque, no extra channels
// - 1 means fully opaque, one extra channel (X or K, padding or black).
// - 5 means one extra alpha channel, other channels are non-premultiplied.
// - 6 means one extra alpha channel, other channels are premultiplied.
// - 7 means one extra alpha channel, binary alpha.
// - all other values are reserved.
//
// 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, wuffs_base__pixel_format 0x5510BBBB is a natural format for
// decoding a PNG image - network byte order (also known as big-endian),
// interleaved, non-premultiplied alpha - that happens to be 16-bit-depth
// truecolor with alpha (RGBA). In memory order:
//
// ptr+0 ptr+1 ptr+2 ptr+3 ptr+4 ptr+5 ptr+6 ptr+7
// Rhi Rlo Ghi Glo Bhi Blo Ahi Alo
//
// 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 the
// Pixel Format Guide at https://afrantzis.github.io/pixel-format-guide/
//
// Do not manipulate these bits directly; they are private implementation
// Do not manipulate its bits directly; they are private implementation
// details. Use methods such as wuffs_base__pixel_format__num_planes instead.
typedef uint32_t wuffs_base__pixel_format;
+5 -11
View File
@@ -104,17 +104,11 @@ const baseImagePrivateH = "" +
const baseImagePublicH = "" +
"// ---------------- Images\n\n// wuffs_base__color_u32_argb_premul is an 8 bit per channel premultiplied\n// Alpha, Red, Green, Blue color, as a uint32_t value. It is in word order, not\n// byte order: its value is always 0xAARRGGBB, regardless of endianness.\ntypedef uint32_t wuffs_base__color_u32_argb_premul;\n\n" +
"" +
"// --------\n\n// wuffs_base__pixel_format encodes the format of the bytes that constitute an\n// image frame's pixel data. Its bits:\n// - bit 31 is reserved.\n// - bits 30 .. 28 encodes color (and channel order, in terms of memory).\n// - bit 27 is reserved.\n// - bits 26 .. 24 encodes transparency.\n// - bits 23 .. 21 are reserved.\n// - bit 20 indicates big-endian/MSB-first (as opposed to little/LSB).\n// - bit 19 indicates floating point (as opposed to integer).\n// - bit 18 indicates palette-indexed. The number-of-planes (the next\n// field) will be 0, as the format is considered interleaved,\n// but the 8-bit N-BGRA color data is stored in plane 3.\n// - bits 17 .. 16 are the number of planes, minus 1. Zero means interleaved.\n// - bits 15 .. 12 encodes the number of bits (depth) in the 3rd channel.\n// - bits 11 .. 8 encodes the number of bits (depth) in the 2nd channel.\n// - bits 7 .. 4 encodes the number of bits (depth) in the 1st" +
" channel.\n// - bits 3 .. 0 encodes the number of bits (depth) in the 0th channel.\n//\n// The bit fields of a wuffs_base__pixel_format are not independent. For\n// example, the number of planes should not be greater than the number of\n// channels. Similarly, bits 15..4 are unused (and should be zero) if bits\n// 31..24 (color and transparency) together imply only 1 channel (gray, no\n// alpha) and floating point samples should mean a bit depth of 16, 32 or 64.\n//\n// Formats hold between 1 and 4 channels. For example: Y (1 channel: gray), YA\n// (2 channels: gray and alpha), BGR (3 channels: blue, green, red) or CMYK (4\n// channels: cyan, magenta, yellow, black).\n//\n// For direct formats with N > 1 channels, those channels can be laid out in\n// either 1 (interleaved) or N (planar) planes. For example, RGBA data is\n// usually interleaved, but YCbCr data is usually planar, due to chroma\n// subsampling (for details, see the wuffs_base__pixel_subsampling type).\n//\n// For indexed formats, the palette (always 256 × 4 " +
"bytes) holds 8 bits per\n// channel non-alpha-premultiplied BGRA color data. There is only 1 plane (for\n// the index), as the format is considered interleaved. Plane 0 holds the\n// per-pixel indices. Plane 3 is re-purposed to hold the per-index colors.\n//\n// The color field is encoded in 3 bits:\n// - 0 means A (Alpha).\n// - 1 means Y or YA (Gray, Alpha).\n// - 2 means YCbCr or YCbCrA (Luma, Chroma-blue, Chroma-red, Alpha).\n// - 3 means YCoCg or YCoCgA (Luma, Chroma-orange, Chroma-green, Alpha).\n// - 4 means BGR, BGRX or BGRA (Blue, Green, Red, X-padding or Alpha).\n// - 5 means RGB, RGBX or RGBA (Red, Green, Blue, X-padding or Alpha).\n// - 6 means CMY or CMYK (Cyan, Magenta, Yellow, Black).\n// - all other values are reserved.\n//\n// In Wuffs, channels are given in memory order (also known as byte order),\n// regardless of endianness, since the C type for the pixel data is an array of\n// bytes, not an array of uint32_t. For example, interleaved BGRA with 8 b" +
"its\n// per channel means that the bytes in memory are always Blue, Green, Red then\n// Alpha. On big-endian systems, that is the uint32_t 0xBBGGRRAA. On\n// little-endian, 0xAARRGGBB.\n//\n// When the color field (3 bits) encodes multiple options, the transparency\n// field (3 bits) distinguishes them:\n// - 0 means fully opaque, no extra channels\n// - 1 means fully opaque, one extra channel (X or K, padding or black).\n// - 5 means one extra alpha channel, other channels are non-premultiplied.\n// - 6 means one extra alpha channel, other channels are premultiplied.\n// - 7 means one extra alpha channel, binary alpha.\n// - all other values are reserved.\n//\n// Binary alpha means that if a color is not completely opaque, it is\n// completely transparent black. As a source pixel format, it can therefore be\n// treated as either non-premultiplied or premultiplied.\n//\n// The zero wuffs_base__pixel_format value is an invalid pixel format, as it is\n// invalid to combine the zero color (alpha only) with the zero trans" +
"parency.\n//\n// Bit depth is encoded in 4 bits:\n// - 0 means the channel or index is unused.\n// - x means a bit depth of x, for x in the range 1..8.\n// - 9 means a bit depth of 10.\n// - 10 means a bit depth of 12.\n// - 11 means a bit depth of 16.\n// - 12 means a bit depth of 24.\n// - 13 means a bit depth of 32.\n// - 14 means a bit depth of 48.\n// - 15 means a bit depth of 64.\n//\n// For example, wuffs_base__pixel_format 0x5510BBBB is a natural format for\n// decoding a PNG image - network byte order (also known as big-endian),\n// interleaved, non-premultiplied alpha - that happens to be 16-bit-depth\n// truecolor with alpha (RGBA). In memory order:\n//\n// ptr+0 ptr+1 ptr+2 ptr+3 ptr+4 ptr+5 ptr+6 ptr+7\n// Rhi Rlo Ghi Glo Bhi Blo Ahi Alo\n//\n// For example, the value wuffs_base__pixel_format 0x40000565 means BGR with no\n// alpha or padding, 5/6/5 bits for blue/green/red, interleaved 2 bytes per\n// pixel, laid out LSB-first in memory order:\n//\n// ptr+0........... ptr+1...." +
".......\n// MSB LSB MSB LSB\n// G₂G₁G₀B₄B₃B₂B₁B₀ R₄R₃R₂R₁R₀G₅G₄G₃\n//\n// On little-endian systems (but not big-endian), this Wuffs pixel format value\n// (0x40000565) corresponds to the Cairo library's CAIRO_FORMAT_RGB16_565, the\n// SDL2 (Simple DirectMedia Layer 2) library's SDL_PIXELFORMAT_RGB565 and the\n// Skia library's kRGB_565_SkColorType. Note BGR in Wuffs versus RGB in the\n// other libraries.\n//\n// Regardless of endianness, this Wuffs pixel format value (0x40000565)\n// corresponds to the V4L2 (Video For Linux 2) library's V4L2_PIX_FMT_RGB565\n// and the Wayland-DRM library's WL_DRM_FORMAT_RGB565.\n//\n// Different software libraries name their pixel formats (and especially their\n// channel order) either according to memory layout or as bits of a native\n// integer type like uint32_t. The two conventions differ because of a system's\n// endianness. As mentioned earlier, Wuffs pixel formats are always in memory\n// order. More detail of other software librarie" +
"s' naming conventions is in the\n// Pixel Format Guide at https://afrantzis.github.io/pixel-format-guide/\n//\n// Do not manipulate these bits directly; they are private implementation\n// details. Use methods such as wuffs_base__pixel_format__num_planes instead.\ntypedef uint32_t wuffs_base__pixel_format;\n\n// Common 8-bit-depth pixel formats. This list is not exhaustive; not all valid\n// wuffs_base__pixel_format values are present.\n\n#define WUFFS_BASE__PIXEL_FORMAT__INVALID ((wuffs_base__pixel_format)0x00000000)\n\n#define WUFFS_BASE__PIXEL_FORMAT__A ((wuffs_base__pixel_format)0x02000008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__Y ((wuffs_base__pixel_format)0x10000008)\n#define WUFFS_BASE__PIXEL_FORMAT__YA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x15000008)\n#define WUFFS_BASE__PIXEL_FORMAT__YA_PREMUL \\\n ((wuffs_base__pixel_format)0x16000008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__YCBCR ((wuffs_base__pixel_format)0x20020888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCBCRK ((wuffs_base__pixel_format)0x21038888)\n#define WUFFS_BASE__P" +
"IXEL_FORMAT__YCBCRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x25038888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCG ((wuffs_base__pixel_format)0x30020888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCGK ((wuffs_base__pixel_format)0x31038888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCGA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x35038888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x45040008)\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_PREMUL \\\n ((wuffs_base__pixel_format)0x46040008)\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_BINARY \\\n ((wuffs_base__pixel_format)0x47040008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__BGR ((wuffs_base__pixel_format)0x40000888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRX ((wuffs_base__pixel_format)0x41008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x45008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL \\\n ((wuffs_base__pixel_format)0x46008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_BINARY \\\n ((wuffs_base" +
"__pixel_format)0x47008888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__RGB ((wuffs_base__pixel_format)0x50000888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBX ((wuffs_base__pixel_format)0x51008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x55008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_PREMUL \\\n ((wuffs_base__pixel_format)0x56008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_BINARY \\\n ((wuffs_base__pixel_format)0x57008888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__CMY ((wuffs_base__pixel_format)0x60020888)\n#define WUFFS_BASE__PIXEL_FORMAT__CMYK ((wuffs_base__pixel_format)0x61038888)\n\nextern const uint32_t wuffs_base__pixel_format__bits_per_channel[16];\n\nstatic inline bool //\nwuffs_base__pixel_format__is_valid(wuffs_base__pixel_format f) {\n return f != 0;\n}\n\n// wuffs_base__pixel_format__bits_per_pixel returns the number of bits per\n// pixel for interleaved pixel formats, and returns 0 for planar pixel formats.\nstatic inline uint32_t //\nwuffs_base__pixel_format__bits_per_pixel(wuffs_base__" +
"pixel_format f) {\n if (((f >> 16) & 0x03) != 0) {\n return 0;\n }\n return wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 0)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 4)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 8)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 12)];\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_indexed(wuffs_base__pixel_format f) {\n return (f >> 18) & 0x01;\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_interleaved(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) == 0;\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_planar(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) != 0;\n}\n\nstatic inline uint32_t //\nwuffs_base__pixel_format__num_planes(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) + 1;\n}\n\n#define WUFFS_BASE__PIXEL_FORMAT__NUM_PLANES_MAX 4\n\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__INDEX_PLANE 0\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__COLOR_PLA" +
"NE 3\n\n" +
"// --------\n\n// wuffs_base__pixel_format encodes the format of the bytes that constitute an\n// image frame's pixel data.\n//\n// See https://github.com/google/wuffs/blob/master/doc/note/pixel-formats.md\n//\n// Do not manipulate its bits directly; they are private implementation\n// details. Use methods such as wuffs_base__pixel_format__num_planes instead.\ntypedef uint32_t wuffs_base__pixel_format;\n\n// Common 8-bit-depth pixel formats. This list is not exhaustive; not all valid\n// wuffs_base__pixel_format values are present.\n\n#define WUFFS_BASE__PIXEL_FORMAT__INVALID ((wuffs_base__pixel_format)0x00000000)\n\n#define WUFFS_BASE__PIXEL_FORMAT__A ((wuffs_base__pixel_format)0x02000008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__Y ((wuffs_base__pixel_format)0x10000008)\n#define WUFFS_BASE__PIXEL_FORMAT__YA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x15000008)\n#define WUFFS_BASE__PIXEL_FORMAT__YA_PREMUL \\\n ((wuffs_base__pixel_format)0x16000008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__YCBCR ((wuffs_base__pixel_format)0x20020888)\n#define" +
" WUFFS_BASE__PIXEL_FORMAT__YCBCRK ((wuffs_base__pixel_format)0x21038888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCBCRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x25038888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCG ((wuffs_base__pixel_format)0x30020888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCGK ((wuffs_base__pixel_format)0x31038888)\n#define WUFFS_BASE__PIXEL_FORMAT__YCOCGA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x35038888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x45040008)\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_PREMUL \\\n ((wuffs_base__pixel_format)0x46040008)\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__BGRA_BINARY \\\n ((wuffs_base__pixel_format)0x47040008)\n\n#define WUFFS_BASE__PIXEL_FORMAT__BGR ((wuffs_base__pixel_format)0x40000888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRX ((wuffs_base__pixel_format)0x41008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x45008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL \\\n ((wuffs" +
"_base__pixel_format)0x46008888)\n#define WUFFS_BASE__PIXEL_FORMAT__BGRA_BINARY \\\n ((wuffs_base__pixel_format)0x47008888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__RGB ((wuffs_base__pixel_format)0x50000888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBX ((wuffs_base__pixel_format)0x51008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_NONPREMUL \\\n ((wuffs_base__pixel_format)0x55008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_PREMUL \\\n ((wuffs_base__pixel_format)0x56008888)\n#define WUFFS_BASE__PIXEL_FORMAT__RGBA_BINARY \\\n ((wuffs_base__pixel_format)0x57008888)\n\n#define WUFFS_BASE__PIXEL_FORMAT__CMY ((wuffs_base__pixel_format)0x60020888)\n#define WUFFS_BASE__PIXEL_FORMAT__CMYK ((wuffs_base__pixel_format)0x61038888)\n\nextern const uint32_t wuffs_base__pixel_format__bits_per_channel[16];\n\nstatic inline bool //\nwuffs_base__pixel_format__is_valid(wuffs_base__pixel_format f) {\n return f != 0;\n}\n\n// wuffs_base__pixel_format__bits_per_pixel returns the number of bits per\n// pixel for interleaved pixel formats, and returns 0 for planar p" +
"ixel formats.\nstatic inline uint32_t //\nwuffs_base__pixel_format__bits_per_pixel(wuffs_base__pixel_format f) {\n if (((f >> 16) & 0x03) != 0) {\n return 0;\n }\n return wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 0)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 4)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 8)] +\n wuffs_base__pixel_format__bits_per_channel[0x0F & (f >> 12)];\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_indexed(wuffs_base__pixel_format f) {\n return (f >> 18) & 0x01;\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_interleaved(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) == 0;\n}\n\nstatic inline bool //\nwuffs_base__pixel_format__is_planar(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) != 0;\n}\n\nstatic inline uint32_t //\nwuffs_base__pixel_format__num_planes(wuffs_base__pixel_format f) {\n return ((f >> 16) & 0x03) + 1;\n}\n\n#define WUFFS_BASE__PIXEL_FORMAT__NUM_PLANES_MAX 4\n\n#define WUFFS_B" +
"ASE__PIXEL_FORMAT__INDEXED__INDEX_PLANE 0\n#define WUFFS_BASE__PIXEL_FORMAT__INDEXED__COLOR_PLANE 3\n\n" +
"" +
"// --------\n\n// wuffs_base__pixel_subsampling encodes the mapping of pixel space coordinates\n// (x, y) to pixel buffer indices (i, j). That mapping can differ for each\n// plane p. For a depth of 8 bits (1 byte), the p'th plane's sample starts at\n// (planes[p].ptr + (j * planes[p].stride) + i).\n//\n// For interleaved pixel formats, the mapping is trivial: i = x and j = y. For\n// planar pixel formats, the mapping can differ due to chroma subsampling. For\n// example, consider a three plane YCbCr pixel format with 4:2:2 subsampling.\n// For the luma (Y) channel, there is one sample for every pixel, but for the\n// chroma (Cb, Cr) channels, there is one sample for every two pixels: pairs of\n// horizontally adjacent pixels form one macropixel, i = x / 2 and j == y. In\n// general, for a given p:\n// - i = (x + bias_x) >> shift_x.\n// - j = (y + bias_y) >> shift_y.\n// where biases and shifts are in the range 0..3 and 0..2 respectively.\n//\n// In general, the biases will be zero after decoding an image. However, making\n//" +
" a sub-image may change the bias, since the (x, y) coordinates are relative\n// to the sub-image's top-left origin, but the backing pixel buffers were\n// created relative to the original image's origin.\n//\n// For each plane p, each of those four numbers (biases and shifts) are encoded\n// in two bits, which combine to form an 8 bit unsigned integer:\n//\n// e_p = (bias_x << 6) | (shift_x << 4) | (bias_y << 2) | (shift_y << 0)\n//\n// Those e_p values (e_0 for the first plane, e_1 for the second plane, etc)\n// combine to form a wuffs_base__pixel_subsampling value:\n//\n// pixsub = (e_3 << 24) | (e_2 << 16) | (e_1 << 8) | (e_0 << 0)\n//\n// Do not manipulate these bits directly; they are private implementation\n// details. Use methods such as wuffs_base__pixel_subsampling__bias_x instead.\ntypedef uint32_t wuffs_base__pixel_subsampling;\n\n#define WUFFS_BASE__PIXEL_SUBSAMPLING__NONE ((wuffs_base__pixel_subsampling)0)\n\n#define WUFFS_BASE__PIXEL_SUBSAMPLING__444 \\\n ((wuffs_base__pixel_subsampling)0x000000)\n#define WUFFS_BAS" +
+3 -113
View File
@@ -1419,121 +1419,11 @@ typedef uint32_t wuffs_base__color_u32_argb_premul;
// --------
// wuffs_base__pixel_format encodes the format of the bytes that constitute an
// image frame's pixel data. Its bits:
// - bit 31 is reserved.
// - bits 30 .. 28 encodes color (and channel order, in terms of memory).
// - bit 27 is reserved.
// - bits 26 .. 24 encodes transparency.
// - bits 23 .. 21 are reserved.
// - bit 20 indicates big-endian/MSB-first (as opposed to little/LSB).
// - bit 19 indicates floating point (as opposed to 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 17 .. 16 are the number of planes, minus 1. Zero means interleaved.
// - bits 15 .. 12 encodes the number of bits (depth) in the 3rd channel.
// - bits 11 .. 8 encodes the number of bits (depth) in the 2nd channel.
// - bits 7 .. 4 encodes the number of bits (depth) in the 1st channel.
// - bits 3 .. 0 encodes the number of bits (depth) in the 0th channel.
// image frame's pixel data.
//
// 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.
// See https://github.com/google/wuffs/blob/master/doc/note/pixel-formats.md
//
// 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 details, see the wuffs_base__pixel_subsampling type).
//
// 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:
// - 0 means A (Alpha).
// - 1 means Y or YA (Gray, Alpha).
// - 2 means YCbCr or YCbCrA (Luma, Chroma-blue, Chroma-red, Alpha).
// - 3 means YCoCg or YCoCgA (Luma, Chroma-orange, Chroma-green, Alpha).
// - 4 means BGR, BGRX or BGRA (Blue, Green, Red, X-padding or Alpha).
// - 5 means RGB, RGBX or RGBA (Red, Green, Blue, X-padding or Alpha).
// - 6 means CMY or 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.
//
// When the color field (3 bits) encodes multiple options, the transparency
// field (3 bits) distinguishes them:
// - 0 means fully opaque, no extra channels
// - 1 means fully opaque, one extra channel (X or K, padding or black).
// - 5 means one extra alpha channel, other channels are non-premultiplied.
// - 6 means one extra alpha channel, other channels are premultiplied.
// - 7 means one extra alpha channel, binary alpha.
// - all other values are reserved.
//
// 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, wuffs_base__pixel_format 0x5510BBBB is a natural format for
// decoding a PNG image - network byte order (also known as big-endian),
// interleaved, non-premultiplied alpha - that happens to be 16-bit-depth
// truecolor with alpha (RGBA). In memory order:
//
// ptr+0 ptr+1 ptr+2 ptr+3 ptr+4 ptr+5 ptr+6 ptr+7
// Rhi Rlo Ghi Glo Bhi Blo Ahi Alo
//
// 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 the
// Pixel Format Guide at https://afrantzis.github.io/pixel-format-guide/
//
// Do not manipulate these bits directly; they are private implementation
// Do not manipulate its bits directly; they are private implementation
// details. Use methods such as wuffs_base__pixel_format__num_planes instead.
typedef uint32_t wuffs_base__pixel_format;