@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/bitstream/BitReader.js

@@ -0,0 +1,391 @@
+import { floor_log2 } from "../av1/util/floor_log2.js";
+
+/**
+ * Maximum number of bytes a `leb128()` may occupy, from the conformance requirement that the
+ * continuation bit of the eighth byte is zero.
+ * @type {number}
+ */
+const LEB128_MAX_BYTES = 8;
+
+/**
+ * MSB-first bit cursor over a byte range, carrying the AV1 bitstream descriptors.
+ *
+ * This is the counterpart to {@link BitWriter}. It reads out of an existing `Uint8Array` without
+ * copying, so a reader can be pointed at a slice of a much larger file cheaply. Bounds are checked
+ * on every read: a truncated or malformed stream throws rather than reading zeroes off the end of
+ * the buffer and producing a plausible-looking but wrong header.
+ *
+ * It is a struct with methods rather than a struct plus free functions because that is the shape
+ * meep already uses for stream cursors ({@link BinaryBuffer}), and because a bit cursor's whole
+ * purpose is the coupling of the position to the buffer.
+ *
+ * Not used for tile data: arithmetic-coded payloads are read by the symbol decoder straight from
+ * the byte array, so this class is never on a per-sample path.
+ *
+ * @see AV1 spec 4.10 "Descriptors"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BitReader {
+    /**
+     * Bytes being read. Not owned.
+     * @type {Uint8Array}
+     */
+    data = null;
+
+    /**
+     * Index into {@link data} of the byte holding the next bit.
+     * @type {number}
+     */
+    byte_position = 0;
+
+    /**
+     * Index of the next bit within the byte at {@link byte_position}, `0` being the most
+     * significant bit.
+     * @type {number}
+     */
+    bit_position = 0;
+
+    /**
+     * Index into {@link data} one past the last readable byte.
+     * @type {number}
+     */
+    end = 0;
+
+    /**
+     * Index into {@link data} of the first readable byte. Kept so {@link position_in_bits} can be
+     * reported relative to the start of the range rather than the start of the array.
+     * @type {number}
+     */
+    start = 0;
+
+    /**
+     * Number of bytes consumed by the most recent {@link leb128} call. The AV1 syntax refers to
+     * this as `Leb128Bytes` and several OBU size computations need it.
+     * @type {number}
+     */
+    leb128_bytes = 0;
+
+    /**
+     * Point the reader at a byte range. Cheap: no allocation, no copy, so a reader can be reused
+     * across many payloads.
+     *
+     * @param {Uint8Array} data
+     * @param {number} [byte_offset] offset within `data` to start at
+     * @param {number} [byte_length] number of bytes readable from `byte_offset`
+     * @returns {BitReader} this
+     */
+    init(data, byte_offset = 0, byte_length = data.length - byte_offset) {
+        if (byte_offset < 0 || byte_length < 0 || byte_offset + byte_length > data.length) {
+            throw new Error(`BitReader range [${byte_offset}, ${byte_offset + byte_length}) is outside the ${data.length} byte buffer`);
+        }
+
+        this.data = data;
+        this.start = byte_offset;
+        this.byte_position = byte_offset;
+        this.bit_position = 0;
+        this.end = byte_offset + byte_length;
+        this.leb128_bytes = 0;
+
+        return this;
+    }
+
+    /**
+     * Bits consumed since {@link init}.
+     * @returns {number}
+     */
+    get position_in_bits() {
+        return (this.byte_position - this.start) * 8 + this.bit_position;
+    }
+
+    /**
+     * Bits left before the end of the range.
+     * @returns {number}
+     */
+    get bits_remaining() {
+        return (this.end - this.byte_position) * 8 - this.bit_position;
+    }
+
+    /**
+     * Whether the cursor sits on a byte boundary. Several descriptors are only legal there.
+     * @returns {boolean}
+     */
+    get is_byte_aligned() {
+        return this.bit_position === 0;
+    }
+
+    /**
+     * `f(1)`. The single primitive every other descriptor is built from.
+     * @returns {number} `0` or `1`
+     */
+    read_bit() {
+        if (this.byte_position >= this.end) {
+            throw new Error("BitReader read past the end of the bitstream");
+        }
+
+        const bit = (this.data[this.byte_position] >> (7 - this.bit_position)) & 1;
+
+        if (this.bit_position === 7) {
+            this.bit_position = 0;
+            this.byte_position++;
+        } else {
+            this.bit_position++;
+        }
+
+        return bit;
+    }
+
+    /**
+     * `f(n)`: unsigned `n`-bit number, most significant bit first.
+     *
+     * Accumulates with multiplication rather than `<<` so that `n === 32` does not overflow into a
+     * negative number. Bits are taken a byte at a time rather than one at a time, which matters
+     * because sequence headers read a lot of 8- and 16-bit fields.
+     *
+     * @param {number} n `0 .. 32`
+     * @returns {number}
+     * @see AV1 spec 8.1 "Parsing process for f(n)"
+     */
+    f(n) {
+        if (n === 0) {
+            return 0;
+        }
+
+        if (n < 0 || n > 32) {
+            throw new Error(`f(n) supports 0..32 bits, got ${n}`);
+        }
+
+        if (this.bits_remaining < n) {
+            throw new Error(`BitReader needs ${n} bits but only ${this.bits_remaining} remain`);
+        }
+
+        const data = this.data;
+
+        let result = 0;
+        let remaining = n;
+        let byte_position = this.byte_position;
+        let bit_position = this.bit_position;
+
+        while (remaining > 0) {
+            const available_in_byte = 8 - bit_position;
+            const take = remaining < available_in_byte ? remaining : available_in_byte;
+
+            const chunk = (data[byte_position] >> (available_in_byte - take)) & ((1 << take) - 1);
+
+            result = result * (1 << take) + chunk;
+
+            bit_position += take;
+
+            if (bit_position === 8) {
+                bit_position = 0;
+                byte_position++;
+            }
+
+            remaining -= take;
+        }
+
+        this.byte_position = byte_position;
+        this.bit_position = bit_position;
+
+        return result;
+    }
+
+    /**
+     * `su(n)`: signed integer whose bottom `n` bits appear in the bitstream.
+     *
+     * @param {number} n `1 .. 32`
+     * @returns {number}
+     * @see AV1 spec 4.10.6 "su(n)"
+     */
+    su(n) {
+        const value = this.f(n);
+        const sign_mask = 1 << (n - 1);
+
+        return (value & sign_mask) !== 0 ? value - 2 * sign_mask : value;
+    }
+
+    /**
+     * `ns(n)`: unsigned integer in `0 .. n - 1`, coded with one bit fewer over the lower part of
+     * the range.
+     *
+     * @param {number} n number of distinct values, `>= 1`
+     * @returns {number}
+     * @see AV1 spec 4.10.7 "ns(n)"
+     */
+    ns(n) {
+        const w = floor_log2(n) + 1;
+        const m = (1 << w) - n;
+
+        const v = this.f(w - 1);
+
+        if (v < m) {
+            return v;
+        }
+
+        return (v << 1) - m + this.read_bit();
+    }
+
+    /**
+     * `uvlc()`: Exp-Golomb-style variable length unsigned number.
+     *
+     * A run of 32 or more leading zeroes is the specification's encoding of `(1 << 32) - 1` and is
+     * returned as such rather than treated as corruption. The leading-zero count is still bounded
+     * by the buffer, so a stream of zero bytes terminates on the range check in {@link read_bit}.
+     *
+     * @returns {number}
+     * @see AV1 spec 4.10.3 "uvlc()"
+     */
+    uvlc() {
+        let leading_zeros = 0;
+
+        while (this.read_bit() === 0) {
+            leading_zeros++;
+        }
+
+        // the specification counts every leading zero before testing the limit, so an over-long run
+        // consumes its terminating one bit too. Stopping early would leave the cursor a bit short
+        // and desynchronise everything after it.
+        if (leading_zeros >= 32) {
+            return 4294967295;
+        }
+
+        return this.f(leading_zeros) + (2 ** leading_zeros) - 1;
+    }
+
+    /**
+     * `le(n)`: unsigned little-endian `n`-byte number. Only legal on a byte boundary.
+     *
+     * @param {number} n number of bytes
+     * @returns {number}
+     * @see AV1 spec 4.10.4 "le(n)"
+     */
+    le(n) {
+        if (!this.is_byte_aligned) {
+            throw new Error("le(n) requires a byte aligned bitstream position");
+        }
+
+        // above six bytes the accumulator would leave the range where a float64 represents every
+        // integer, and would start rounding silently. Nothing in AV1 asks for more than four.
+        if (n < 0 || n > 6) {
+            throw new Error(`le(n) supports 0..6 bytes, got ${n}`);
+        }
+
+        let t = 0;
+
+        for (let i = 0; i < n; i++) {
+            t += this.f(8) * (2 ** (i * 8));
+        }
+
+        return t;
+    }
+
+    /**
+     * `leb128()`: unsigned integer in a variable number of little-endian 7-bit groups. Only legal
+     * on a byte boundary. Sets {@link leb128_bytes}.
+     *
+     * Accumulates with multiplication because a conforming eight-byte encoding carries 56 bits of
+     * payload; the value itself is required to fit in 32 bits, which is checked, but the shift
+     * would have wrapped before the check could run.
+     *
+     * @returns {number}
+     * @see AV1 spec 4.10.5 "leb128()"
+     */
+    leb128() {
+        if (!this.is_byte_aligned) {
+            throw new Error("leb128() requires a byte aligned bitstream position");
+        }
+
+        let value = 0;
+
+        this.leb128_bytes = 0;
+
+        for (let i = 0; i < LEB128_MAX_BYTES; i++) {
+            const leb128_byte = this.f(8);
+
+            value += (leb128_byte & 0x7f) * (2 ** (i * 7));
+
+            this.leb128_bytes++;
+
+            // checked inside the loop rather than after it: a conforming eight byte encoding
+            // carries 56 bits, which is past the point where the accumulator stops representing
+            // every integer exactly, so an out-of-range value has to be caught while it is still
+            // being built rather than inspected at the end.
+            if (value > 4294967295) {
+                throw new Error(`leb128() value exceeds the conformance limit of 2^32 - 1`);
+            }
+
+            if ((leb128_byte & 0x80) === 0) {
+                break;
+            }
+
+            if (i === LEB128_MAX_BYTES - 1) {
+                throw new Error("leb128() did not terminate within 8 bytes");
+            }
+        }
+
+        return value;
+    }
+
+    /**
+     * Skip forward to the next byte boundary, requiring the skipped bits to be zero as the
+     * specification's `byte_alignment()` does.
+     *
+     * @see AV1 spec 5.3.5 "Byte alignment syntax"
+     */
+    byte_alignment() {
+        while (!this.is_byte_aligned) {
+            if (this.read_bit() !== 0) {
+                throw new Error("byte_alignment() found a non-zero padding bit");
+            }
+        }
+    }
+
+    /**
+     * Consume the `trailing_one_bit` plus zero padding that terminates an OBU payload.
+     *
+     * @see AV1 spec 5.3.4 "Trailing bits syntax"
+     */
+    trailing_bits() {
+        if (this.read_bit() !== 1) {
+            throw new Error("trailing_bits() expected a trailing one bit");
+        }
+
+        while (!this.is_byte_aligned) {
+            if (this.read_bit() !== 0) {
+                throw new Error("trailing_bits() found a non-zero padding bit");
+            }
+        }
+    }
+
+    /**
+     * Advance to the next byte boundary without checking what the skipped bits contain.
+     *
+     * The specification says the padding "shall be equal to 0", and {@link byte_alignment} enforces
+     * that. A decoder cannot afford to: libaom rounds a frame header up to a whole byte by simply
+     * advancing its write cursor, so inside an OBU_FRAME those bits are whatever was already in its
+     * output buffer. Refusing such a file would reject a large share of the AVIFs in existence over
+     * bits nothing reads.
+     */
+    skip_to_byte_boundary() {
+        while (!this.is_byte_aligned) {
+            this.read_bit();
+        }
+    }
+
+    /**
+     * Advance the cursor by whole bytes without reading. Requires byte alignment.
+     * @param {number} count
+     */
+    skip_bytes(count) {
+        if (!this.is_byte_aligned) {
+            throw new Error("skip_bytes() requires a byte aligned bitstream position");
+        }
+
+        if (count < 0 || this.byte_position + count > this.end) {
+            throw new Error(`BitReader cannot skip ${count} bytes, only ${this.end - this.byte_position} remain`);
+        }
+
+        this.byte_position += count;
+    }
+}

package/src/avif/native/bitstream/BitWriter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * MSB-first bit sink, the inverse of {@link BitReader}.
+ *
+ * Grows its own backing array. Used for OBU headers and for synthesising streams in tests; tile
+ * payloads are produced by the symbol writer, which emits bytes directly.
+ *
+ * @see AV1 spec 4.10 "Descriptors"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BitWriter {
+    /**
+     * Bytes written so far, plus unused capacity beyond {@link byte_position}.
+     * @type {Uint8Array}
+     */
+    data: Uint8Array;
+    /**
+     * Index of the byte currently being filled.
+     * @type {number}
+     */
+    byte_position: number;
+    /**
+     * Number of bits already placed in the byte at {@link byte_position}, counting from the most
+     * significant.
+     * @type {number}
+     */
+    bit_position: number;
+    /**
+     * Discard everything written and start again, keeping the allocated buffer. Lets one writer
+     * serve many payloads without allocating.
+     * @returns {BitWriter} this
+     */
+    reset(): BitWriter;
+    /**
+     * Bits written since the last {@link reset}.
+     * @returns {number}
+     */
+    get position_in_bits(): number;
+    /**
+     * @returns {boolean}
+     */
+    get is_byte_aligned(): boolean;
+    /**
+     * Write a single bit.
+     * @param {number} bit `0` or `1`
+     */
+    write_bit(bit: number): void;
+    /**
+     * `f(n)`: unsigned `n`-bit number, most significant bit first.
+     *
+     * Emits a byte at a time where alignment allows. `value` is decomposed with division rather
+     * than shifts so that a 32-bit value does not lose its top bit to sign extension.
+     *
+     * @param {number} n `0 .. 32`
+     * @param {number} value
+     */
+    f(n: number, value: number): void;
+    /**
+     * `su(n)`: signed integer, bottom `n` bits written.
+     * @param {number} n `1 .. 32`
+     * @param {number} value
+     */
+    su(n: number, value: number): void;
+    /**
+     * `ns(n)`: unsigned integer in `0 .. n - 1`.
+     * @param {number} n number of distinct values, `>= 1`
+     * @param {number} value
+     */
+    ns(n: number, value: number): void;
+    /**
+     * `uvlc()`: variable length unsigned number.
+     * @param {number} value `0 .. 2^32 - 1`
+     */
+    uvlc(value: number): void;
+    /**
+     * `le(n)`: unsigned little-endian `n`-byte number. Requires byte alignment.
+     * @param {number} n `0 .. 6`
+     * @param {number} value
+     */
+    le(n: number, value: number): void;
+    /**
+     * `leb128()`: variable-length little-endian unsigned integer. Requires byte alignment.
+     *
+     * `fixed_size` pads the encoding out to a chosen byte count with redundant continuation bits.
+     * The specification explicitly allows this so a writer can reserve space for a length it does
+     * not know yet and patch it later, which is exactly how OBU sizes are emitted.
+     *
+     * @param {number} value `0 .. 2^32 - 1`
+     * @param {number} [fixed_size] number of bytes to occupy, `1 .. 8`
+     */
+    leb128(value: number, fixed_size?: number): void;
+    /**
+     * Pad to the next byte boundary with zero bits.
+     * @see AV1 spec 5.3.5 "Byte alignment syntax"
+     */
+    byte_alignment(): void;
+    /**
+     * Write the `trailing_one_bit` and zero padding that terminates an OBU payload.
+     * @see AV1 spec 5.3.4 "Trailing bits syntax"
+     */
+    trailing_bits(): void;
+    /**
+     * Copy whole bytes in. Requires byte alignment.
+     * @param {Uint8Array} bytes
+     * @param {number} [offset]
+     * @param {number} [length]
+     */
+    write_bytes(bytes: Uint8Array, offset?: number, length?: number): void;
+    /**
+     * The bytes written so far. A partially filled trailing byte is included, with its unwritten
+     * low bits zero.
+     *
+     * Returns a view onto the writer's own buffer, so it is only valid until the next write. Copy
+     * it if it needs to outlive the writer's next use.
+     *
+     * @returns {Uint8Array}
+     */
+    to_bytes(): Uint8Array;
+    #private;
+}
+//# sourceMappingURL=BitWriter.d.ts.map

package/src/avif/native/bitstream/BitWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BitWriter.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/bitstream/BitWriter.js"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,MAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFa,SAAS,CAQrB;IAED;;;OAGG;IACH,+BAEC;IAED;;OAEG;IACH,+BAEC;IAwBD;;;OAGG;IACH,eAFW,MAAM,QAmBhB;IAED;;;;;;;;OAQG;IACH,KAHW,MAAM,SACN,MAAM,QA0ChB;IAED;;;;OAIG;IACH,MAHW,MAAM,SACN,MAAM,QAUhB;IAED;;;;OAIG;IACH,MAHW,MAAM,SACN,MAAM,QAoBhB;IAED;;;OAGG;IACH,YAFW,MAAM,QAuBhB;IAED;;;;OAIG;IACH,MAHW,MAAM,SACN,MAAM,QAkBhB;IAED;;;;;;;;;OASG;IACH,cAHW,MAAM,eACN,MAAM,QAiChB;IAED;;;OAGG;IACH,uBAIC;IAED;;;OAGG;IACH,sBAIC;IAED;;;;;OAKG;IACH,mBAJW,UAAU,WACV,MAAM,WACN,MAAM,QAahB;IAED;;;;;;;;OAQG;IACH,YAFa,UAAU,CAMtB;;CACJ"}