mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-19 00:38:14 +01:00
Add doc/note/pixel-formats.md
This commit is contained in:
1 parent
a4f7761182
commit
5362ca7573
7 files changed
+142
-240
No files matched your search
@@ -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.
|
||||
@@ -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
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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
@@ -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" +
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
Reference in new issue
Block a user