@woosh/meep-engine 3.14.2 → 3.14.3

package/src/format/texture/basis/transcode/etc1s_to_astc.js

@@ -0,0 +1,328 @@
+import {
+    ASTC_BLOCK_BYTES,
+    ASTC_WEIGHT_UNQUANTIZED,
+    astc_interpolate,
+    astc_order_endpoints,
+    astc_write_block
+} from "../astc_block.js";
+import { etc1s_block_colors } from "../etc1s/etc1s_block_colors.js";
+
+/**
+ * Bits a weight takes in the blocks this writes, and the levels that follow from it.
+ *
+ * **Two, where {@link uastc_to_astc} takes three.** An ETC1S block holds four colours and no more,
+ * so eight weight levels would spend half of them describing points the source never had — the
+ * limit here is the source, not the container. Two bits is also what leaves room for the endpoints
+ * a four-channel mode would need, should alpha ever be worth carrying this way.
+ *
+ * @readonly
+ * @type {number}
+ */
+const WEIGHT_BITS = 2;
+
+/**
+ * @readonly
+ * @type {number[]}
+ */
+const LEVELS = ASTC_WEIGHT_UNQUANTIZED[WEIGHT_BITS];
+
+/**
+ * Transcode ETC1S to ASTC 4x4.
+ *
+ * **The mobile counterpart to {@link etc1s_to_etc2}**, and the one compressed format that appears in
+ * every role's preference list — every recent phone samples it, where ETC2 is the older floor. Both
+ * are eight bits a texel.
+ *
+ * **A close fit, because an ETC1S block is already a line.** Its four colours are one base colour
+ * plus the same offset in each channel, so they lie on a line parallel to the grey axis, which is
+ * exactly what a single-partition ASTC block with two endpoints and an interpolant represents. What
+ * is left is choosing where on that line the four weight levels sit, which {@link fit_block} searches.
+ *
+ * **Opaque only.** ASTC can carry alpha, but not with a shared weight plane: an ETC1S payload's
+ * colour and alpha come from two independent slices with their own selectors, and forcing them onto
+ * one set of weights would wreck both. The dual-plane block mode that would separate them cannot also
+ * hold eight endpoints and thirty-two weight bits in 128 bits. So this declares no alpha and a
+ * payload carrying some falls through to a target that has room — the mechanism BC1 has used since
+ * step 9, and which `ktx2_read` now applies before a format is committed to rather than after.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} _alpha_slice refused before this is called; see above
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed ASTC blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_astc(slice, _alpha_slice, endpoints, selectors) {
+    const block_count = slice.blocks_x * slice.blocks_y;
+
+    const out = new Uint8Array(block_count * ASTC_BLOCK_BYTES);
+
+    const palette = new Uint8Array(12);
+    const fitted = new Int32Array(6);
+    const weights = new Uint8Array(16);
+
+    for (let block = 0; block < block_count; block++) {
+        etc1s_block_colors(
+            palette, 0, endpoints.color5, endpoints.intensity, slice.endpoint_index[block]
+        );
+
+        const selector_base = slice.selector_index[block] * 16;
+
+        fit_block(fitted, weights, palette, selectors.selectors, selector_base);
+
+        astc_order_endpoints(fitted, weights, LEVELS.length - 1);
+
+        astc_write_block(out, block * ASTC_BLOCK_BYTES, fitted, weights, WEIGHT_BITS);
+    }
+
+    return out;
+}
+
+/**
+ * Every strictly increasing choice of `count` of the four weight levels.
+ *
+ * Enumerated rather than reasoned about: fifteen in total across all four sizes, and the arithmetic
+ * that would pick the right one directly is longer than the list.
+ *
+ * @readonly
+ * @type {number[][][]}
+ */
+const PLACEMENTS = [0, 1, 2, 3, 4].map(count => {
+    const out = [];
+
+    const walk = (start, chosen) => {
+        if (chosen.length === count) {
+            out.push(chosen.slice());
+
+            return;
+        }
+
+        for (let level = start; level < 4; level++) {
+            chosen.push(level);
+            walk(level + 1, chosen);
+            chosen.pop();
+        }
+    };
+
+    walk(0, []);
+
+    return out;
+});
+
+/**
+ * Fit a block: which weight level each of its selectors takes, and the endpoints that follow.
+ *
+ * **The selectors are placed on the weight levels rather than used as them.** ETC1S's four colours
+ * and ASTC's four weight levels are both ordered darkest to brightest, so the identity mapping is
+ * available and is what a block using its whole palette is stuck with — but a block using only two
+ * or three entries should spread those over all four levels instead, which costs nothing and is
+ * exact for two. Skipping this is worth about nine decibels, and it is what the reference transcoder
+ * does.
+ *
+ * The two orderings are not alike even when all four are used: ETC1S's middle pair sits at roughly
+ * 0.37 and 0.63 of the range against ASTC's 21/64 and 43/64, so the identity mapping is a fit rather
+ * than an equality. Nothing better is available at two bits a weight.
+ *
+ * @param {Int32Array} endpoints_out six values, `R0 R1 G0 G1 B0 B1`
+ * @param {Uint8Array} weights_out sixteen weight levels, in raster order
+ * @param {Uint8Array} palette twelve bytes, four RGB triples
+ * @param {Uint8Array} selector_values
+ * @param {number} selector_base
+ */
+function fit_block(endpoints_out, weights_out, palette, selector_values, selector_base) {
+    const used = [];
+
+    for (let texel = 0; texel < 16; texel++) {
+        const selector = selector_values[selector_base + texel];
+
+        if (!used.includes(selector)) {
+            used.push(selector);
+        }
+    }
+
+    used.sort((a, b) => a - b);
+
+    let best_error = Infinity;
+
+    const level_of = new Int32Array(4);
+    const candidate = new Int32Array(6);
+
+    for (const placement of PLACEMENTS[used.length]) {
+        for (let i = 0; i < used.length; i++) {
+            level_of[used[i]] = placement[i];
+        }
+
+        const error = fit_endpoints(candidate, palette, selector_values, selector_base, level_of);
+
+        if (error < best_error) {
+            best_error = error;
+
+            endpoints_out.set(candidate);
+
+            for (let texel = 0; texel < 16; texel++) {
+                weights_out[texel] = level_of[selector_values[selector_base + texel]];
+            }
+        }
+    }
+
+    refine(endpoints_out, palette, selector_values, selector_base, weights_out);
+}
+
+/**
+ * Nudge each channel's endpoints to the best pair within a step or two of the least-squares one.
+ *
+ * **Least squares minimises the wrong thing by a little.** It fits real-valued endpoints against
+ * real-valued targets; what gets written is the rounded pair, and what is read back is
+ * {@link interpolate}'s integer arithmetic on it. Those two roundings do not commute, so the rounded
+ * least-squares answer is usually but not always the best integer pair — a step in one direction
+ * often trades a large error on one texel for small ones on several.
+ *
+ * Only the winning placement is refined, and only over a small window. The placement search above
+ * runs first on the cheaper score, because refining all fifteen would multiply the cost of every
+ * block by more than it buys: this closes the last level against the reference encoder, which is
+ * worth a bounded pass and not an unbounded one.
+ *
+ * Channels are independent once the weights are fixed, so each is searched on its own — three
+ * searches of twenty-five candidates rather than one of fifteen thousand.
+ *
+ * @param {Int32Array} endpoints six values, modified in place
+ * @param {Uint8Array} palette
+ * @param {Uint8Array} selector_values
+ * @param {number} selector_base
+ * @param {Uint8Array} weights the chosen weight level per texel
+ */
+function refine(endpoints, palette, selector_values, selector_base, weights) {
+    for (let channel = 0; channel < 3; channel++) {
+        const start0 = endpoints[channel * 2];
+        const start1 = endpoints[channel * 2 + 1];
+
+        let best0 = start0;
+        let best1 = start1;
+        let best_error = Infinity;
+
+        for (let d0 = -2; d0 <= 2; d0++) {
+            for (let d1 = -2; d1 <= 2; d1++) {
+                const q0 = clamp255(start0 + d0);
+                const q1 = clamp255(start1 + d1);
+
+                let error = 0;
+
+                for (let texel = 0; texel < 16; texel++) {
+                    const decoded = astc_interpolate(q0, q1, LEVELS[weights[texel]]);
+
+                    const delta = decoded
+                        - palette[selector_values[selector_base + texel] * 3 + channel];
+
+                    error += delta * delta;
+                }
+
+                if (error < best_error) {
+                    best_error = error;
+                    best0 = q0;
+                    best1 = q1;
+                }
+            }
+        }
+
+        endpoints[channel * 2] = best0;
+        endpoints[channel * 2 + 1] = best1;
+    }
+}
+
+/**
+ * Least-squares endpoints for one placement, and the squared error it leaves.
+ *
+ * A two-parameter linear fit per channel, sharing one set of `t` statistics because every channel's
+ * texels sit at the same positions along the line. The fit is real-valued and the scoring is not:
+ * what is compared is what {@link interpolate} will actually produce from the rounded, clamped
+ * endpoints, so a placement is judged on the block that will be written.
+ *
+ * @param {Int32Array} out six values
+ * @param {Uint8Array} palette
+ * @param {Uint8Array} selector_values
+ * @param {number} selector_base
+ * @param {Int32Array} level_of weight level for each selector value
+ * @returns {number} summed squared error over all sixteen texels and three channels
+ */
+function fit_endpoints(out, palette, selector_values, selector_base, level_of) {
+    let sum_t = 0;
+    let sum_tt = 0;
+
+    for (let texel = 0; texel < 16; texel++) {
+        const t = LEVELS[level_of[selector_values[selector_base + texel]]] / 64;
+
+        sum_t += t;
+        sum_tt += t * t;
+    }
+
+    const n = 16;
+
+    /*
+     The normal equations for `value = e0 (1 - t) + e1 t`, written in terms of `e0` and `d = e1 - e0`
+     so that the shared statistics fall out: `sum(v) = n e0 + d sum(t)` and
+     `sum(v t) = e0 sum(t) + d sum(t t)`.
+    */
+    const determinant = n * sum_tt - sum_t * sum_t;
+
+    let error = 0;
+
+    for (let channel = 0; channel < 3; channel++) {
+        let sum_v = 0;
+        let sum_vt = 0;
+
+        for (let texel = 0; texel < 16; texel++) {
+            const selector = selector_values[selector_base + texel];
+
+            const v = palette[selector * 3 + channel];
+            const t = LEVELS[level_of[selector]] / 64;
+
+            sum_v += v;
+            sum_vt += v * t;
+        }
+
+        let e0;
+        let d;
+
+        if (determinant === 0) {
+            /*
+             Every texel at the same weight, so the line is a point and only one endpoint is
+             determined. Both are set to it, which reproduces the block exactly whatever the weights
+             then say.
+            */
+            e0 = sum_v / n;
+            d = 0;
+        } else {
+            e0 = (sum_v * sum_tt - sum_vt * sum_t) / determinant;
+            d = (n * sum_vt - sum_v * sum_t) / determinant;
+        }
+
+        const q0 = clamp255(Math.round(e0));
+        const q1 = clamp255(Math.round(e0 + d));
+
+        out[channel * 2] = q0;
+        out[channel * 2 + 1] = q1;
+
+        for (let texel = 0; texel < 16; texel++) {
+            const selector = selector_values[selector_base + texel];
+
+            const decoded = astc_interpolate(q0, q1, LEVELS[level_of[selector]]);
+
+            const delta = decoded - palette[selector * 3 + channel];
+
+            error += delta * delta;
+        }
+    }
+
+    return error;
+}
+
+/**
+ * @param {number} value
+ * @returns {number} `value` brought into `[0, 255]`
+ */
+function clamp255(value) {
+    return value < 0 ? 0 : value > 255 ? 255 : value;
+}
+

package/src/format/texture/basis/transcode/etc1s_to_bc1.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Transcode a decoded ETC1S slice to BC1.
+ *
+ * **Both formats put four colours on a line, which is what makes this cheap and good.** An ETC1S
+ * block is a base colour plus an intensity modifier applied equally to all three channels, so its
+ * four colours are collinear; BC1's are two endpoints plus two interpolants, which is the same
+ * shape. The transcode is therefore a re-parameterisation rather than a re-quantisation, and what it
+ * loses is only what 5:6:5 endpoints lose over ETC1S's 5:5:5-plus-modifier.
+ *
+ * **The work is per endpoint codebook entry, not per block.** A block's four colours depend only on
+ * which endpoint entry it names, so the endpoint pair and the selector-to-index mapping are computed
+ * once per entry — of which there are at most a few thousand — and every block that names it just
+ * writes them out. A texture is typically tens of thousands of blocks over a few hundred entries.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed BC1 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_bc1(slice: Etc1sSlice, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook): Uint8Array;
+/**
+ * The two packed endpoints, ordered so the block decodes in four-colour mode.
+ */
+export type Bc1EndpointPair = {
+    /**
+     * the endpoint written first, which must compare greater
+     */
+    first: number;
+    second: number;
+};
+//# sourceMappingURL=etc1s_to_bc1.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_bc1.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/etc1s_to_bc1.js"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qHALa,UAAU,CAiCtB;;;;;;;;WAyPa,MAAM;YACN,MAAM"}