@woosh/meep-engine 3.14.0 → 3.14.2

package/src/basis/transcode/etc1s_to_bc7.js

@@ -0,0 +1,496 @@
+import { etc1s_block_colors } from "../etc1s/etc1s_block_colors.js";
+import { build_range_plan } from "./build_range_plan.js";
+import { fit_endpoints, SELECTOR_RANGES } from "./fit_endpoints.js";
+
+/**
+ * Bytes one BC7 block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BC7_BLOCK_BYTES = 16;
+
+/**
+ * BC7's interpolation weights for four-bit indices, out of 64.
+ *
+ * @readonly
+ * @type {Int32Array}
+ */
+const WEIGHT4 = new Int32Array([0, 4, 9, 13, 17, 21, 26, 30, 34, 38, 43, 47, 51, 55, 60, 64]);
+
+/**
+ * BC7's interpolation weights for two-bit indices, out of 64.
+ *
+ * @readonly
+ * @type {Int32Array}
+ */
+const WEIGHT2 = new Int32Array([0, 21, 43, 64]);
+
+/**
+ * @param {number} a endpoint, eight bits
+ * @param {number} b endpoint, eight bits
+ * @param {number} weight out of 64
+ * @returns {number} the interpolated channel, as BC7 defines it
+ */
+function interpolate(a, b, weight) {
+    return (a * (64 - weight) + b * weight + 32) >> 6;
+}
+
+/**
+ * The eight-bit value a seven-bit endpoint decodes to, by BC7's bit replication.
+ *
+ * @param {number} value seven bits
+ * @returns {number}
+ */
+function replicate7(value) {
+    return ((value << 1) | (value >> 6)) & 255;
+}
+
+/**
+ * A little-endian bit accumulator over one block's sixteen bytes.
+ *
+ * BC7 fields are specified least significant bit first from byte zero, so writing them in the order
+ * the specification lists them is exactly writing the block.
+ */
+class Bc7BlockWriter {
+    /**
+     * @type {Uint8Array}
+     */
+    #out = null;
+
+    /**
+     * Bit position within {@link #out}, not within the block.
+     * @type {number}
+     */
+    #bit = 0;
+
+    /**
+     * @param {Uint8Array} out
+     * @param {number} byte_offset of the block
+     * @returns {Bc7BlockWriter} this
+     */
+    init(out, byte_offset) {
+        this.#out = out;
+        this.#bit = byte_offset * 8;
+
+        return this;
+    }
+
+    /**
+     * @param {number} value
+     * @param {number} count bits, at most 8
+     */
+    write(value, count) {
+        for (let i = 0; i < count; i++) {
+            if (((value >> i) & 1) !== 0) {
+                this.#out[(this.#bit + i) >> 3] |= 1 << ((this.#bit + i) & 7);
+            }
+        }
+
+        this.#bit += count;
+    }
+}
+
+/**
+ * Transcode a decoded ETC1S slice to BC7.
+ *
+ * **Two modes, chosen by whether the payload carries alpha, because BC7 cannot do both at once.**
+ * Mode 6 gives one index per texel, shared by all four channels, with four bits of it; mode 5 gives
+ * colour and alpha their own indices but only two bits each. An opaque payload wants the finer
+ * index; an alpha payload needs the independent one, because an ETC1S file's alpha slice has its own
+ * selectors, unrelated to the colour slice's, and a shared index could not express both.
+ *
+ * **The work is per codebook pairing, not per block.** What a block decodes to depends only on which
+ * endpoint entry and which selector entry it names, so endpoints are fitted once per (endpoint
+ * entry, selector span) pairing — see {@link fit_endpoints} for why the span is part of the key —
+ * and every block naming that pairing just writes the result out. Colour and alpha are tabulated
+ * separately, which is what lets mode 5 pair any colour entry with any alpha entry without a table
+ * of their product.
+ *
+ * @param {Etc1sSlice} slice the colour slice
+ * @param {Etc1sSlice|undefined} alpha_slice the alpha slice, when the payload has one
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed BC7 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_bc7(slice, alpha_slice, endpoints, selectors) {
+    return alpha_slice === undefined
+        ? to_mode6(slice, endpoints, selectors)
+        : to_mode5(slice, alpha_slice, endpoints, selectors);
+}
+
+/**
+ * The opaque path: one four-bit index per texel, alpha pinned opaque.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array}
+ */
+function to_mode6(slice, endpoints, selectors) {
+    const plan = build_range_plan(selectors);
+
+    const templates = build_color_templates(endpoints, plan, WEIGHT4, quantise_mode6);
+
+    const block_count = slice.blocks_x * slice.blocks_y;
+
+    const out = new Uint8Array(block_count * BC7_BLOCK_BYTES);
+
+    const writer = new Bc7BlockWriter();
+
+    const indices = new Uint8Array(16);
+
+    for (let block = 0; block < block_count; block++) {
+        const selector_entry = slice.selector_index[block];
+        const selector_base = selector_entry * 16;
+
+        const pairing = slice.endpoint_index[block] * plan.slot_count
+            + plan.slot_of_entry[selector_entry];
+
+        const e = pairing * 3;
+
+        const flipped = fill_indices(
+            indices, templates.selector_to_index, pairing, selectors, selector_base, WEIGHT4.length
+        );
+
+        writer.init(out, block * BC7_BLOCK_BYTES);
+
+        // mode 6 is signalled by six zero bits then a one
+        writer.write(0x40, 7);
+
+        /*
+         The endpoints go out in whichever order {@link fill_indices} settled on. Swapping them and
+         inverting every index leaves the decoded block identical — BC7's weight tables are symmetric
+         about their midpoint — which is what makes the anchor rule satisfiable without re-fitting.
+        */
+        const first = flipped ? templates.high : templates.low;
+        const second = flipped ? templates.low : templates.high;
+
+        writer.write(first[e], 7);
+        writer.write(second[e], 7);
+        writer.write(first[e + 1], 7);
+        writer.write(second[e + 1], 7);
+        writer.write(first[e + 2], 7);
+        writer.write(second[e + 2], 7);
+
+        /*
+         Alpha, opaque. Both endpoints are seven ones and both parity bits are one, so each decodes
+         to exactly 255 — which is why the parity is fixed rather than fitted: an endpoint's parity
+         bit is shared with its alpha channel, and an opaque texture that decoded to 254 would be a
+         texture with alpha nobody asked for. It costs each colour channel one step out of 255.
+        */
+        writer.write(0x7F, 7);
+        writer.write(0x7F, 7);
+
+        writer.write(1, 1);
+        writer.write(1, 1);
+
+        for (let texel = 0; texel < 16; texel++) {
+            writer.write(indices[texel], texel === 0 ? 3 : 4);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * The alpha path: two-bit colour and alpha indices, each with their own endpoints.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice} alpha_slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array}
+ */
+function to_mode5(slice, alpha_slice, endpoints, selectors) {
+    const plan = build_range_plan(selectors);
+
+    const color = build_color_templates(endpoints, plan, WEIGHT2, quantise_mode5);
+    const alpha = build_alpha_templates(endpoints, plan);
+
+    const block_count = slice.blocks_x * slice.blocks_y;
+
+    const out = new Uint8Array(block_count * BC7_BLOCK_BYTES);
+
+    const writer = new Bc7BlockWriter();
+
+    const color_indices = new Uint8Array(16);
+    const alpha_indices = new Uint8Array(16);
+
+    for (let block = 0; block < block_count; block++) {
+        const selector_entry = slice.selector_index[block];
+        const selector_base = selector_entry * 16;
+
+        const alpha_selector_entry = alpha_slice.selector_index[block];
+        const alpha_selector_base = alpha_selector_entry * 16;
+
+        const pairing = slice.endpoint_index[block] * plan.slot_count
+            + plan.slot_of_entry[selector_entry];
+
+        const alpha_pairing = alpha_slice.endpoint_index[block] * plan.slot_count
+            + plan.slot_of_entry[alpha_selector_entry];
+
+        const e = pairing * 3;
+
+        /*
+         Mode 5 keeps two index sets and each has its own anchor, so each is normalised on its own —
+         which is exactly why the colour and alpha endpoints had to stay independent.
+        */
+        const color_flipped = fill_indices(
+            color_indices, color.selector_to_index, pairing, selectors, selector_base,
+            WEIGHT2.length
+        );
+
+        const alpha_flipped = fill_indices(
+            alpha_indices, alpha.selector_to_index, alpha_pairing, selectors, alpha_selector_base,
+            WEIGHT2.length
+        );
+
+        writer.init(out, block * BC7_BLOCK_BYTES);
+
+        // mode 5 is signalled by five zero bits then a one, followed by a two-bit channel rotation
+        writer.write(0x20, 6);
+        writer.write(0, 2);
+
+        const first = color_flipped ? color.high : color.low;
+        const second = color_flipped ? color.low : color.high;
+
+        writer.write(first[e], 7);
+        writer.write(second[e], 7);
+        writer.write(first[e + 1], 7);
+        writer.write(second[e + 1], 7);
+        writer.write(first[e + 2], 7);
+        writer.write(second[e + 2], 7);
+
+        writer.write(alpha_flipped ? alpha.high[alpha_pairing] : alpha.low[alpha_pairing], 8);
+        writer.write(alpha_flipped ? alpha.low[alpha_pairing] : alpha.high[alpha_pairing], 8);
+
+        for (let texel = 0; texel < 16; texel++) {
+            writer.write(color_indices[texel], texel === 0 ? 1 : 2);
+        }
+
+        for (let texel = 0; texel < 16; texel++) {
+            writer.write(alpha_indices[texel], texel === 0 ? 1 : 2);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Quantise a fitted eight-bit channel the way mode 6 stores it, with the parity bit fixed at one.
+ *
+ * @param {number} value
+ * @returns {{stored: number, decoded: number}}
+ */
+function quantise_mode6(value) {
+    const decoded = value | 1;
+
+    return { stored: decoded >> 1, decoded };
+}
+
+/**
+ * Quantise a fitted eight-bit channel the way mode 5 stores a colour endpoint: seven bits, decoding
+ * by replication rather than by an appended parity bit.
+ *
+ * @param {number} value
+ * @returns {{stored: number, decoded: number}}
+ */
+function quantise_mode5(value) {
+    const stored = Math.min(127, (value * 127 + 127) / 255 | 0);
+
+    return { stored, decoded: replicate7(stored) };
+}
+
+/**
+ * Fitted, quantised endpoints and a selector mapping for every (endpoint entry, selector span)
+ * pairing.
+ *
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {{slot_count: number, range_of_slot: Uint8Array}} plan
+ * @param {Int32Array} weights
+ * @param {function(number): {stored: number, decoded: number}} quantise
+ * @returns {{low: Uint8Array, high: Uint8Array, selector_to_index: Uint8Array}}
+ */
+function build_color_templates(endpoints, plan, weights, quantise) {
+    const pairings = endpoints.count * plan.slot_count;
+
+    const low = new Uint8Array(pairings * 3);
+    const high = new Uint8Array(pairings * 3);
+    const selector_to_index = new Uint8Array(pairings * 4);
+
+    const colors = new Uint8Array(12);
+    const fitted_low = new Uint8Array(3);
+    const fitted_high = new Uint8Array(3);
+    const decoded_low = new Uint8Array(3);
+    const decoded_high = new Uint8Array(3);
+
+    for (let entry = 0; entry < endpoints.count; entry++) {
+        etc1s_block_colors(colors, 0, endpoints.color5, endpoints.intensity, entry);
+
+        for (let slot = 0; slot < plan.slot_count; slot++) {
+            const [min, max] = SELECTOR_RANGES[plan.range_of_slot[slot]];
+
+            for (let c = 0; c < 3; c++) {
+                fitted_low[c] = colors[min * 3 + c];
+                fitted_high[c] = colors[max * 3 + c];
+            }
+
+            fit_endpoints(fitted_low, fitted_high, colors, weights, min, max);
+
+            const pairing = entry * plan.slot_count + slot;
+            const e = pairing * 3;
+
+            for (let c = 0; c < 3; c++) {
+                const a = quantise(fitted_low[c]);
+                const b = quantise(fitted_high[c]);
+
+                low[e + c] = a.stored;
+                high[e + c] = b.stored;
+
+                decoded_low[c] = a.decoded;
+                decoded_high[c] = b.decoded;
+            }
+
+            /*
+             Assigned against the endpoints as they will *decode*, not as they were fitted.
+             Quantisation moves them, and an index chosen against the unquantised pair would be a
+             step off wherever that move mattered.
+            */
+            for (let selector = 0; selector < 4; selector++) {
+                selector_to_index[pairing * 4 + selector] = closest_weight(
+                    decoded_low, decoded_high, weights, colors, selector * 3
+                );
+            }
+        }
+    }
+
+    return { low, high, selector_to_index };
+}
+
+/**
+ * The same, read as alpha.
+ *
+ * The alpha slice is an ordinary ETC1S image whose green channel carries the alpha, which is what
+ * the specification says of it — so the same codebook is read and one channel of it is kept. Mode 5
+ * gives alpha a full eight bits, so no quantisation happens and the endpoints of a two-value span
+ * are exact.
+ *
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {{slot_count: number, range_of_slot: Uint8Array}} plan
+ * @returns {{low: Uint8Array, high: Uint8Array, selector_to_index: Uint8Array}}
+ */
+function build_alpha_templates(endpoints, plan) {
+    const pairings = endpoints.count * plan.slot_count;
+
+    const low = new Uint8Array(pairings);
+    const high = new Uint8Array(pairings);
+    const selector_to_index = new Uint8Array(pairings * 4);
+
+    const colors = new Uint8Array(12);
+
+    for (let entry = 0; entry < endpoints.count; entry++) {
+        etc1s_block_colors(colors, 0, endpoints.color5, endpoints.intensity, entry);
+
+        for (let slot = 0; slot < plan.slot_count; slot++) {
+            const [min, max] = SELECTOR_RANGES[plan.range_of_slot[slot]];
+
+            const pairing = entry * plan.slot_count + slot;
+
+            const a = colors[min * 3 + 1];
+            const b = colors[max * 3 + 1];
+
+            low[pairing] = a;
+            high[pairing] = b;
+
+            for (let selector = 0; selector < 4; selector++) {
+                const target = colors[selector * 3 + 1];
+
+                let best = 0;
+                let best_error = Infinity;
+
+                for (let i = 0; i < WEIGHT2.length; i++) {
+                    const error = Math.abs(interpolate(a, b, WEIGHT2[i]) - target);
+
+                    if (error < best_error) {
+                        best_error = error;
+                        best = i;
+                    }
+                }
+
+                selector_to_index[pairing * 4 + selector] = best;
+            }
+        }
+    }
+
+    return { low, high, selector_to_index };
+}
+
+/**
+ * Fill one block's indices, flipping them if the first texel's would not fit the anchor.
+ *
+ * **BC7 stores the first texel's index one bit short**, because a block is required to be written so
+ * that index's most significant bit is zero. Nothing about an ETC1S block guarantees that — the
+ * first texel is whatever it is — so a block whose first index is in the upper half is rewritten
+ * against the endpoints in the other order, which inverts every index and lands the first one in the
+ * lower half. The decoded result is unchanged, since BC7's weight tables are symmetric about their
+ * midpoint.
+ *
+ * @param {Uint8Array} out sixteen indices
+ * @param {Uint8Array} selector_to_index the pairing's mapping
+ * @param {number} pairing
+ * @param {Etc1sSelectorCodebook} selectors
+ * @param {number} selector_base into `selectors.selectors`
+ * @param {number} index_count how many index values the mode has
+ * @returns {boolean} whether the endpoints must be written in the other order
+ */
+function fill_indices(out, selector_to_index, pairing, selectors, selector_base, index_count) {
+    const map = pairing * 4;
+
+    const first = selector_to_index[map + selectors.selectors[selector_base]];
+
+    const flipped = first >= index_count / 2;
+
+    for (let texel = 0; texel < 16; texel++) {
+        const index = selector_to_index[map + selectors.selectors[selector_base + texel]];
+
+        out[texel] = flipped ? index_count - 1 - index : index;
+    }
+
+    return flipped;
+}
+
+/**
+ * Which interpolation weight best reproduces a target colour between two endpoints.
+ *
+ * @param {Uint8Array} a three channels, as they decode
+ * @param {Uint8Array} b three channels, as they decode
+ * @param {Int32Array} weights
+ * @param {Uint8Array} target
+ * @param {number} target_offset
+ * @returns {number} an index into `weights`
+ */
+function closest_weight(a, b, weights, target, target_offset) {
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < weights.length; i++) {
+        let error = 0;
+
+        for (let c = 0; c < 3; c++) {
+            const delta = interpolate(a[c], b[c], weights[i]) - target[target_offset + c];
+
+            error += delta * delta;
+        }
+
+        if (error < best_error) {
+            best_error = error;
+            best = i;
+        }
+    }
+
+    return best;
+}

package/src/basis/transcode/fit_endpoints.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Which entry of {@link SELECTOR_RANGES} a `[min, max]` span is.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function selector_range_index(min: number, max: number): number;
+/**
+ * Fit a pair of endpoints to the colours a block actually uses, by least squares.
+ *
+ * **Why the obvious choice is not good enough.** An ETC1S block's four colours are its base colour
+ * plus a modifier applied equally to every channel, so before clamping they lie on a line and the
+ * darkest and brightest of them span it exactly. Clamping breaks that. A base colour near white with
+ * a large modifier gives, say, red `{67, 203, 255, 255}` beside green `{0, 0, 57, 193}` — still
+ * ordered, but no longer collinear, because red saturated and green did not. Taking the outer two as
+ * endpoints then leaves the middle two nowhere near the line between them, and no interpolation
+ * weight can recover them.
+ *
+ * So the endpoints are fitted rather than read off: each colour is assigned the weight that suits it
+ * best, the endpoints are re-solved to minimise squared error against all of them at once, and the
+ * two steps alternate.
+ *
+ * **And the fit is over `[min_selector, max_selector]` only.** Which colours a block uses is a
+ * property of its *selector* codebook entry, and most entries do not use all four — a block spanning
+ * only the darkest two is a line those two define exactly, and fitting it against colours it never
+ * samples throws that away for nothing. Conditioning on the span is what closes most of the distance
+ * to the reference transcoder on saturated content.
+ *
+ * @param {Uint8Array} low three channels, seeded with a guess and overwritten with the fit
+ * @param {Uint8Array} high three channels, likewise
+ * @param {Uint8Array} colors twelve bytes, the block's four `[r, g, b]` colours
+ * @param {Int32Array} weights the destination format's interpolation weights, out of 64
+ * @param {number} min_selector lowest selector value any block using this pairing has
+ * @param {number} max_selector highest
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function fit_endpoints(low: Uint8Array, high: Uint8Array, colors: Uint8Array, weights: Int32Array, min_selector: number, max_selector: number): void;
+/**
+ * The `[min, max]` selector span of every entry of a selector codebook.
+ *
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} one index into {@link SELECTOR_RANGES} per entry
+ */
+export function selector_codebook_ranges(selectors: Etc1sSelectorCodebook): Uint8Array;
+/**
+ * Every `[min, max]` span of selector values a block can use, as pairs.
+ *
+ * Ten of them, because a span is an ordered pair drawn from four values. A block that only uses the
+ * darkest two colours is fitted against those two alone, which is the whole reason this exists — see
+ * {@link fit_endpoints}.
+ *
+ * @readonly
+ * @type {number[][]}
+ */
+export const SELECTOR_RANGES: number[][];
+//# sourceMappingURL=fit_endpoints.d.ts.map

package/src/basis/transcode/fit_endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit_endpoints.d.ts","sourceRoot":"","sources":["../../../../src/basis/transcode/fit_endpoints.js"],"names":[],"mappings":"AA2BA;;;;;;GAMG;AACH,0CAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,mCAVW,UAAU,QACV,UAAU,UACV,UAAU,WACV,UAAU,gBACV,MAAM,gBACN,MAAM,QA+EhB;AA+CD;;;;;GAKG;AACH,4EAFa,UAAU,CAyBtB;AAvND;;;;;;;;;GASG;AACH,8BAFU,MAAM,EAAE,EAAE,CAOlB"}