@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,297 @@
+/**
+ * How many refine-and-reassign rounds to run.
+ *
+ * **Measured, not guessed.** Two rounds give bit-identical output to eight on every fixture in
+ * `__fixtures__`; one does not. Three is that plus a round of margin, since six files are not proof
+ * about every file. It is a ceiling rather than a cost — the loop leaves as soon as a round moves
+ * nothing — but the ceiling was reached often enough to matter: at eight, a 1024x1024 texture spent
+ * 162 ms transcoding to BC7 and 511 ms to BC1, against 127 ms and 389 ms here, for the same texels.
+ *
+ * @readonly
+ * @type {number}
+ */
+const MAX_ITERATIONS = 3;
+
+/**
+ * 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 = [
+    [0, 0], [0, 1], [0, 2], [0, 3],
+    [1, 1], [1, 2], [1, 3],
+    [2, 2], [2, 3],
+    [3, 3],
+];
+
+/**
+ * Which entry of {@link SELECTOR_RANGES} a `[min, max]` span is.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function selector_range_index(min, max) {
+    for (let i = 0; i < SELECTOR_RANGES.length; i++) {
+        if (SELECTOR_RANGES[i][0] === min && SELECTOR_RANGES[i][1] === max) {
+            return i;
+        }
+    }
+
+    throw new Error(`Basis: ${min}..${max} is not a selector range`);
+}
+
+/**
+ * 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. This is the part that matters.** 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.
+ *
+ * The two halves are worth very different amounts, and it is worth knowing which is which before
+ * anyone simplifies one of them away. Measured on the noise fixture: **conditioning on the span is
+ * worth about 9 dB for BC7 and 6 dB for BC1**, and dropping it takes the worst channel error from 2
+ * to 30. The least-squares solve on top of it is worth **0 to 1 dB** — nothing at all on that
+ * fixture, about a decibel on the harder mip levels of the gradient and the non-power-of-two file.
+ * It stays because it is cheap beside the template build and because those levels are real, not
+ * because it is what closes the gap to the reference transcoder.
+ *
+ * @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, high, colors, weights, min_selector, max_selector) {
+    if (min_selector === max_selector) {
+        /*
+         One colour, and both endpoints are it — every weight then interpolates to the same value, so
+         there is nothing to solve and the normal equations below would be singular anyway.
+        */
+        for (let c = 0; c < 3; c++) {
+            low[c] = colors[min_selector * 3 + c];
+            high[c] = colors[min_selector * 3 + c];
+        }
+
+        return;
+    }
+
+    const assigned = new Int32Array(4);
+
+    for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+        for (let selector = min_selector; selector <= max_selector; selector++) {
+            assigned[selector] = nearest_weight(low, high, weights, colors, selector * 3);
+        }
+
+        let sum_aa = 0;
+        let sum_ab = 0;
+        let sum_bb = 0;
+
+        for (let selector = min_selector; selector <= max_selector; selector++) {
+            const b = weights[assigned[selector]] / 64;
+            const a = 1 - b;
+
+            sum_aa += a * a;
+            sum_ab += a * b;
+            sum_bb += b * b;
+        }
+
+        const determinant = sum_aa * sum_bb - sum_ab * sum_ab;
+
+        // singular when every colour in the span was assigned the same weight; the fit is done
+        if (Math.abs(determinant) < 1e-6) {
+            return;
+        }
+
+        let moved = false;
+
+        for (let c = 0; c < 3; c++) {
+            let sum_ap = 0;
+            let sum_bp = 0;
+
+            for (let selector = min_selector; selector <= max_selector; selector++) {
+                const b = weights[assigned[selector]] / 64;
+                const a = 1 - b;
+                const p = colors[selector * 3 + c];
+
+                sum_ap += a * p;
+                sum_bp += b * p;
+            }
+
+            const solved_low = (sum_bb * sum_ap - sum_ab * sum_bp) / determinant;
+            const solved_high = (sum_aa * sum_bp - sum_ab * sum_ap) / determinant;
+
+            const next_low = clamp_round(solved_low);
+            const next_high = clamp_round(solved_high);
+
+            if (next_low !== low[c] || next_high !== high[c]) {
+                moved = true;
+            }
+
+            low[c] = next_low;
+            high[c] = next_high;
+        }
+
+        if (!moved) {
+            return;
+        }
+    }
+}
+
+/**
+ * Solve for the endpoint pair that best reproduces a span of colours, given which weight each is to
+ * be reproduced at.
+ *
+ * Separated from {@link fit_endpoints} because the assignment is not always worth searching for
+ * greedily. A format with few weights — BC1 has four — is better served by trying every sensible
+ * assignment and solving each, since the best one routinely places both endpoints *outside* the
+ * colours they encode. Three evenly spaced colours are the standard case: no pair of endpoints has
+ * them at weights 0, something, and 64, but a pair extended past both ends puts them at 64, 43 and
+ * 21 almost exactly.
+ *
+ * @param {Uint8Array} low three channels, overwritten
+ * @param {Uint8Array} high three channels, overwritten
+ * @param {Uint8Array} colors twelve bytes
+ * @param {Int32Array} weight_of_selector the weight each selector is to be reproduced at, out of 64
+ * @param {number} min_selector
+ * @param {number} max_selector
+ * @returns {boolean} whether a solution exists — it does not when every colour was given the same
+ * weight, which says nothing about where the endpoints are
+ */
+export function solve_endpoints(low, high, colors, weight_of_selector, min_selector, max_selector) {
+    let sum_aa = 0;
+    let sum_ab = 0;
+    let sum_bb = 0;
+
+    for (let selector = min_selector; selector <= max_selector; selector++) {
+        const b = weight_of_selector[selector] / 64;
+        const a = 1 - b;
+
+        sum_aa += a * a;
+        sum_ab += a * b;
+        sum_bb += b * b;
+    }
+
+    const determinant = sum_aa * sum_bb - sum_ab * sum_ab;
+
+    if (Math.abs(determinant) < 1e-6) {
+        return false;
+    }
+
+    for (let c = 0; c < 3; c++) {
+        let sum_ap = 0;
+        let sum_bp = 0;
+
+        for (let selector = min_selector; selector <= max_selector; selector++) {
+            const b = weight_of_selector[selector] / 64;
+            const a = 1 - b;
+            const p = colors[selector * 3 + c];
+
+            sum_ap += a * p;
+            sum_bp += b * p;
+        }
+
+        low[c] = clamp_round((sum_bb * sum_ap - sum_ab * sum_bp) / determinant);
+        high[c] = clamp_round((sum_aa * sum_bp - sum_ab * sum_ap) / determinant);
+    }
+
+    return true;
+}
+
+/**
+ * @param {number} value
+ * @returns {number} rounded into `[0, 255]`
+ */
+function clamp_round(value) {
+    const rounded = Math.round(value);
+
+    return rounded < 0 ? 0 : rounded > 255 ? 255 : rounded;
+}
+
+/**
+ * Which weight puts the interpolated colour closest to a target.
+ *
+ * @param {Uint8Array} low three channels
+ * @param {Uint8Array} high three channels
+ * @param {Int32Array} weights
+ * @param {Uint8Array} target
+ * @param {number} target_offset
+ * @returns {number} an index into `weights`
+ */
+function nearest_weight(low, high, weights, target, target_offset) {
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < weights.length; i++) {
+        const weight = weights[i];
+
+        let error = 0;
+
+        for (let c = 0; c < 3; c++) {
+            const interpolated = (low[c] * (64 - weight) + high[c] * weight + 32) >> 6;
+            const delta = interpolated - target[target_offset + c];
+
+            error += delta * delta;
+        }
+
+        if (error < best_error) {
+            best_error = error;
+            best = i;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * 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) {
+    const out = new Uint8Array(selectors.count);
+
+    for (let entry = 0; entry < selectors.count; entry++) {
+        let min = 3;
+        let max = 0;
+
+        for (let i = 0; i < 16; i++) {
+            const selector = selectors.selectors[entry * 16 + i];
+
+            if (selector < min) {
+                min = selector;
+            }
+
+            if (selector > max) {
+                max = selector;
+            }
+        }
+
+        out[entry] = selector_range_index(min, max);
+    }
+
+    return out;
+}

package/src/format/texture/basis/transcode_basis.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Whether a target this transcoder writes has somewhere to put an alpha channel.
+ *
+ * **Asked before a target is chosen, not after.** An ETC1S payload's alpha lives in a second slice,
+ * and a target with only three channels cannot hold it — `transcode_basis` refuses that pair rather
+ * than dropping the alpha silently. But the refusal arrives after a caller has already committed to
+ * a format, which is too late to pick a different one, so a caller choosing between several needs to
+ * ask first. `ktx2_read` does, because the container's own descriptor says whether there is alpha.
+ *
+ * @param {TextureFormat} format
+ * @returns {boolean} false for a format this does not write at all
+ */
+export function transcode_basis_carries_alpha(format: TextureFormat): boolean;
+/**
+ * Every format {@link transcode_basis} can write, best first.
+ *
+ * The asset layer's half of §3.5: `texture_format_preference` says what would be good for a role,
+ * and this says what can actually be produced. Intersecting the two is how a caller chooses, and
+ * neither list is any use without the other.
+ *
+ * The sRGB spellings are left out — they are the same blocks, and which one a texture is created
+ * with is decided from the image's colour space rather than chosen here.
+ *
+ * @returns {TextureFormat[]}
+ */
+export function transcode_basis_formats(): TextureFormat[];
+/**
+ * Transcode a Basis Universal ETC1S payload into texels a device can sample.
+ *
+ * **Bytes in, texels out. No device, no queue, no engine.** The same function serves a worker, a
+ * node tool and the offline encoder, and what it produces is a {@link TexelPayload} — a transcoded
+ * texture enters the engine through the same door as one that arrived already in a device format,
+ * and nothing below `ShadeImage` can tell the difference.
+ *
+ * **This is the compatibility path, not the delivery path.** It exists because `KHR_texture_basisu`
+ * is what the web's model pipeline emits and a viewer that cannot read it cannot read the
+ * ecosystem's models. First-party content is encoded to a device format up front and never comes
+ * through here; transcoding pays CPU time on load to recover a format the device could have been
+ * handed directly. Treat a call to this as a cost, not as the fast path.
+ *
+ * **Choosing `target_format` is the caller's job**, from `texture_format_preference(role, support)`
+ * — what is good depends on the device and on which material slot the image fills, and neither is
+ * knowable here. There is no default: a transcoder that guessed would be choosing a texture's
+ * encoding on the strength of nothing.
+ *
+ * **UASTC is not transcoded.** It is the other Basis encoding, a different bitstream, and it is
+ * refused by name where the payload is read rather than half-decoded here.
+ *
+ * @param {BasisEtc1sPayload} payload
+ * @param {TextureFormat} target_format
+ * @returns {TexelPayload}
+ * @throws {Error} naming the format, for a target this cannot write; naming the field, for a payload
+ * that is malformed or self-inconsistent
+ *
+ * @see the Basis Universal specification, sections 6 to 11
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function transcode_basis(payload: BasisEtc1sPayload, target_format: TextureFormat): TexelPayload;
+/**
+ * What a container hands the transcoder: an ETC1S payload, extracted but not decoded.
+ *
+ * Container-shaped only in that somebody had to find these bytes. A `.basis` reader would build the
+ * same thing from a different file layout, which is the point of the type existing at all.
+ */
+export type BasisEtc1sPayload = {
+    /**
+     * texels, base level
+     */
+    width: number;
+    /**
+     * texels, base level
+     */
+    height: number;
+    /**
+     * whether every image carries a second slice holding alpha
+     */
+    has_alpha: boolean;
+    /**
+     * entries in the endpoint codebook
+     */
+    endpoint_count: number;
+    /**
+     * entries in the selector codebook
+     */
+    selector_count: number;
+    /**
+     * the compressed endpoint codebook
+     */
+    endpoints: Uint8Array;
+    /**
+     * the compressed selector codebook
+     */
+    selectors: Uint8Array;
+    /**
+     * the compressed slice-decoding Huffman tables
+     */
+    tables: Uint8Array;
+    /**
+     * one per mip level, base
+     * first
+     */
+    images: {
+        rgb: Uint8Array;
+        alpha: (Uint8Array | undefined);
+    }[];
+};
+import { TextureFormat } from "../../../shade/descriptor/texture/format/TextureFormat.js";
+//# sourceMappingURL=transcode_basis.d.ts.map

package/src/format/texture/basis/transcode_basis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcode_basis.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/basis/transcode_basis.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;GAWG;AACH,sDAHW,aAAa,GACX,OAAO,CAInB;AAED;;;;;;;;;;;GAWG;AACH,2CAFa,aAAa,EAAE,CAW3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCAVW,iBAAiB,iBACjB,aAAa,GACX,YAAY,CA2ExB;;;;;;;;;;;WAtMa,MAAM;;;;YACN,MAAM;;;;eACN,OAAO;;;;oBACP,MAAM;;;;oBACN,MAAM;;;;eACN,UAAU;;;;eACV,UAAU;;;;YACV,UAAU;;;;;YACV;QAAC,GAAG,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,CAAC,UAAU,GAAC,SAAS,CAAC,CAAA;KAAC,EAAE;;8BArClC,2DAA2D"}

package/src/format/texture/basis/transcode_basis.js

@@ -0,0 +1,250 @@
+import { TextureFormat } from "../../../shade/descriptor/texture/format/TextureFormat.js";
+import { etc1s_to_astc } from "./transcode/etc1s_to_astc.js";
+import { etc1s_to_etc2 } from "./transcode/etc1s_to_etc2.js";
+import { etc1s_to_rgba8 } from "./transcode/etc1s_to_rgba8.js";
+import { texture_mip_size } from "../../../shade/util/texture_mip_extent.js";
+import { etc1s_decode_slice } from "./etc1s/etc1s_decode_slice.js";
+import { etc1s_read_endpoint_codebook } from "./etc1s/etc1s_read_endpoint_codebook.js";
+import { etc1s_read_selector_codebook } from "./etc1s/etc1s_read_selector_codebook.js";
+import { etc1s_read_slice_tables } from "./etc1s/etc1s_read_slice_tables.js";
+import { etc1s_to_bc1 } from "./transcode/etc1s_to_bc1.js";
+import { etc1s_to_bc7 } from "./transcode/etc1s_to_bc7.js";
+
+/**
+ * Texels an ETC1S block covers, in each direction. Fixed by the format, and the same as every block
+ * format this transcodes to — which is why a slice's block grid is the destination's block grid and
+ * no resampling happens anywhere below.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ETC1S_BLOCK_SIZE = 4;
+
+/**
+ * What a container hands the transcoder: an ETC1S payload, extracted but not decoded.
+ *
+ * Container-shaped only in that somebody had to find these bytes. A `.basis` reader would build the
+ * same thing from a different file layout, which is the point of the type existing at all.
+ *
+ * @typedef {object} BasisEtc1sPayload
+ * @property {number} width texels, base level
+ * @property {number} height texels, base level
+ * @property {boolean} has_alpha whether every image carries a second slice holding alpha
+ * @property {number} endpoint_count entries in the endpoint codebook
+ * @property {number} selector_count entries in the selector codebook
+ * @property {Uint8Array} endpoints the compressed endpoint codebook
+ * @property {Uint8Array} selectors the compressed selector codebook
+ * @property {Uint8Array} tables the compressed slice-decoding Huffman tables
+ * @property {{rgb: Uint8Array, alpha: (Uint8Array|undefined)}[]} images one per mip level, base
+ * first
+ */
+
+
+/**
+ * The two ETC2 spellings {@link etc1s_to_etc2} serves, as the table's uniform writer signature.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} alpha_slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @param {number} width
+ * @param {number} height
+ * @returns {Uint8Array}
+ */
+function write_etc2_rgb(slice, alpha_slice, endpoints, selectors, width, height) {
+    return etc1s_to_etc2(slice, alpha_slice, endpoints, selectors, width, height, false);
+}
+
+/**
+ * @see write_etc2_rgb
+ * @returns {Uint8Array}
+ */
+function write_etc2_rgba(slice, alpha_slice, endpoints, selectors, width, height) {
+    return etc1s_to_etc2(slice, alpha_slice, endpoints, selectors, width, height, true);
+}
+
+/**
+ * Which formats this transcodes to, and what writes each one.
+ *
+ * A table rather than a switch so the refusal below can list what is available by name — a caller
+ * that asked for ASTC should be told what it could have asked for instead.
+ *
+ * @readonly
+ * @type {Object<TextureFormat, {write: Function, carries_alpha: boolean}>}
+ */
+const TARGETS = {
+    [TextureFormat.BC7_RGBA_UNORM]: { write: write_bc7, carries_alpha: true },
+    [TextureFormat.BC7_RGBA_UNORM_SRGB]: { write: write_bc7, carries_alpha: true },
+    [TextureFormat.BC1_RGBA_UNORM]: { write: write_bc1, carries_alpha: false },
+    [TextureFormat.BC1_RGBA_UNORM_SRGB]: { write: write_bc1, carries_alpha: false },
+    [TextureFormat.ASTC_4X4_UNORM]: { write: etc1s_to_astc, carries_alpha: false },
+    [TextureFormat.ASTC_4X4_UNORM_SRGB]: { write: etc1s_to_astc, carries_alpha: false },
+    [TextureFormat.ETC2_RGB8UNORM]: { write: write_etc2_rgb, carries_alpha: false },
+    [TextureFormat.ETC2_RGB8UNORM_SRGB]: { write: write_etc2_rgb, carries_alpha: false },
+    [TextureFormat.ETC2_RGBA8UNORM]: { write: write_etc2_rgba, carries_alpha: true },
+    [TextureFormat.ETC2_RGBA8UNORM_SRGB]: { write: write_etc2_rgba, carries_alpha: true },
+    [TextureFormat.RGBA8UNORM]: { write: etc1s_to_rgba8, carries_alpha: true },
+    [TextureFormat.RGBA8UNORM_SRGB]: { write: etc1s_to_rgba8, carries_alpha: true },
+};
+
+/**
+ * Whether a target this transcoder writes has somewhere to put an alpha channel.
+ *
+ * **Asked before a target is chosen, not after.** An ETC1S payload's alpha lives in a second slice,
+ * and a target with only three channels cannot hold it — `transcode_basis` refuses that pair rather
+ * than dropping the alpha silently. But the refusal arrives after a caller has already committed to
+ * a format, which is too late to pick a different one, so a caller choosing between several needs to
+ * ask first. `ktx2_read` does, because the container's own descriptor says whether there is alpha.
+ *
+ * @param {TextureFormat} format
+ * @returns {boolean} false for a format this does not write at all
+ */
+export function transcode_basis_carries_alpha(format) {
+    return TARGETS[format]?.carries_alpha === true;
+}
+
+/**
+ * Every format {@link transcode_basis} can write, best first.
+ *
+ * The asset layer's half of §3.5: `texture_format_preference` says what would be good for a role,
+ * and this says what can actually be produced. Intersecting the two is how a caller chooses, and
+ * neither list is any use without the other.
+ *
+ * The sRGB spellings are left out — they are the same blocks, and which one a texture is created
+ * with is decided from the image's colour space rather than chosen here.
+ *
+ * @returns {TextureFormat[]}
+ */
+export function transcode_basis_formats() {
+    return [
+        TextureFormat.BC7_RGBA_UNORM,
+        TextureFormat.ASTC_4X4_UNORM,
+        TextureFormat.ETC2_RGBA8UNORM,
+        TextureFormat.BC1_RGBA_UNORM,
+        TextureFormat.ETC2_RGB8UNORM,
+        TextureFormat.RGBA8UNORM,
+    ];
+}
+
+/**
+ * Transcode a Basis Universal ETC1S payload into texels a device can sample.
+ *
+ * **Bytes in, texels out. No device, no queue, no engine.** The same function serves a worker, a
+ * node tool and the offline encoder, and what it produces is a {@link TexelPayload} — a transcoded
+ * texture enters the engine through the same door as one that arrived already in a device format,
+ * and nothing below `ShadeImage` can tell the difference.
+ *
+ * **This is the compatibility path, not the delivery path.** It exists because `KHR_texture_basisu`
+ * is what the web's model pipeline emits and a viewer that cannot read it cannot read the
+ * ecosystem's models. First-party content is encoded to a device format up front and never comes
+ * through here; transcoding pays CPU time on load to recover a format the device could have been
+ * handed directly. Treat a call to this as a cost, not as the fast path.
+ *
+ * **Choosing `target_format` is the caller's job**, from `texture_format_preference(role, support)`
+ * — what is good depends on the device and on which material slot the image fills, and neither is
+ * knowable here. There is no default: a transcoder that guessed would be choosing a texture's
+ * encoding on the strength of nothing.
+ *
+ * **UASTC is not transcoded.** It is the other Basis encoding, a different bitstream, and it is
+ * refused by name where the payload is read rather than half-decoded here.
+ *
+ * @param {BasisEtc1sPayload} payload
+ * @param {TextureFormat} target_format
+ * @returns {TexelPayload}
+ * @throws {Error} naming the format, for a target this cannot write; naming the field, for a payload
+ * that is malformed or self-inconsistent
+ *
+ * @see the Basis Universal specification, sections 6 to 11
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function transcode_basis(payload, target_format) {
+    const target = TARGETS[target_format];
+
+    if (target === undefined) {
+        throw new Error(
+            `Basis: '${target_format}' is not a format this transcoder writes. It writes`
+            + ` ${Object.keys(TARGETS).map(name => `'${name}'`).join(", ")}.`
+        );
+    }
+
+    if (payload.has_alpha && !target.carries_alpha) {
+        /*
+         Refused rather than silently dropped. A payload with alpha slices has alpha because
+         something needed it, and a texture that arrives opaque is a bug that surfaces as a
+         cutout that does not cut out — far from here, and long after.
+        */
+        throw new Error(
+            `Basis: the payload carries alpha and '${target_format}' has no alpha channel to put it`
+            + ` in. Ask for a format that does — 'bc7-rgba-unorm' is the one this transcoder writes.`
+        );
+    }
+
+    const endpoints = etc1s_read_endpoint_codebook(payload.endpoints, payload.endpoint_count);
+    const selectors = etc1s_read_selector_codebook(payload.selectors, payload.selector_count);
+    const tables = etc1s_read_slice_tables(payload.tables);
+
+    const levels = payload.images.map((image, level) => {
+        const width = texture_mip_size(payload.width, level);
+        const height = texture_mip_size(payload.height, level);
+
+        const blocks_x = Math.ceil(width / ETC1S_BLOCK_SIZE);
+        const blocks_y = Math.ceil(height / ETC1S_BLOCK_SIZE);
+
+        const slice = etc1s_decode_slice(
+            image.rgb, blocks_x, blocks_y, tables, payload.endpoint_count, payload.selector_count
+        );
+
+        const alpha_slice = image.alpha === undefined
+            ? undefined
+            : etc1s_decode_slice(
+                image.alpha, blocks_x, blocks_y, tables,
+                payload.endpoint_count, payload.selector_count
+            );
+
+        /*
+         `width` and `height` matter only to the uncompressed target, whose level is exactly
+         `width * height * 4` — a block writer's level is a whole number of blocks and it reads the
+         grid off the slice. Passed to both rather than branching, since a writer is free to ignore
+         what it does not need.
+        */
+        return target.write(slice, alpha_slice, endpoints, selectors, width, height);
+    });
+
+    /*
+     Not re-measured: each writer emitted a whole number of blocks for the grid it was handed, so a
+     level is the right size by construction. `ShadeTexelData` checks it again against the format
+     table when the engine takes the payload in, which is the one place a disagreement could matter.
+    */
+    return {
+        format: target_format,
+        width: payload.width,
+        height: payload.height,
+        depth: 1,
+        layers: 1,
+        faces: 1,
+        levels
+    };
+}
+
+/**
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} alpha_slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array}
+ */
+function write_bc7(slice, alpha_slice, endpoints, selectors) {
+    return etc1s_to_bc7(slice, alpha_slice, endpoints, selectors);
+}
+
+/**
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} alpha_slice unused — a payload with alpha is refused above
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array}
+ */
+function write_bc1(slice, alpha_slice, endpoints, selectors) {
+    return etc1s_to_bc1(slice, endpoints, selectors);
+}