Re-write bit ranges in the docs

This commit is contained in:
Nigel Tao committed 2020-04-09 22:29:45 +10:00
1 parent 496e88b6c5
commit 6612d90ca2
3 files changed
+34 -34

No files matched your search

+4 -4
View File
@@ -33,7 +33,7 @@ Base38 is a tighter encoding than FourCC, fitting four characters into 21 bits
instead of 32 bits. This is achieved by using a smaller alphabet of 38 possible
values (space, 0-9, ? or a-z), so that it cannot distinguish between e.g. an
upper case 'X' and a lower case 'x'. There's also the happy coincidence that
`38 ** 4` is slightly smaller than `2 ** 21`.
`38 ** 4`, `2085136`, is slightly smaller than `2 ** 21`, `2097152`.
The base38 encoding of `"JPEG"` is `0x122FF6`, which is `1191926`, which is
`((21 * (38 ** 3)) + (27 * (38 ** 2)) + (16 * (38 ** 1)) + (18 * (38 ** 0)))`.
@@ -45,9 +45,9 @@ different values in their own namespace, without conflicting with other
packages (assuming that there aren't e.g. two `"JPEG"` Wuffs packages in the
same library). The conventional `uint32_t` packing is:
- Bit 31 is reserved (zero).
- Bits 30 .. 10 are the base38 value, shifted by 10.
- Bits 9 .. 0 are the enumeration value.
- Bit `31` (1 bit) is reserved (zero).
- Bits `10 ..= 30` (21 bits) are the base38 value, shifted by 10.
- Bits `0 ..= 9` (10 bits) are the enumeration value.
For example, [quirk values](/doc/note/quirks.md) use this `((base38 << 10) |
enumeration)` scheme.
+19 -19
View File
@@ -3,27 +3,27 @@
`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.
- Bit `31` is reserved.
- Bits `28 ..= 30` encodes color (and channel order, in terms of memory).
- Bit `27` is reserved.
- Bits `24 ..= 26` 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 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.
channels. Similarly, bits `4 ..= 15` are unused (and should be zero) if bits
`24 ..= 31` (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
@@ -77,7 +77,7 @@ 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.
- 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.
+11 -11
View File
@@ -36,9 +36,9 @@ string are treated differently when reconstructing the decoded string:
A token is just a `uint64_t`. The broad divisions are:
- Bits 63 .. 17 (47 bits) is the value.
- Bits 16 .. 16 (1 bit) is the `continued` bit.
- Bits 15 .. 0 (16 bits) is the length.
- Bits `17 ..= 63` (47 bits) are the value.
- Bit `16` (1 bit) is the `continued` bit.
- Bits `0 ..= 15` (16 bits) are the length.
The `continued` bit is whether that the token chain for this token also
contains the next token. The final token in a token chain, including
@@ -56,12 +56,12 @@ stand-alone tokens, will have the `continued` bit set to zero.
The value bits can be sub-divided in multiple ways. First, the high bit:
- Bits 63 .. 63 (1 bit) denote an extended (1) or simple (0) token.
- Bit `63` (1 bit) denotes an extended (1) or simple (0) token.
### Extended Tokens
- Bits 62 .. 17 (46 bits) is the bitwise-not (~) of the `value_extension`.
- Bits `17 ..= 62` (46 bits) are the bitwise-not (~) of the `value_extension`.
Extended tokens are typically part of a multi-token chain whose first token is
a simple token that provides the semantics for each `value_extension`.
@@ -69,8 +69,8 @@ a simple token that provides the semantics for each `value_extension`.
### Simple Tokens
- Bits 62 .. 42 (21 bits) is the `value_major`.
- Bits 41 .. 17 (25 bits) is the `value_minor`.
- Bits `42 ..= 62` (21 bits) are the `value_major`.
- Bits `17 ..= 41` (25 bits) are the `value_minor`.
The `value_major` is a 21-bit [Base38](doc/note/base38-and-fourcc.md) number.
For example, an HTML tokenizer might produce a combination of "base" tokens
@@ -87,8 +87,8 @@ tokenizer's package assigns to it.
A zero `value_major` is reserved for Wuffs' built-in "base" package. The
`value_minor` is further sub-divided:
- Bits 41 .. 38 (4 bits) is the `VBC` (`value_base_category`).
- Bits 37 .. 17 (21 bits) is the `VBD` (`value_base_detail`).
- Bits `38 ..= 41` (4 bits) are the `VBC` (`value_base_category`).
- Bits `17 ..= 37` (21 bits) are the `VBD` (`value_base_detail`).
The high 47 bits (bits 63 .. 17) only have `VBC` and `VBD` semantics when the
high 22 bits (the `extended` and `value_major` parts) are all zero. An
@@ -132,8 +132,8 @@ Wuffs code. Instead, Wuffs just outputs tokens and tokens are just `uint64_t`s.
The [example/jsonfindptrs](/example/jsonfindptrs/jsonfindptrs.cc) program
demonstrates creating a traditional DOM-like node tree from a SAX-like token
stream. The [example/jsonptr](/example/jsonptr/jsonptr.cc) program demonstrates
a different, lower-level approach that works directly on tokens, where the
entire program (not just the Wuffs library) never calls `malloc`.
a lower-level approach that works directly on tokens, where the entire program
(not just the Wuffs library) never calls `malloc`.
## Example Token Stream