@woosh/meep-engine 3.14.2 → 3.14.4

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

@@ -0,0 +1,486 @@
+import { BC1_BLOCK_BYTES, bc1_write_block } from "../../bc/bc1_write_block.js";
+import { build_range_plan } from "./build_range_plan.js";
+import { SELECTOR_RANGES, solve_endpoints } from "./fit_endpoints.js";
+import { etc1s_block_colors } from "../etc1s/etc1s_block_colors.js";
+
+/**
+ * Pack an eight-bit-per-channel colour into BC1's 5:6:5 endpoint.
+ *
+ * Rounding rather than truncating: truncation biases every endpoint darker, and over a whole texture
+ * that reads as a gamma shift rather than as noise.
+ *
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {number} sixteen bits
+ */
+function pack565(r, g, b) {
+    const r5 = Math.min(31, (r * 31 + 127) / 255 | 0);
+    const g6 = Math.min(63, (g * 63 + 127) / 255 | 0);
+    const b5 = Math.min(31, (b * 31 + 127) / 255 | 0);
+
+    return (r5 << 11) | (g6 << 5) | b5;
+}
+
+/**
+ * The eight-bit colour a 5:6:5 endpoint decodes to, by the same bit replication hardware uses.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {number} packed
+ */
+function unpack565(out, offset, packed) {
+    const r5 = (packed >> 11) & 31;
+    const g6 = (packed >> 5) & 63;
+    const b5 = packed & 31;
+
+    out[offset] = (r5 << 3) | (r5 >> 2);
+    out[offset + 1] = (g6 << 2) | (g6 >> 4);
+    out[offset + 2] = (b5 << 3) | (b5 >> 2);
+}
+
+/**
+ * Which of BC1's four colours best matches a target, given the block's decoded palette.
+ *
+ * @param {Uint8Array} palette twelve bytes, four `[r, g, b]` triples in BC1 index order
+ * @param {Uint8Array} target three bytes
+ * @param {number} target_offset
+ * @returns {number} `0` to `3`
+ */
+function closest_index(palette, target, target_offset) {
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < 4; i++) {
+        const dr = palette[i * 3] - target[target_offset];
+        const dg = palette[i * 3 + 1] - target[target_offset + 1];
+        const db = palette[i * 3 + 2] - target[target_offset + 2];
+
+        const error = dr * dr + dg * dg + db * db;
+
+        if (error < best_error) {
+            best_error = error;
+            best = i;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * 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, endpoints, selectors) {
+    const plan = build_range_plan(selectors);
+
+    const templates = build_templates(endpoints, plan);
+
+    const block_count = slice.blocks_x * slice.blocks_y;
+
+    const out = new Uint8Array(block_count * BC1_BLOCK_BYTES);
+
+    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 low = templates.low[pairing];
+        const high = templates.high[pairing];
+        const map = pairing * 4;
+
+        for (let texel = 0; texel < 16; texel++) {
+            INDICES[texel] = templates.selector_to_index[map + selectors.selectors[selector_base + texel]];
+        }
+
+        bc1_write_block(out, block * BC1_BLOCK_BYTES, low, high, INDICES);
+    }
+
+    return out;
+}
+
+/**
+ * Scratch for a block's sixteen indices, so a block does not allocate.
+ *
+ * @type {Uint8Array}
+ */
+const INDICES = new Uint8Array(16);
+
+/**
+ * The BC1 endpoint pair and selector mapping for every (endpoint entry, selector span) pairing.
+ *
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sRangePlan} plan
+ * @returns {{low: Uint16Array, high: Uint16Array, selector_to_index: Uint8Array}} `low` is written
+ * first, and is the larger of the pair so the block decodes in four-colour mode
+ */
+function build_templates(endpoints, plan) {
+    const pairings = endpoints.count * plan.slot_count;
+
+    const low = new Uint16Array(pairings);
+    const high = new Uint16Array(pairings);
+    const selector_to_index = new Uint8Array(pairings * 4);
+
+    const colors = new Uint8Array(12);
+    const palette = new Uint8Array(12);
+    const fitted_low = new Uint8Array(3);
+    const fitted_high = new Uint8Array(3);
+    const weight_of_selector = new Int32Array(4);
+
+    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++) {
+            build_one(
+                low, high, selector_to_index, entry * plan.slot_count + slot,
+                colors, palette, fitted_low, fitted_high, weight_of_selector,
+                SELECTOR_RANGES[plan.range_of_slot[slot]]
+            );
+        }
+    }
+
+    return { low, high, selector_to_index };
+}
+
+/**
+ * One pairing's endpoints and selector mapping.
+ *
+ * @param {Uint16Array} low
+ * @param {Uint16Array} high
+ * @param {Uint8Array} selector_to_index
+ * @param {number} pairing
+ * @param {Uint8Array} colors the endpoint entry's four colours
+ * @param {Uint8Array} palette scratch
+ * @param {Uint8Array} fitted_low scratch
+ * @param {Uint8Array} fitted_high scratch
+ * @param {Int32Array} weight_of_selector scratch
+ * @param {number[]} range the selector span, `[min, max]`
+ */
+function build_one(
+    low, high, selector_to_index, pairing, colors, palette, fitted_low, fitted_high,
+    weight_of_selector, range
+) {
+    const [min, max] = range;
+
+    if (min === max) {
+        /*
+         Every block using this pairing is one colour, so both endpoints are that colour and there is
+         nothing to solve — the normal equations would be singular, since a single point says nothing
+         about the direction of the line through it.
+        */
+        const packed = pack565(colors[min * 3], colors[min * 3 + 1], colors[min * 3 + 2]);
+        const pair = order_pair(packed, packed);
+
+        low[pairing] = pair.first;
+        high[pairing] = pair.second;
+
+        build_palette(palette, pair.first, pair.second);
+
+        for (let selector = 0; selector < 4; selector++) {
+            selector_to_index[pairing * 4 + selector] = closest_index(palette, colors, selector * 3);
+        }
+
+        return;
+    }
+
+    const span = max - min + 1;
+
+    let best;
+    let best_error = Infinity;
+
+    /*
+     **Every way the span's colours could sit on BC1's four positions is tried, in order.** With only
+     four weights to aim at, which colour goes where is the decision that matters most, and the
+     greedy answer — extremes at the extremes — is frequently not the best one: three evenly spaced
+     colours fit almost exactly at weights 64, 43 and 21, with the fourth position falling outside
+     the colours entirely. There are at most fifteen such assignments, so they are enumerated rather
+     than searched for.
+    */
+    for (const assignment of ASSIGNMENTS[span]) {
+        for (let i = 0; i < span; i++) {
+            weight_of_selector[min + i] = POSITION_WEIGHTS[assignment[i]];
+        }
+
+        if (!solve_endpoints(fitted_low, fitted_high, colors, weight_of_selector, min, max)) {
+            continue;
+        }
+
+        /*
+         **And then the pair is searched in 5:6:5 space rather than rounded into it.** This is where
+         BC1 differs from BC7: BC7's endpoints are seven and eight bits wide, so rounding a fit into
+         them loses almost nothing, while BC1's are five, six and five, and the best representable
+         pair is not always the rounding of the best real-valued one — both endpoints and the two
+         interpolants derived from them move together, so a step that makes one endpoint worse can
+         make the block better.
+
+         Worth 0.2 to 1.3 dB, measured. The enumeration above is the expensive-looking half and the
+         one that actually pays: restricted to the greedy assignment, the noise fixture falls from
+         44.1 dB to 37.6 with a worst channel error of 30.
+        */
+        const candidate = refine_in_565(
+            quantise_pair(fitted_low, fitted_high), palette, colors, min, max
+        );
+
+        if (candidate.error < best_error) {
+            best_error = candidate.error;
+            best = candidate.pair;
+        }
+    }
+
+    low[pairing] = best.first;
+    high[pairing] = best.second;
+
+    build_palette(palette, best.first, best.second);
+
+    for (let selector = 0; selector < 4; selector++) {
+        selector_to_index[pairing * 4 + selector] = closest_index(palette, colors, selector * 3);
+    }
+}
+
+/**
+ * How many coordinate-descent passes to run over the six endpoint components. Two is almost always
+ * enough; the loop leaves early when a pass changes nothing.
+ *
+ * @readonly
+ * @type {number}
+ */
+const COORDINATE_PASSES = 4;
+
+/**
+ * Where BC1's four colours sit along the line between its endpoints, as weights out of 64.
+ *
+ * In positional order, which is not index order: indices 0 and 1 are the endpoints and 2 and 3 the
+ * interpolants between them, so along the line the indices run 0, 2, 3, 1. Only the positions matter
+ * here — which index each colour ends up with is settled afterwards by {@link closest_index}, against
+ * the palette the endpoints actually produce.
+ *
+ * @readonly
+ * @type {number[]}
+ */
+const POSITION_WEIGHTS = [0, 21, 43, 64];
+
+/**
+ * Every increasing assignment of a span of `k` colours to BC1's four positions, indexed by `k`.
+ *
+ * Increasing because the colours are already ordered darkest to brightest and an assignment that
+ * crossed them over would describe the same pair with the endpoints swapped.
+ *
+ * @readonly
+ * @type {number[][][]}
+ */
+const ASSIGNMENTS = build_assignments();
+
+/**
+ * @returns {number[][][]}
+ */
+function build_assignments() {
+    const by_span = [[], [], [], [], []];
+
+    for (let mask = 1; mask < 16; mask++) {
+        const chosen = [];
+
+        for (let position = 0; position < 4; position++) {
+            if ((mask & (1 << position)) !== 0) {
+                chosen.push(position);
+            }
+        }
+
+        by_span[chosen.length].push(chosen);
+    }
+
+    return by_span;
+}
+
+/**
+ * Coordinate-descend a packed pair over its six 5:6:5 components.
+ *
+ * @param {Bc1EndpointPair} seed
+ * @param {Uint8Array} palette scratch
+ * @param {Uint8Array} colors
+ * @param {number} min
+ * @param {number} max
+ * @returns {{pair: Bc1EndpointPair, error: number}}
+ */
+function refine_in_565(seed, palette, colors, min, max) {
+    let best = seed;
+    let best_error = pair_error(best, palette, colors, min, max);
+
+    for (let pass = 0; pass < COORDINATE_PASSES; pass++) {
+        let improved = false;
+
+        for (let component = 0; component < 6; component++) {
+            for (let step = -1; step <= 1; step += 2) {
+                const candidate = step_component(best, component, step);
+
+                if (candidate === undefined) {
+                    continue;
+                }
+
+                const error = pair_error(candidate, palette, colors, min, max);
+
+                if (error < best_error) {
+                    best_error = error;
+                    best = candidate;
+                    improved = true;
+                }
+            }
+        }
+
+        if (!improved) {
+            break;
+        }
+    }
+
+    return { pair: best, error: best_error };
+}
+
+/**
+ * Bits each 5:6:5 component has, in the order {@link step_component} walks them.
+ *
+ * @readonly
+ * @type {number[]}
+ */
+const COMPONENT_BITS = [5, 6, 5, 5, 6, 5];
+
+/**
+ * The two packed endpoints, ordered so the block decodes in four-colour mode.
+ *
+ * @typedef {object} Bc1EndpointPair
+ * @property {number} first the endpoint written first, which must compare greater
+ * @property {number} second
+ */
+
+/**
+ * @param {Uint8Array} a three channels
+ * @param {Uint8Array} b three channels
+ * @returns {Bc1EndpointPair}
+ */
+function quantise_pair(a, b) {
+    return order_pair(
+        pack565(a[0], a[1], a[2]),
+        pack565(b[0], b[1], b[2])
+    );
+}
+
+/**
+ * Put a pair in the order four-colour mode requires.
+ *
+ * Equal endpoints would select three-colour mode, whose fourth index decodes to transparent black,
+ * so they are nudged apart — which is invisible, because a block whose endpoints quantise to the
+ * same value is one colour either way.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {Bc1EndpointPair}
+ */
+function order_pair(a, b) {
+    const first = a >= b ? a : b;
+    const second = a >= b ? b : a;
+
+    return first === second
+        ? { first: first === 0 ? 1 : first, second: first === 0 ? 0 : first - 1 }
+        : { first, second };
+}
+
+/**
+ * A pair with one 5:6:5 component moved by a step, or `undefined` when that would leave the range.
+ *
+ * @param {Bc1EndpointPair} pair
+ * @param {number} component `0` to `2` in `first`, `3` to `5` in `second`
+ * @param {number} step
+ * @returns {Bc1EndpointPair|undefined}
+ */
+function step_component(pair, component, step) {
+    const in_second = component >= 3;
+    const channel = component % 3;
+
+    const packed = in_second ? pair.second : pair.first;
+
+    const shift = channel === 0 ? 11 : channel === 1 ? 5 : 0;
+    const bits = COMPONENT_BITS[component];
+    const mask = (1 << bits) - 1;
+
+    const value = (packed >> shift) & mask;
+    const next = value + step;
+
+    if (next < 0 || next > mask) {
+        return undefined;
+    }
+
+    const moved = (packed & ~(mask << shift)) | (next << shift);
+
+    return order_pair(
+        in_second ? pair.first : moved,
+        in_second ? moved : pair.second
+    );
+}
+
+/**
+ * Squared error of a candidate pair against the colours in the span, summed over channels.
+ *
+ * @param {Bc1EndpointPair} pair
+ * @param {Uint8Array} palette scratch, twelve bytes
+ * @param {Uint8Array} colors
+ * @param {number} min selector
+ * @param {number} max selector
+ * @returns {number}
+ */
+function pair_error(pair, palette, colors, min, max) {
+    build_palette(palette, pair.first, pair.second);
+
+    let total = 0;
+
+    for (let selector = min; selector <= max; selector++) {
+        const index = closest_index(palette, colors, selector * 3);
+
+        for (let c = 0; c < 3; c++) {
+            const delta = palette[index * 3 + c] - colors[selector * 3 + c];
+
+            total += delta * delta;
+        }
+    }
+
+    return total;
+}
+
+/**
+ * The four colours a BC1 block decodes to, in index order.
+ *
+ * The interpolants truncate rather than round, as the specification writes them. It matters only
+ * that the same arithmetic is used here and by whatever decodes the result: these colours exist to
+ * pick indices, and picking them against a palette a decoder will not produce is how a transcoder
+ * ends up half a level off everywhere.
+ *
+ * @param {Uint8Array} palette twelve bytes
+ * @param {number} first
+ * @param {number} second
+ */
+function build_palette(palette, first, second) {
+    unpack565(palette, 0, first);
+    unpack565(palette, 3, second);
+
+    for (let c = 0; c < 3; c++) {
+        palette[6 + c] = (2 * palette[c] + palette[3 + c]) / 3 | 0;
+        palette[9 + c] = (palette[c] + 2 * palette[3 + c]) / 3 | 0;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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: Etc1sSlice, alpha_slice: Etc1sSlice | undefined, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook): Uint8Array;
+//# sourceMappingURL=etc1s_to_bc7.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_bc7.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/etc1s_to_bc7.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,6DARW,aAAW,SAAS,uEAGlB,UAAU,CAStB"}

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"}