From 6612d90ca2313e394caf6ec466dcc37d07cf41fe Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 9 Apr 2020 22:29:45 +1000 Subject: [PATCH] Re-write bit ranges in the docs --- doc/note/base38-and-fourcc.md | 8 ++++---- doc/note/pixel-formats.md | 38 +++++++++++++++++------------------ doc/note/tokens.md | 22 ++++++++++---------- 3 files changed, 34 insertions(+), 34 deletions(-) diff --git a/doc/note/base38-and-fourcc.md b/doc/note/base38-and-fourcc.md index dc3c83f1..dc513516 100644 --- a/doc/note/base38-and-fourcc.md +++ b/doc/note/base38-and-fourcc.md @@ -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. diff --git a/doc/note/pixel-formats.md b/doc/note/pixel-formats.md index bc6f26a7..9eca00eb 100644 --- a/doc/note/pixel-formats.md +++ b/doc/note/pixel-formats.md @@ -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. diff --git a/doc/note/tokens.md b/doc/note/tokens.md index 5577f2da..5e26d27d 100644 --- a/doc/note/tokens.md +++ b/doc/note/tokens.md @@ -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