@woosh/meep-engine 3.17.2 → 3.18.0

package/src/core/binary/meshopt/meshopt_encode_index_sequence.js

@@ -0,0 +1,146 @@
+import { assert } from "../../assert.js";
+import { MESHOPT_UINT_VAR_MAX_BYTES, meshopt_write_uint_var } from "./meshopt_write_uint_var.js";
+
+/**
+ * Header nibble every index-sequence stream starts with; the low nibble is the codec version.
+ * @type {number}
+ */
+const HEADER = 0xd0;
+
+/**
+ * Reserved bytes that close the stream. They are zero, and their only job is to be found.
+ * @type {number}
+ */
+const TAIL_SIZE = 4;
+
+/**
+ * How far one index may sit from the baseline it is coded against.
+ *
+ * The stored value spends its low bit on which baseline, leaving thirty-one for the zigzag, whose
+ * own low bit is the sign — so the delta has thirty bits and a sign, and half of the 32-bit index
+ * range is out of reach of any one step. Nothing that indexes a real vertex buffer comes near it,
+ * but a stream that crossed it would decode to different indices rather than fail, so it is checked.
+ *
+ * @type {number}
+ */
+export const MESHOPT_INDEX_SEQUENCE_MAX_DELTA = 1 << 30;
+
+/**
+ * Encode an index stream of no particular topology — the `"INDICES"` mode of both meshopt
+ * extensions, and the inverse of {@link meshopt_decode_index_sequence}.
+ *
+ * Each index is a zigzag delta against one of *two* running baselines, and which one is the low bit
+ * of the stored value. Two rather than one is what lets two independently monotonic runs be spliced
+ * together and still pay one small delta per index — a triangle strip's own indices against one, a
+ * degenerate seam against the other — so the choice is where the compression is, and it is made per
+ * index by pricing both:
+ *
+ * - the baseline whose delta encodes in fewer bytes wins;
+ * - a tie goes to the smaller delta, which leaves both baselines nearer the runs they are tracking;
+ * - a tie in that too goes to baseline 0, which keeps baseline 1 free for a run that has not
+ *   started yet.
+ *
+ * Greedy, and deliberately so: a baseline that is cheap now is cheap because it is near, and near is
+ * what makes it cheap again next time.
+ *
+ * A baseline both of whose deltas are further away than {@link MESHOPT_INDEX_SEQUENCE_MAX_DELTA} is
+ * not a choice at all, and an index that is out of reach of both is refused.
+ *
+ * @see https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression
+ *
+ * @param {ArrayLike<number>} indices unsigned 32-bit
+ * @param {Object} [options]
+ * @param {number} [options.version] 0 or 1, defaulting to 1 — the two are the same bitstream, and
+ *   the nibble is there for a codec change that has not happened
+ * @returns {Uint8Array} the whole compressed stream, reserved tail included
+ * @throws {Error} on an index further than {@link MESHOPT_INDEX_SEQUENCE_MAX_DELTA} from both
+ *   baselines, which the format has no way to write down
+ */
+export function meshopt_encode_index_sequence(indices, options = {}) {
+    const version = options.version ?? 1;
+
+    assert.isOneOf(version, [0, 1], 'version');
+
+    const count = indices.length;
+
+    const destination = new Uint8Array(1 + count * MESHOPT_UINT_VAR_MAX_BYTES + TAIL_SIZE);
+
+    destination[0] = HEADER | version;
+
+    let offset = 1;
+
+    let last_0 = 0;
+    let last_1 = 0;
+
+    for (let i = 0; i < count; i++) {
+        const index = indices[i] >>> 0;
+
+        // the deltas as signed 32-bit, which is the arithmetic the decoder undoes them with
+        const delta_0 = (index - last_0) | 0;
+        const delta_1 = (index - last_1) | 0;
+
+        const value_0 = (((delta_0 << 1) ^ (delta_0 >> 31)) << 1) >>> 0;
+        const value_1 = ((((delta_1 << 1) ^ (delta_1 >> 31)) << 1) | 1) >>> 0;
+
+        const fits_0 = in_reach(delta_0);
+        const fits_1 = in_reach(delta_1);
+
+        const size_0 = uint_var_size(value_0);
+        const size_1 = uint_var_size(value_1);
+
+        const take_1 = fits_1 && (
+            !fits_0
+            || size_1 < size_0
+            || (size_1 === size_0 && Math.abs(delta_1) < Math.abs(delta_0))
+        );
+
+        if (!take_1 && !fits_0) {
+            throw new Error(
+                `meshopt index ${i} (=${index}) is further than ${MESHOPT_INDEX_SEQUENCE_MAX_DELTA}`
+                + ` from both baselines (${last_0}, ${last_1}), which an index sequence cannot express`
+            );
+        }
+
+        if (take_1) {
+            offset = meshopt_write_uint_var(destination, offset, value_1);
+            last_1 = index;
+        } else {
+            offset = meshopt_write_uint_var(destination, offset, value_0);
+            last_0 = index;
+        }
+    }
+
+    return destination.slice(0, offset + TAIL_SIZE);
+}
+
+/**
+ * @param {number} delta signed 32-bit
+ * @returns {boolean} whether one step can carry it
+ */
+function in_reach(delta) {
+    return delta >= -MESHOPT_INDEX_SEQUENCE_MAX_DELTA && delta < MESHOPT_INDEX_SEQUENCE_MAX_DELTA;
+}
+
+/**
+ * @param {number} value unsigned 32-bit
+ * @returns {number} what {@link meshopt_write_uint_var} would spend on it
+ */
+function uint_var_size(value) {
+    if (value < 0x80) {
+        return 1;
+    }
+
+    if (value < 0x4000) {
+        return 2;
+    }
+
+    if (value < 0x200000) {
+        return 3;
+    }
+
+    if (value < 0x10000000) {
+        return 4;
+    }
+
+    return MESHOPT_UINT_VAR_MAX_BYTES;
+}

package/src/core/binary/meshopt/meshopt_encode_vertex_buffer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Encode an attribute stream — the `"ATTRIBUTES"` mode of both meshopt extensions, and the inverse
+ * of {@link meshopt_decode_vertex_buffer}.
+ *
+ * Elements are delta-coded against the element before them, byte position by byte position. What
+ * the encoder gets to decide, and does:
+ *
+ * - **per group of sixteen deltas**, the width they are packed at, out of the four the block's
+ *   control mode admits — including "all zero", which stores nothing;
+ * - **per byte position** (version 1), whether the groups carry a header at all: a position that
+ *   never changes costs nothing, and one that is pure noise skips the header and is written
+ *   verbatim rather than paying two bits a group to be told so;
+ * - **per channel of four byte positions** (version 1), whether its deltas are 8-bit, 16-bit, or a
+ *   rotated 32-bit exclusive-or — see {@link choose_channel_mode}.
+ *
+ * Every one of those is priced against the alternatives on the data in hand rather than guessed at,
+ * so the output is never larger than the verbatim form and is usually a fraction of it.
+ *
+ * Version 0 is what `EXT_meshopt_compression` admits and is the default. Version 1 is
+ * `KHR_meshopt_compression` only, and buys the last two decisions above.
+ *
+ * @see https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression
+ *
+ * @param {Uint8Array} source `count * byte_stride` bytes
+ * @param {number} count elements
+ * @param {number} byte_stride divisible by 4, at most 256
+ * @param {Object} [options]
+ * @param {number} [options.version] 0 or 1, defaulting to 0
+ * @param {number[]|Uint8Array} [options.channel_modes] one mode byte per channel — low nibble the
+ *   mode, high nibble the rotation — imposed rather than chosen. Version 1 only, and the caller
+ *   owns the consequences: a mode that suits the data less well than the one this would have picked
+ *   makes a larger stream, not a wrong one.
+ * @returns {Uint8Array} the whole compressed stream, tail included
+ * @throws {Error} if the arguments do not describe an encodable buffer
+ */
+export function meshopt_encode_vertex_buffer(source: Uint8Array, count: number, byte_stride: number, options?: {
+    version?: number;
+    channel_modes?: number[] | Uint8Array;
+}): Uint8Array;
+//# sourceMappingURL=meshopt_encode_vertex_buffer.d.ts.map

package/src/core/binary/meshopt/meshopt_encode_vertex_buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshopt_encode_vertex_buffer.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/meshopt/meshopt_encode_vertex_buffer.js"],"names":[],"mappings":"AA2FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qDAZW,UAAU,SACV,MAAM,eACN,MAAM;IAEW,OAAO,GAAxB,MAAM;IACwB,aAAa,GAA3C,MAAM,EAAE,GAAC,UAAU;IAIjB,UAAU,CA0EtB"}