mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
Re-write bit ranges in the docs
This commit is contained in:
1 parent
496e88b6c5
commit
6612d90ca2
3 files changed
+34
-34
No files matched your search
@@ -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
@@ -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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user