mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
And some minor clean-ups. There should be no semantic changes to the documentation in this patch.
130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
# Pixel Subsampling
|
||
|
||
`wuffs_base__pixel_subsampling` is a `uint32_t` that encodes whether samples
|
||
cover one pixel or cover multiple pixels. RGBA or BGRA pixel formats are
|
||
typically one pixel per sample. For YCbCr pixel formats (i.e. the native
|
||
formats of JPEG and WebP lossy images), the luma channel (Y) is also typically
|
||
one pixel per sample but the chroma channels (Cb, Cr) are often 2 or 4 pixels
|
||
per sample. In JPEG terminology, 4:4:4, 4:2:2 or 4:2:0 subsampling correspond
|
||
to 1, 2 or 4 pixels per [chroma
|
||
sample](https://en.wikipedia.org/wiki/Chroma_subsampling).
|
||
|
||
Equivalently, `wuffs_base__pixel_subsampling` encodes the mapping of pixel
|
||
space coordinates `(x, y)` to sample space coordinates `(i, j)`, also known as
|
||
pixel buffer indices. That mapping can differ for each plane `p`. A Wuffs image
|
||
can have up to 4 planes or channels. For a depth of 8 bits (1 byte), the `p`'th
|
||
plane's sample starts at `(planes[p].ptr + (j * planes[p].stride) + i)`.
|
||
|
||
For interleaved pixel formats, which are always one pixel per sample, the
|
||
mapping is trivial: `i = x` and `j = y`. For planar pixel formats, the mapping
|
||
can differ due to chroma subsampling. For example, consider a three plane YCbCr
|
||
pixel format with 4:2:2 subsampling. For the luma (Y) channel, there is one
|
||
sample for every pixel, but for the chroma (Cb, Cr) channels, there is one
|
||
sample for every two pixels: pairs of horizontally adjacent pixels form one
|
||
macropixel, `i = x / 2` and `j == y`. In general, for a given `p`:
|
||
|
||
- `i = (x + bias_x) / denominator_x`.
|
||
- `j = (y + bias_y) / denominator_y`.
|
||
|
||
where biases and denominators are in the range `0 ..= 3` and `1 ..= 4`
|
||
respectively.
|
||
|
||
In general, the biases will be zero after decoding an image. However, making
|
||
a sub-image may change the bias, since the `(x, y)` coordinates are relative
|
||
to the sub-image's top-left origin, but the backing pixel buffers were
|
||
created relative to the original image's origin.
|
||
|
||
For example, consider a 10×3 image with what JPEG calls 4:1:1 subsampling,
|
||
where each Chroma sample covers a macropixel (a block of pixels) 4 wide and 1
|
||
high. For a Chroma channel, there are 30 pixels and 9 samples. `bias_x = 0` and
|
||
`denominator_x = 2`, so that the 6th pixel column (`x = 5`) maps to the 2nd
|
||
sample column (`i = 1`).
|
||
|
||
```
|
||
Pixel space:
|
||
+---------------------------------------+
|
||
|l00 l01 l02 l03 m04 m05 m06 m07 n08 n09|
|
||
| |
|
||
|p10 p11 p12 p13 q14 q15 q16 q17 r18 r19|
|
||
| +-----------+ |
|
||
|t21 t21 t22|t23 u24 u25|u26 u27 v28 v29|
|
||
+-----------+-----------+---------------+
|
||
|
||
Chroma sample space:
|
||
+-----+
|
||
|l m n|
|
||
| |
|
||
|p q r|
|
||
| |
|
||
|t u v|
|
||
+-----+
|
||
```
|
||
|
||
Now consider the 3×1 sub-image shown above. Even though its pixel width (3) is
|
||
less than the macropixel width (4 columns per sample), as that sub-image shares
|
||
the sample buffer with its containing image, it still straddles 2 sample
|
||
columns (`t` and `u`). `denominator_x = 2`, the same as before, but now `bias_x
|
||
= 3`.
|
||
|
||
```
|
||
Pixel space:
|
||
+-----------+
|
||
|t23 u24 u25|
|
||
+-----------+
|
||
|
||
Chroma sample space:
|
||
+---+
|
||
|t u|
|
||
+---+
|
||
```
|
||
|
||
|
||
## Bit Packing
|
||
|
||
For each plane `p`, the adjusted denominator is defined to be one less than the
|
||
denominator. The plane's four numbers (two biases and two adjusted
|
||
denominators) are each in the range `0 ..= 3`, and are each encodable in two
|
||
bits. Four groups of two bits combine to form an 8 bit unsigned integer:
|
||
|
||
```
|
||
e_p = (bias_x << 6) | (adj_denom_x << 4) | (bias_y << 2) | (adj_denom_y << 0)
|
||
```
|
||
|
||
|
||
Those `e_p` values (`e_0` for the first plane, `e_1` for the second plane, etc)
|
||
combine to form a `wuffs_base__pixel_subsampling` value:
|
||
|
||
```
|
||
pixsub = (e_3 << 24) | (e_2 << 16) | (e_1 << 8) | (e_0 << 0)
|
||
```
|
||
|
||
For example, visualizing 4:2:2 YCbCr (with no bias):
|
||
|
||
```
|
||
Pixel space:
|
||
+-------------------+
|
||
|l00 l01 m02 m03 n04|
|
||
| |
|
||
|p10 p11 q12 q13 r14|
|
||
+-------------------+
|
||
|
||
Chroma sample space:
|
||
+-----+
|
||
|l m n|
|
||
| |
|
||
|p q r|
|
||
+-----+
|
||
```
|
||
|
||
This corresponds to a `denominator_x` of 1, 2 and 2 for the three planes (Y,
|
||
Cb, Cr) and a `denominator_y` of 1, 1 and 1. The `uint32_t` encoding is
|
||
`0x101000`.
|
||
|
||
|
||
## API Stability
|
||
|
||
The `wuffs_base__pixel_subsampling` 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_subsampling__bias_x` instead.
|