@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/texture/basis/uastc/uastc_to_bc7.js

@@ -0,0 +1,602 @@
+import {
+    bc7_expand_endpoint,
+    bc7_quantise_endpoint,
+    bc7_write_block,
+    BC7_BLOCK_BYTES,
+    BC7_MODES,
+} from "./bc7_write_block.js";
+import {
+    bc7_fold_subset_3_to_2,
+    BC7_ANCHOR_2,
+    BC7_ANCHOR_3_SECOND,
+    BC7_ANCHOR_3_THIRD,
+    BC7_PARTITIONS_2,
+    BC7_PARTITIONS_3,
+    SUBSET_PERMUTATIONS,
+    UASTC_TO_BC7_2,
+    UASTC_TO_BC7_2_VIA_3,
+    UASTC_TO_BC7_3,
+} from "./bc7_tables.js";
+import { uastc_decode_block, UASTC_BLOCK_BYTES } from "./uastc_decode_block.js";
+import { UASTC_WEIGHT_VALUE } from "./uastc_tables.js";
+
+/**
+ * BC7's interpolation weights, by index width. Two- and three-bit are ASTC's tables exactly, which
+ * is what lets most weights cross over untouched.
+ *
+ * @readonly
+ * @type {Object<number, Int32Array>}
+ */
+const BC7_WEIGHTS = {
+    2: new Int32Array([0, 21, 43, 64]),
+    3: new Int32Array([0, 9, 18, 27, 37, 46, 55, 64]),
+    4: new Int32Array([0, 4, 8, 12, 17, 21, 25, 29, 35, 39, 43, 47, 52, 56, 60, 64]),
+};
+
+/**
+ * Which BC7 mode each UASTC mode is carried into, and how its partition maps.
+ *
+ * Taken from the specification, which names a BC7 mode against every UASTC mode. `via` says which
+ * of the three partition mappings applies — the odd one is mode 7, two subsets in UASTC and three in
+ * BC7.
+ *
+ * @readonly
+ * @type {Object<number, {bc7: number, via: string}>}
+ */
+const MODE_MAP = {
+    0: { bc7: 6, via: "single" },
+
+    /*
+     One subset, and the specification still pairs it with a *two*-subset BC7 mode — written as
+     partition zero with both subsets given the same endpoints. That is not a quirk: mode 1 carries
+     eight-bit endpoints and two-bit weights, and BC7 mode 3 is the only mode that holds eight-bit
+     endpoints without also having an alpha channel whose parity bit would have to be traded against
+     colour. Mode 6 would cost a bit of every channel to keep alpha at 255.
+    */
+    1: { bc7: 3, via: "single_as_two" },
+    2: { bc7: 1, via: "two" },
+    3: { bc7: 2, via: "three" },
+    4: { bc7: 3, via: "two" },
+    5: { bc7: 6, via: "single" },
+    6: { bc7: 5, via: "dual" },
+    7: { bc7: 2, via: "two_via_three" },
+    8: { bc7: 6, via: "single" },
+    9: { bc7: 7, via: "two" },
+    10: { bc7: 6, via: "single" },
+    11: { bc7: 5, via: "dual" },
+    12: { bc7: 6, via: "single" },
+    13: { bc7: 5, via: "dual" },
+    14: { bc7: 6, via: "single" },
+    15: { bc7: 6, via: "single" },
+    16: { bc7: 7, via: "two" },
+    17: { bc7: 5, via: "dual" },
+    18: { bc7: 6, via: "single" },
+};
+
+/**
+ * Transcode UASTC blocks to BC7.
+ *
+ * **Every UASTC mode is carried into the BC7 mode the specification pairs it with**, rather than
+ * decoded to texels and re-encoded. A UASTC block already *is* a partition, a pair of endpoints per
+ * subset and a weight per texel, which is exactly what BC7 stores — so the transcode is a change of
+ * representation and the only loss is endpoint precision. Re-fitting from texels instead costs
+ * around eighteen decibels on the dual plane modes and far more on the partitioned ones, because it
+ * throws away the answer the encoder already found.
+ *
+ * The pairings, all from the specification's mode table:
+ *
+ * | UASTC | BC7 | why |
+ * |---|---|---|
+ * | 0, 1, 5, 10, 12, 14, 15, 18 | 6 | one subset, one index set |
+ * | 8 | 6 | a solid colour, which BC7 has no mode for and mode 6 holds exactly |
+ * | 6, 11, 13, 17 | 5 | dual plane — one channel with its own weights, which BC7 spells as a rotation |
+ * | 2 | 1 | two subsets, three-bit weights |
+ * | 4 | 3 | two subsets, two-bit weights, seven-bit endpoints |
+ * | 9, 16 | 7 | two subsets with alpha |
+ * | 3 | 2 | three subsets |
+ * | 7 | 2 | two subsets in UASTC, three in BC7 — two of BC7's endpoint pairs are written alike |
+ *
+ * **The weights need no remapping.** ASTC's two- and three-bit weight tables are BC7's, and the
+ * four-bit ones agree too, so an index crosses over as itself. Where a UASTC mode's weight range is
+ * finer than the BC7 mode's index — only mode 18, at five bits — the nearest is taken.
+ *
+ * @param {Uint8Array} blocks UASTC blocks, tightly packed
+ * @param {number} block_count
+ * @returns {Uint8Array} tightly packed BC7 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function uastc_to_bc7(blocks, block_count) {
+    const out = new Uint8Array(block_count * BC7_BLOCK_BYTES);
+
+    const scratch = {
+        endpoints: new Uint8Array(3 * 2 * 4),
+        decoded: new Uint8Array(3 * 2 * 4),
+        parity: new Int8Array(6),
+        indices: new Uint8Array(16),
+        secondary_indices: new Uint8Array(16),
+        anchors: new Uint8Array(3),
+        subset_of_texel: new Uint8Array(16),
+        source_subset: new Uint8Array(3),
+    };
+
+    for (let block = 0; block < block_count; block++) {
+        const decoded = uastc_decode_block(blocks, block * UASTC_BLOCK_BYTES);
+
+        const mapping = MODE_MAP[decoded.mode];
+
+        if (mapping.via === "dual") {
+            write_dual_plane(out, block * BC7_BLOCK_BYTES, decoded, scratch);
+        } else if (mapping.via === "single") {
+            write_single_subset(out, block * BC7_BLOCK_BYTES, decoded, scratch);
+        } else {
+            write_partitioned(out, block * BC7_BLOCK_BYTES, decoded, mapping, scratch);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Map a UASTC weight index into a BC7 index of the given width.
+ *
+ * @param {number} index
+ * @param {number} weight_range
+ * @param {number} bits
+ * @returns {number}
+ */
+function map_index(index, weight_range, bits) {
+    const from = UASTC_WEIGHT_VALUE[weight_range];
+    const to = BC7_WEIGHTS[bits];
+
+    const weight = from[index];
+
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < to.length; i++) {
+        const error = Math.abs(to[i] - weight);
+
+        if (error < best_error) {
+            best_error = error;
+            best = i;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Quantise one subset's two endpoints, choosing the parity that suits them best.
+ *
+ * A parity bit is shared — by an endpoint's four channels, or by a subset's two endpoints — so it
+ * cannot be fitted per channel. Both values are tried and the one with less total error kept, which
+ * is what the specification means by an "optimal p-bit".
+ *
+ * @param {Uint8Array} source eight bytes, low then high RGBA
+ * @param {number} source_offset
+ * @param {Uint8Array} out stored fields, written
+ * @param {number} out_offset
+ * @param {Uint8Array} decoded what those fields decode to, written
+ * @param {Int8Array} parity written
+ * @param {number} parity_offset
+ * @param {Bc7Mode} spec
+ * @param {number} channels how many carry data — three where the mode has no alpha
+ */
+function quantise_subset(
+    source, source_offset, out, out_offset, decoded, parity, parity_offset, spec, channels
+) {
+    const per_endpoint = spec.endpoint_parity_bits > 0;
+    const shared = spec.shared_parity_bits > 0;
+
+    const color_width = spec.color_bits + (per_endpoint || shared ? 1 : 0);
+    const alpha_width = spec.alpha_bits + (per_endpoint || shared ? 1 : 0);
+
+    /**
+     * @param {number[]} candidate one parity per endpoint
+     * @returns {number} total squared error
+     */
+    const error_of = candidate => {
+        let total = 0;
+
+        for (let end = 0; end < 2; end++) {
+            for (let c = 0; c < channels; c++) {
+                const width = c === 3 ? alpha_width : color_width;
+
+                const value = source[source_offset + end * 4 + c];
+
+                const stored = bc7_quantise_endpoint(value, width, candidate[end]);
+
+                const delta = bc7_expand_endpoint(stored, width) - value;
+
+                total += delta * delta;
+            }
+        }
+
+        return total;
+    };
+
+    let chosen = [-1, -1];
+
+    if (per_endpoint) {
+        // one bit each, so the two endpoints are independent and each takes its own better value
+        for (let end = 0; end < 2; end++) {
+            chosen[end] = error_of_end(source, source_offset, end, 0, spec, channels)
+                <= error_of_end(source, source_offset, end, 1, spec, channels) ? 0 : 1;
+        }
+    } else if (shared) {
+        // one bit for the whole subset, so both endpoints have to agree
+        chosen = error_of([0, 0]) <= error_of([1, 1]) ? [0, 0] : [1, 1];
+    }
+
+    for (let end = 0; end < 2; end++) {
+        for (let c = 0; c < 4; c++) {
+            const width = c === 3 ? alpha_width : color_width;
+
+            if (c === 3 && spec.alpha_bits === 0) {
+                out[out_offset + end * 4 + c] = 0;
+                decoded[out_offset + end * 4 + c] = 255;
+
+                continue;
+            }
+
+            const value = source[source_offset + end * 4 + c];
+
+            const stored = bc7_quantise_endpoint(value, width, chosen[end]);
+
+            decoded[out_offset + end * 4 + c] = bc7_expand_endpoint(stored, width);
+
+            // the parity bit is carried separately, so the stored field is the rest
+            out[out_offset + end * 4 + c] = (per_endpoint || shared) ? stored >> 1 : stored;
+        }
+    }
+
+    if (per_endpoint) {
+        parity[parity_offset] = chosen[0];
+        parity[parity_offset + 1] = chosen[1];
+    } else if (shared) {
+        parity[parity_offset] = chosen[0];
+    }
+}
+
+/**
+ * Total squared error of one endpoint under a candidate parity.
+ *
+ * @param {Uint8Array} source
+ * @param {number} source_offset
+ * @param {number} end
+ * @param {number} parity
+ * @param {Bc7Mode} spec
+ * @param {number} channels
+ * @returns {number}
+ */
+function error_of_end(source, source_offset, end, parity, spec, channels) {
+    const color_width = spec.color_bits + 1;
+    const alpha_width = spec.alpha_bits + 1;
+
+    let total = 0;
+
+    for (let c = 0; c < channels; c++) {
+        const width = c === 3 ? alpha_width : color_width;
+
+        const value = source[source_offset + end * 4 + c];
+
+        const delta = bc7_expand_endpoint(bc7_quantise_endpoint(value, width, parity), width)
+            - value;
+
+        total += delta * delta;
+    }
+
+    return total;
+}
+
+/**
+ * Flip a subset's endpoints and invert its indices, so its anchor index fits the bit it is given.
+ *
+ * @param {Uint8Array} endpoints stored fields
+ * @param {Uint8Array} decoded
+ * @param {Int8Array} parity
+ * @param {number} subset
+ * @param {Bc7Mode} spec
+ * @param {Uint8Array} indices
+ * @param {Uint8Array} subset_of_texel
+ * @param {number} index_count
+ */
+function flip_subset(
+    endpoints, decoded, parity, subset, spec, indices, subset_of_texel, index_count
+) {
+    for (let c = 0; c < 4; c++) {
+        const low = (subset * 2) * 4 + c;
+        const high = (subset * 2 + 1) * 4 + c;
+
+        const swap = endpoints[low];
+
+        endpoints[low] = endpoints[high];
+        endpoints[high] = swap;
+
+        const swap_decoded = decoded[low];
+
+        decoded[low] = decoded[high];
+        decoded[high] = swap_decoded;
+    }
+
+    if (spec.endpoint_parity_bits > 0) {
+        const swap = parity[subset * 2];
+
+        parity[subset * 2] = parity[subset * 2 + 1];
+        parity[subset * 2 + 1] = swap;
+    }
+
+    for (let texel = 0; texel < 16; texel++) {
+        if (subset_of_texel[texel] === subset) {
+            indices[texel] = index_count - 1 - indices[texel];
+        }
+    }
+}
+
+/**
+ * Carry a partitioned block — two or three subsets — into its BC7 counterpart.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {UastcBlock} block
+ * @param {{bc7: number, via: string}} mapping
+ * @param {object} scratch
+ */
+function write_partitioned(out, offset, block, mapping, scratch) {
+    const spec = BC7_MODES[mapping.bc7];
+
+    const { endpoints, decoded, parity, indices, anchors, subset_of_texel, source_subset } = scratch;
+
+    /*
+     Which BC7 subset each texel lands in, and which UASTC subset each BC7 subset draws its endpoints
+     from. The two questions have different answers for mode 7, where BC7 has a subset UASTC does not
+     — two of its three endpoint pairs end up identical.
+    */
+    if (mapping.via === "single_as_two") {
+        /*
+         One UASTC subset written as two identical BC7 ones. Partition zero divides the block, and
+         giving both halves the same endpoints makes that division invisible — which is how a
+         one-subset block reaches a mode that has no one-subset form.
+        */
+        scratch.partition = 0;
+
+        subset_of_texel.set(BC7_PARTITIONS_2.subarray(0, 16));
+
+        source_subset[0] = 0;
+        source_subset[1] = 0;
+    } else if (mapping.via === "two") {
+        const { bc7, invert } = UASTC_TO_BC7_2[block.pattern];
+
+        scratch.partition = bc7;
+
+        for (let texel = 0; texel < 16; texel++) {
+            subset_of_texel[texel] = invert ? 1 - block.partition[texel] : block.partition[texel];
+        }
+
+        source_subset[0] = invert ? 1 : 0;
+        source_subset[1] = invert ? 0 : 1;
+    } else if (mapping.via === "three") {
+        const { bc7, permutation } = UASTC_TO_BC7_3[block.pattern];
+
+        scratch.partition = bc7;
+
+        const perm = SUBSET_PERMUTATIONS[permutation];
+
+        for (let texel = 0; texel < 16; texel++) {
+            subset_of_texel[texel] = perm[block.partition[texel]];
+        }
+
+        for (let s = 0; s < 3; s++) {
+            source_subset[perm[s]] = s;
+        }
+    } else {
+        const { bc7, fold } = UASTC_TO_BC7_2_VIA_3[block.pattern];
+
+        scratch.partition = bc7;
+
+        /*
+         BC7's three subsets fold onto UASTC's two, so two of them share a source — and writing the
+         same endpoints twice is exactly what makes a three-subset BC7 block describe two.
+        */
+        for (let s = 0; s < 3; s++) {
+            source_subset[s] = bc7_fold_subset_3_to_2(s, fold);
+        }
+
+        for (let texel = 0; texel < 16; texel++) {
+            // the BC7 pattern is the authority here; UASTC's is what it folds to
+            subset_of_texel[texel] = bc7_subset_of(bc7, texel);
+        }
+    }
+
+    /*
+     **The parity is chosen over the channels that carry something.** It is shared by an endpoint's
+     four, so choosing it by total error across all four lets a constant alpha outvote the colour —
+     and on an RGB source that alpha is 255 by construction, invented by the colour endpoint mode
+     rather than authored. Letting it vote costs 1.66 dB of colour on the photographic fixture, to
+     perfect a channel nothing reads: meep declares a texture's alpha mode rather than inferring it
+     from texels (§9.2), so an opaque source decoding to 254 changes no decision anywhere. The
+     reference transcoder makes the same trade.
+    */
+    const channels = (spec.alpha_bits > 0 && block.has_alpha) ? 4 : 3;
+
+    for (let s = 0; s < spec.subsets; s++) {
+        quantise_subset(
+            block.endpoints, source_subset[s] * 8,
+            endpoints, s * 8, decoded, parity, spec.endpoint_parity_bits > 0 ? s * 2 : s,
+            spec, channels
+        );
+    }
+
+    for (let texel = 0; texel < 16; texel++) {
+        indices[texel] = map_index(
+            block.weight_indices[texel], block.weight_range, spec.index_bits
+        );
+    }
+
+    anchors[0] = 0;
+
+    if (spec.subsets === 2) {
+        anchors[1] = BC7_ANCHOR_2[scratch.partition];
+    } else {
+        anchors[1] = BC7_ANCHOR_3_SECOND[scratch.partition];
+        anchors[2] = BC7_ANCHOR_3_THIRD[scratch.partition];
+    }
+
+    const index_count = 1 << spec.index_bits;
+
+    for (let s = 0; s < spec.subsets; s++) {
+        if (indices[anchors[s]] >= index_count / 2) {
+            flip_subset(
+                endpoints, decoded, parity, s, spec, indices, subset_of_texel, index_count
+            );
+        }
+    }
+
+    bc7_write_block(out, offset, mapping.bc7, {
+        partition: scratch.partition,
+        endpoints,
+        indices,
+        anchors,
+        parity,
+    });
+}
+
+/**
+ * Which BC7 three-subset subset a texel is in, for a given partition.
+ *
+ * @param {number} partition
+ * @param {number} texel
+ * @returns {number}
+ */
+function bc7_subset_of(partition, texel) {
+    return BC7_PARTITIONS_3[partition * 16 + texel];
+}
+
+/**
+ * Carry a single-subset block into BC7 mode 6.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {UastcBlock} block
+ * @param {object} scratch
+ */
+function write_single_subset(out, offset, block, scratch) {
+    const spec = BC7_MODES[6];
+
+    const { endpoints, decoded, parity, indices, anchors, subset_of_texel } = scratch;
+
+    subset_of_texel.fill(0);
+    quantise_subset(
+        block.endpoints, 0, endpoints, 0, decoded, parity, 0, spec, block.has_alpha ? 4 : 3
+    );
+
+    for (let texel = 0; texel < 16; texel++) {
+        indices[texel] = map_index(
+            block.weight_indices[texel], block.weight_range, spec.index_bits
+        );
+    }
+
+    anchors[0] = 0;
+
+    const index_count = 1 << spec.index_bits;
+
+    if (indices[0] >= index_count / 2) {
+        flip_subset(endpoints, decoded, parity, 0, spec, indices, subset_of_texel, index_count);
+    }
+
+    bc7_write_block(out, offset, 6, { endpoints, indices, anchors, parity });
+}
+
+/**
+ * Carry a dual plane block into BC7 mode 5.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {UastcBlock} block
+ * @param {object} scratch
+ */
+function write_dual_plane(out, offset, block, scratch) {
+    const spec = BC7_MODES[5];
+
+    const {
+        endpoints, decoded, parity, indices, secondary_indices, anchors, subset_of_texel,
+    } = scratch;
+
+    subset_of_texel.fill(0);
+
+    const selector = block.component_selector;
+
+    /*
+     BC7 always interpolates *alpha* with the second index set, so the channel ASTC nominated is
+     swapped into alpha's place — endpoints included — and the rotation tells the decoder to swap it
+     back. This is the one place the two formats disagree about dual planes rather than merely
+     spelling them differently.
+    */
+    const source = new Uint8Array(8);
+
+    source.set(block.endpoints.subarray(0, 8));
+
+    if (selector !== 3) {
+        for (let end = 0; end < 2; end++) {
+            const swap = source[end * 4 + selector];
+
+            source[end * 4 + selector] = source[end * 4 + 3];
+            source[end * 4 + 3] = swap;
+        }
+    }
+
+    quantise_subset(source, 0, endpoints, 0, decoded, parity, 0, spec, 4);
+
+    for (let texel = 0; texel < 16; texel++) {
+        indices[texel] = map_index(
+            block.weight_indices[texel * 2], block.weight_range, spec.index_bits
+        );
+
+        secondary_indices[texel] = map_index(
+            block.weight_indices[texel * 2 + 1], block.weight_range, spec.secondary_index_bits
+        );
+    }
+
+    anchors[0] = 0;
+
+    const index_count = 1 << spec.index_bits;
+
+    /*
+     Mode 5's two index sets each have their own anchor, and flipping one must not disturb the other
+     — the colour flip swaps only the three colour channels and the alpha flip only alpha.
+    */
+    if (indices[0] >= index_count / 2) {
+        for (let c = 0; c < 3; c++) {
+            const swap = endpoints[c];
+
+            endpoints[c] = endpoints[4 + c];
+            endpoints[4 + c] = swap;
+        }
+
+        for (let texel = 0; texel < 16; texel++) {
+            indices[texel] = index_count - 1 - indices[texel];
+        }
+    }
+
+    if (secondary_indices[0] >= index_count / 2) {
+        const swap = endpoints[3];
+
+        endpoints[3] = endpoints[7];
+        endpoints[7] = swap;
+
+        for (let texel = 0; texel < 16; texel++) {
+            secondary_indices[texel] = index_count - 1 - secondary_indices[texel];
+        }
+    }
+
+    bc7_write_block(out, offset, 5, {
+        rotation: selector + 1,
+        endpoints,
+        indices,
+        secondary_indices,
+        anchors,
+        parity,
+    });
+}

package/src/format/texture/basis/uastc/uastc_to_rgba8.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Decode UASTC to plain 8-bit RGBA texels.
+ *
+ * **The path for a device that can sample no compressed format at all**, and the only one here that
+ * loses nothing: {@link uastc_decode_block} already produces the block's exact texels, and the BC7
+ * and BC5 targets beside this one then *re-encode* them into a different block format. This one
+ * simply stops there, so what it writes is what the encoder put in — an odd inversion, in that the
+ * fallback for the weakest devices is the highest-fidelity thing this file can produce, at four
+ * bytes a texel rather than one.
+ *
+ * See {@link etc1s_to_rgba8} for why an uncompressed target has to exist at all: WebGPU guarantees
+ * no compressed format, so every one of them is a feature that can be absent.
+ *
+ * **Cropped to the image, not to the block grid.** A block format's level is a whole number of
+ * blocks and the format table sizes it that way, so a 100x60 texture stores 25x15 blocks and the
+ * padding is simply never sampled. `rgba8unorm` has no such slack — its level is exactly
+ * `width * height * 4` — so the partial blocks along the right and bottom edges are written only as
+ * far as the image goes.
+ *
+ * **Do not remove the two bounds checks below on the grounds that a test still passes.** They are
+ * unobservable, and only by accident: a write past the right edge of row `y` lands at the start of
+ * row `y + 1` because the index is row-major, and row `y + 1` is written afterwards and overwrites
+ * it. The one spill nothing corrects runs past the end of the buffer, where a typed array silently
+ * drops it. So the output is the same either way, and it is the same for reasons that hold only
+ * while the iteration order does — reorder the loops and the coincidence stops covering.
+ *
+ * @param {Uint8Array} blocks UASTC blocks, tightly packed
+ * @param {number} block_count
+ * @param {number} width in texels
+ * @param {number} height in texels
+ * @returns {Uint8Array} `width * height * 4` bytes, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function uastc_to_rgba8(blocks: Uint8Array, block_count: number, width: number, height: number): Uint8Array;
+//# sourceMappingURL=uastc_to_rgba8.d.ts.map

package/src/format/texture/basis/uastc/uastc_to_rgba8.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uastc_to_rgba8.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/uastc/uastc_to_rgba8.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,uCATW,UAAU,eACV,MAAM,SACN,MAAM,UACN,MAAM,GACJ,UAAU,CA8CtB"}