@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/texture/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/format/texture/basis/transcode/etc1s_to_etc2.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Transcode ETC1S to ETC2, which for these blocks is a repack rather than a re-encode.
+ *
+ * **ETC1S is a constrained ETC1, and ETC1 is a subset of ETC2.** A Basis block is one base colour
+ * with one intensity table and sixteen two-bit selectors, which is precisely ETC1's differential
+ * mode with both subblocks given the same colour — the deltas are zero and the two table codewords
+ * are equal. So nothing is fitted, nothing is searched, and nothing is lost: the RGB half of the
+ * output decodes bit-identically to what {@link etc1s_to_rgba8} produces, on any ETC2 hardware.
+ *
+ * That is what makes this worth having over the uncompressed floor on a device with no BC. It is
+ * eight bits a texel against thirty-two, at no cost in quality at all.
+ *
+ * **Alpha is the part that is actually encoded.** ETC2's RGBA8 block is an EAC alpha block followed
+ * by the RGB one, and EAC is a different scheme — a base value, a multiplier and a table, with three
+ * bits a texel. A payload with no alpha slice is written exactly opaque through the one table row
+ * containing a zero; a payload that carries alpha is fitted, which is the only lossy step here.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} alpha_slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @param {number} _width unused: an ETC2 level is a whole number of blocks, like every block format
+ * @param {number} _height
+ * @param {boolean} [with_alpha] write the 16-byte RGBA8 block rather than the 8-byte RGB8 one
+ * @returns {Uint8Array} tightly packed blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_etc2(slice: Etc1sSlice, alpha_slice: Etc1sSlice | undefined, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook, _width: number, _height: number, with_alpha?: boolean): Uint8Array;
+//# sourceMappingURL=etc1s_to_etc2.d.ts.map

package/src/format/texture/basis/transcode/etc1s_to_etc2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_etc2.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/etc1s_to_etc2.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8DAXW,aAAW,SAAS,8EAGpB,MAAM,WACN,MAAM,eACN,OAAO,GACL,UAAU,CAgDtB"}