@driftengine/assets 4.8.7 → 4.10.0

package/dist/etc2Encode.js

@@ -0,0 +1,531 @@
+/**
+ * ETC2 and EAC blocks made from pixels: what a phone samples, at half a byte a texel for colour and
+ * a byte with alpha, where RGBA costs four. The loader encodes a texture this way where the device
+ * takes ETC2 and not the BC its file holds (`etc2Plan`), and a caller holding pixels of its own can
+ * call `encodeEtc2` directly — off the main thread, since a 2048² image is 262,144 blocks.
+ *
+ * **ETC2's colour, through the modes it shares with ETC1**: each 4x4 block split in two halves,
+ * side by side or one above the other, each half a base colour and one of eight tables of
+ * brightness steps, each texel the step nearest its own colour. Both splits and both ways of storing
+ * the two bases — each on its own at four bits, or the second as a small difference from the first
+ * at five — are tried, and the least error kept. **What it gives up** is ETC2's three further modes,
+ * T, H and planar, which every ETC2 device decodes and this encoder never chooses: a smooth gradient
+ * across a block and a sharp edge between two colours come out a little coarser than a full search
+ * would make them. What would make that worth changing is a texture whose banding shows at the size
+ * it is seen.
+ *
+ * **EAC for everything that is not colour**: an alpha channel beside ETC2's colour, and one or two
+ * channels of data on their own (`eac-r11`, `eac-rg11`) — a roughness map, a normal map's x and y.
+ * Each block a base, a step size and one of sixteen tables of eight steps, searched per table.
+ *
+ * Texels past the edge of a level smaller than a block repeat the last row and column, so a 2x2 or
+ * 1x1 level is one block whose other texels match. Allocates the blocks it returns, once a level.
+ */
+/** ETC1's eight tables of brightness steps: the small and the large, each added and subtracted. */
+const STEPS = [
+    [2, 8],
+    [5, 17],
+    [9, 29],
+    [13, 42],
+    [18, 60],
+    [24, 80],
+    [33, 106],
+    [47, 183],
+];
+/** A texel's step by its two-bit index: the small added, the large added, then both subtracted. */
+function step(table, index) {
+    const [small, large] = STEPS[table];
+    return index === 0 ? small : index === 1 ? large : index === 2 ? -small : -large;
+}
+/** EAC's sixteen tables of eight steps. */
+const EAC = [
+    [-3, -6, -9, -15, 2, 5, 8, 14],
+    [-3, -7, -10, -13, 2, 6, 9, 12],
+    [-2, -5, -8, -13, 1, 4, 7, 12],
+    [-2, -4, -6, -13, 1, 3, 5, 12],
+    [-3, -6, -8, -12, 2, 5, 7, 11],
+    [-3, -7, -9, -11, 2, 6, 8, 10],
+    [-4, -7, -8, -11, 3, 6, 7, 10],
+    [-3, -5, -8, -11, 2, 4, 7, 10],
+    [-2, -6, -8, -10, 1, 5, 7, 9],
+    [-2, -5, -8, -10, 1, 4, 7, 9],
+    [-2, -4, -8, -10, 1, 3, 7, 9],
+    [-2, -5, -7, -10, 1, 4, 6, 9],
+    [-3, -4, -7, -10, 2, 3, 6, 9],
+    [-1, -2, -3, -10, 0, 1, 2, 9],
+    [-4, -6, -8, -9, 3, 5, 7, 8],
+    [-3, -5, -7, -9, 2, 4, 6, 8],
+];
+/** Per EAC table, the index of the step nearest each whole offset from -16 to 15. */
+const NEAREST = EAC.map((steps) => {
+    const lookup = new Int8Array(32);
+    for (let u = -16; u < 16; u++) {
+        let chosen = 0;
+        for (let index = 1; index < 8; index++) {
+            if (Math.abs(steps[index] - u) < Math.abs(steps[chosen] - u)) {
+                chosen = index;
+            }
+        }
+        lookup[u + 16] = chosen;
+    }
+    return lookup;
+});
+/** Bytes a block of each format takes. */
+const BYTES = {
+    'etc2-rgb8': 8,
+    'etc2-rgba8': 16,
+    'eac-r11': 8,
+    'eac-rg11': 16,
+};
+const clamp255 = (v) => (v < 0 ? 0 : v > 255 ? 255 : v);
+/** One block's texels, RGBA, in ETC's own order: down each column, then across. */
+const texels = new Int32Array(64);
+/** `rgba` at `width` by `height` as `format` blocks, row of blocks after row of blocks. */
+export function encodeEtc2(format, rgba, width, height) {
+    const across = Math.max(1, Math.ceil(width / 4));
+    const down = Math.max(1, Math.ceil(height / 4));
+    const bytes = BYTES[format];
+    const out = new Uint8Array(across * down * bytes);
+    for (let by = 0; by < down; by++) {
+        for (let bx = 0; bx < across; bx++) {
+            gather(rgba, width, height, bx * 4, by * 4);
+            const at = (by * across + bx) * bytes;
+            if (format === 'etc2-rgb8')
+                encodeColour(out, at);
+            else if (format === 'etc2-rgba8') {
+                encodeEac(out, at, 3, false);
+                encodeColour(out, at + 8);
+            }
+            else if (format === 'eac-r11')
+                encodeEac(out, at, 0, true);
+            else {
+                encodeEac(out, at, 0, true);
+                encodeEac(out, at + 8, 1, true);
+            }
+        }
+    }
+    return out;
+}
+/** The block at `(x0, y0)` into `texels`, the edge repeated past a level smaller than a block. */
+function gather(rgba, width, height, x0, y0) {
+    for (let x = 0; x < 4; x++) {
+        for (let y = 0; y < 4; y++) {
+            const sx = Math.min(x0 + x, width - 1);
+            const sy = Math.min(y0 + y, height - 1);
+            const from = (sy * width + sx) * 4;
+            const to = (x * 4 + y) * 4;
+            texels[to] = rgba[from];
+            texels[to + 1] = rgba[from + 1];
+            texels[to + 2] = rgba[from + 2];
+            texels[to + 3] = rgba[from + 3];
+        }
+    }
+}
+/** Whether texel `i` (ETC order) is in the first half, for a split `flip` names. */
+const firstHalf = (i, flip) => (flip === 0 ? i < 8 : i % 4 < 2);
+/** The eight texels of each half: `HALF_TEXELS[flip * 2 + half]`. */
+const HALF_TEXELS = [0, 1, 2, 3].map((k) => {
+    const list = new Int32Array(8);
+    let count = 0;
+    for (let i = 0; i < 16; i++) {
+        if (firstHalf(i, k >> 1) === ((k & 1) === 0))
+            list[count++] = i;
+    }
+    return list;
+});
+/** Each table's small and large step, as numbers the search reads without unpacking a pair. */
+const SMALL = new Int32Array(STEPS.map(([small]) => small));
+const LARGE = new Int32Array(STEPS.map(([, large]) => large));
+const halves = [
+    { error: 0, table: 0, indices: new Int32Array(8) },
+    { error: 0, table: 0, indices: new Int32Array(8) },
+];
+const best = { error: Infinity, high: 0, low: 0 };
+const base = new Int32Array(6);
+const quantized = new Int32Array(6);
+const offsets = new Float64Array(8);
+/** The least-error ETC1-mode block for `texels`, written at `at`. */
+function encodeColour(out, at) {
+    best.error = Infinity;
+    const [first, second] = halves;
+    for (let flip = 0; flip < 2; flip++) {
+        let fitted = false;
+        for (let differential = 1; differential >= 0; differential--) {
+            /* Five bits where the pair's difference fits, which is nearly always the better; four bits
+               each only where it does not, so a split pays for one search and not two. */
+            if (differential === 0 && fitted)
+                continue;
+            fitted = bases(flip, differential === 1);
+            if (!fitted)
+                continue;
+            /* Each half searched only as far as it could still beat the best block so far. */
+            searchHalf(flip, 0, first, best.error);
+            if (first.error >= best.error)
+                continue;
+            searchHalf(flip, 1, second, best.error - first.error);
+            const error = first.error + second.error;
+            if (error >= best.error)
+                continue;
+            best.error = error;
+            let high = 0;
+            if (differential === 1) {
+                for (let c = 0; c < 3; c++) {
+                    const q = quantized[c];
+                    const delta = quantized[c + 3] - q;
+                    high |= ((q << 3) | (delta & 7)) << (24 - c * 8);
+                }
+            }
+            else {
+                for (let c = 0; c < 3; c++) {
+                    high |= ((quantized[c] << 4) | quantized[c + 3]) << (24 - c * 8);
+                }
+            }
+            high |= (first.table << 5) | (second.table << 2) | (differential << 1) | flip;
+            let low = 0;
+            for (let half = 0; half < 2; half++) {
+                const list = HALF_TEXELS[flip * 2 + half];
+                const indices = halves[half].indices;
+                for (let k = 0; k < 8; k++) {
+                    const i = list[k];
+                    const index = indices[k];
+                    low |= ((index >> 1) << (i + 16)) | ((index & 1) << i);
+                }
+            }
+            best.high = high >>> 0;
+            best.low = low >>> 0;
+        }
+    }
+    write32(out, at, best.high);
+    write32(out, at + 4, best.low);
+}
+/**
+ * Each half's average, quantised as the mode stores it and expanded back, into `base` — and false
+ * where the differential mode cannot hold the second as a step of -4 to 3 from the first.
+ */
+function bases(flip, differential) {
+    for (let half = 0; half < 2; half++) {
+        const list = HALF_TEXELS[flip * 2 + half];
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        for (let k = 0; k < 8; k++) {
+            const i = list[k];
+            r += texels[i * 4];
+            g += texels[i * 4 + 1];
+            b += texels[i * 4 + 2];
+        }
+        for (let c = 0; c < 3; c++) {
+            const average = (c === 0 ? r : c === 1 ? g : b) / 8;
+            if (differential) {
+                const q = Math.round((average * 31) / 255);
+                quantized[half * 3 + c] = q;
+                base[half * 3 + c] = (q << 3) | (q >> 2);
+            }
+            else {
+                const q = Math.round((average * 15) / 255);
+                quantized[half * 3 + c] = q;
+                base[half * 3 + c] = (q << 4) | q;
+            }
+        }
+    }
+    if (!differential)
+        return true;
+    for (let c = 0; c < 3; c++) {
+        const delta = quantized[c + 3] - quantized[c];
+        if (delta < -4 || delta > 3)
+            return false;
+    }
+    return true;
+}
+/**
+ * The table with the least error for one half against its base, and each texel's step for it —
+ * or `into.error` left at infinity where no table comes under `bound`.
+ *
+ * **A texel's step is found, not searched.** Every step moves all three channels by one amount, so
+ * the amount that brings a texel nearest its colour is its average offset from the base, and the
+ * step to take is the one nearest that. Unclamped, a texel's error at step `s` is its spread about
+ * that average offset `o` plus `3(s − o)²`, so a table's error is the half's spread, summed once,
+ * plus that term — exact, with no channel read again. **Only a table whose large step could carry a
+ * channel past 0 or 255 is checked texel by texel**, with the clamp a device applies and the
+ * nearest step's neighbour as a second candidate, since a clamped channel can make the nearest step
+ * no longer the closest. On a photograph that is a dark or a bright block's few tables.
+ *
+ * What it gives up is the error a weighting by channel would trade; the steps are one brightness for
+ * all three, so a weight changes which of two near steps wins and little else.
+ */
+function searchHalf(flip, half, into, bound) {
+    const list = HALF_TEXELS[flip * 2 + half];
+    const r0 = base[half * 3];
+    const g0 = base[half * 3 + 1];
+    const b0 = base[half * 3 + 2];
+    const lowest = Math.min(r0, g0, b0);
+    const highest = Math.max(r0, g0, b0);
+    let spread = 0;
+    for (let k = 0; k < 8; k++) {
+        const i = list[k];
+        const dr = texels[i * 4] - r0;
+        const dg = texels[i * 4 + 1] - g0;
+        const db = texels[i * 4 + 2] - b0;
+        const offset = (dr + dg + db) / 3;
+        offsets[k] = offset;
+        spread += dr * dr + dg * dg + db * db - 3 * offset * offset;
+    }
+    into.error = Infinity;
+    let chosen = -1;
+    let least = bound;
+    for (let table = 0; table < 8; table++) {
+        const small = SMALL[table];
+        const large = LARGE[table];
+        const error = lowest - large >= 0 && highest + large <= 255
+            ? spread + 3 * nearestSum(small, large, null)
+            : clampedError(list, r0, g0, b0, small, large, least, null);
+        if (error < least) {
+            least = error;
+            chosen = table;
+        }
+    }
+    if (chosen < 0)
+        return;
+    into.error = least;
+    into.table = chosen;
+    const small = SMALL[chosen];
+    const large = LARGE[chosen];
+    if (lowest - large >= 0 && highest + large <= 255)
+        nearestSum(small, large, into.indices);
+    else
+        clampedError(list, r0, g0, b0, small, large, Infinity, into.indices);
+}
+/** `Σ (s − o)²` over the half's offsets at each one's nearest step, the steps into `write`. */
+function nearestSum(small, large, write) {
+    const middle = (small + large) / 2;
+    let sum = 0;
+    for (let k = 0; k < 8; k++) {
+        const offset = offsets[k];
+        let index;
+        let d;
+        if (offset >= 0) {
+            index = offset > middle ? 1 : 0;
+            d = (index === 1 ? large : small) - offset;
+        }
+        else {
+            index = offset < -middle ? 3 : 2;
+            d = (index === 3 ? -large : -small) - offset;
+        }
+        if (write !== null)
+            write[k] = index;
+        sum += d * d;
+    }
+    return sum;
+}
+/** A table's error with every channel clamped as a device does, stopping once past `bound`. */
+function clampedError(list, r0, g0, b0, small, large, bound, write) {
+    let error = 0;
+    for (let k = 0; k < 8; k++) {
+        const i = list[k];
+        const offset = offsets[k];
+        /* The nearest step by the offset, and its neighbour toward zero. */
+        let near;
+        let other;
+        if (offset >= 0) {
+            near = offset > (small + large) / 2 ? 1 : 0;
+            other = near === 1 ? 0 : 2;
+        }
+        else {
+            near = offset < -(small + large) / 2 ? 3 : 2;
+            other = near === 3 ? 2 : 0;
+        }
+        const e1 = texelError(i, r0, g0, b0, stepOf(near, small, large));
+        const e2 = texelError(i, r0, g0, b0, stepOf(other, small, large));
+        if (write !== null)
+            write[k] = e1 <= e2 ? near : other;
+        error += e1 <= e2 ? e1 : e2;
+        if (error >= bound)
+            return error;
+    }
+    return error;
+}
+/** A step by its two-bit index, from a table's two amounts. */
+function stepOf(index, small, large) {
+    return index === 0 ? small : index === 1 ? large : index === 2 ? -small : -large;
+}
+/** One texel's squared error against a base moved by `s`, every channel clamped as a device does. */
+function texelError(i, r0, g0, b0, s) {
+    const dr = texels[i * 4] - clamp255(r0 + s);
+    const dg = texels[i * 4 + 1] - clamp255(g0 + s);
+    const db = texels[i * 4 + 2] - clamp255(b0 + s);
+    return dr * dr + dg * dg + db * db;
+}
+const eacIndices = new Int32Array(16);
+const eacBest = new Int32Array(16);
+/**
+ * One EAC block of channel `channel` at `at`: eight-bit, as alpha beside colour is, or eleven-bit,
+ * as `eac-r11` stores data. A block of one value is stored exactly, through the one table with a
+ * zero step.
+ */
+function encodeEac(out, at, channel, eleven) {
+    let min = 255;
+    let max = 0;
+    for (let i = 0; i < 16; i++) {
+        const v = texels[i * 4 + channel];
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    /* Targets in the stored range: eight bits, or eleven with 255 at 2047. */
+    const scale = eleven ? 2047 / 255 : 1;
+    let bestError = Infinity;
+    let bestBase = 0;
+    let bestMultiplier = 1;
+    let bestTable = 13;
+    for (let table = 0; table < 16; table++) {
+        const steps = EAC[table];
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (const s of steps) {
+            if (s < lo)
+                lo = s;
+            if (s > hi)
+                hi = s;
+        }
+        const span = (max - min) * scale;
+        const grain = eleven ? 8 : 1;
+        const ideal = span / ((hi - lo) * grain);
+        for (let round = 0; round < 2; round++) {
+            const m = Math.min(15, Math.max(1, round === 0 ? Math.floor(ideal) : Math.ceil(ideal)));
+            /* The base that puts the table's middle on the block's. */
+            const middle = ((min + max) / 2) * scale - ((hi + lo) / 2) * m * grain;
+            const b = Math.min(255, Math.max(0, Math.round(eleven ? (middle - 4) / 8 : middle)));
+            let error = 0;
+            const nearest = NEAREST[table];
+            const origin = eleven ? b * 8 + 4 : b;
+            const unit = m * grain;
+            for (let i = 0; i < 16; i++) {
+                const target = texels[i * 4 + channel] * scale;
+                /* The step nearest the texel's offset, looked up, and checked exactly with the clamp. */
+                const u = Math.round((target - origin) / unit);
+                const chosen = nearest[(u < -16 ? -16 : u > 15 ? 15 : u) + 16];
+                const d = eacValue(b, m, steps[chosen], eleven) - target;
+                eacIndices[i] = chosen;
+                error += d * d;
+                if (error >= bestError)
+                    break;
+            }
+            if (error < bestError) {
+                bestError = error;
+                bestBase = b;
+                bestMultiplier = m;
+                bestTable = table;
+                eacBest.set(eacIndices);
+            }
+        }
+    }
+    out[at] = bestBase;
+    out[at + 1] = (bestMultiplier << 4) | bestTable;
+    /* Forty-eight bits of three-bit indices, the first texel in the highest: two words of 24. */
+    let first = 0;
+    let second = 0;
+    for (let i = 0; i < 8; i++)
+        first = (first << 3) | eacBest[i];
+    for (let i = 8; i < 16; i++)
+        second = (second << 3) | eacBest[i];
+    out[at + 2] = (first >>> 16) & 255;
+    out[at + 3] = (first >>> 8) & 255;
+    out[at + 4] = first & 255;
+    out[at + 5] = (second >>> 16) & 255;
+    out[at + 6] = (second >>> 8) & 255;
+    out[at + 7] = second & 255;
+}
+/** What an EAC block decodes a step to: eight-bit, or eleven-bit as `eac-r11` stores. */
+function eacValue(base, multiplier, step, eleven) {
+    if (!eleven)
+        return clamp255(base + step * multiplier);
+    const v = base * 8 + 4 + step * multiplier * 8;
+    return v < 0 ? 0 : v > 2047 ? 2047 : v;
+}
+function write32(out, at, value) {
+    out[at] = (value >>> 24) & 255;
+    out[at + 1] = (value >>> 16) & 255;
+    out[at + 2] = (value >>> 8) & 255;
+    out[at + 3] = value & 255;
+}
+/**
+ * One level of a block back to RGBA, for the modes this encoder writes and EAC: what a device
+ * decodes, stated here so the encoder can be held to a number. A block in T, H or planar mode is
+ * refused by name, since nothing here writes one.
+ */
+export function decodeEtc2(format, blocks, width, height) {
+    const across = Math.max(1, Math.ceil(width / 4));
+    const bytes = BYTES[format];
+    const out = new Uint8Array(width * height * 4);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const at = (Math.floor(y / 4) * across + Math.floor(x / 4)) * bytes;
+            const i = (x % 4) * 4 + (y % 4);
+            const to = (y * width + x) * 4;
+            out[to + 3] = 255;
+            if (format === 'etc2-rgb8' || format === 'etc2-rgba8') {
+                decodeColourTexel(blocks, format === 'etc2-rgba8' ? at + 8 : at, i, out, to);
+                if (format === 'etc2-rgba8')
+                    out[to + 3] = decodeEacTexel(blocks, at, i, false);
+            }
+            else {
+                out[to] = Math.round((decodeEacTexel(blocks, at, i, true) * 255) / 2047);
+                out[to + 1] =
+                    format === 'eac-rg11'
+                        ? Math.round((decodeEacTexel(blocks, at + 8, i, true) * 255) / 2047)
+                        : 0;
+                out[to + 2] = 0;
+            }
+        }
+    }
+    return out;
+}
+function read32(blocks, at) {
+    return (((blocks[at] << 24) |
+        (blocks[at + 1] << 16) |
+        (blocks[at + 2] << 8) |
+        blocks[at + 3]) >>>
+        0);
+}
+function decodeColourTexel(blocks, at, i, out, to) {
+    const high = read32(blocks, at);
+    const low = read32(blocks, at + 4);
+    const flip = high & 1;
+    const differential = (high >> 1) & 1;
+    const half = firstHalf(i, flip) ? 0 : 1;
+    const table = half === 0 ? (high >> 5) & 7 : (high >> 2) & 7;
+    const index = (((low >>> (i + 16)) & 1) << 1) | ((low >>> i) & 1);
+    for (let c = 0; c < 3; c++) {
+        let value;
+        if (differential === 1) {
+            const first = (high >>> (27 - c * 8)) & 31;
+            let delta = (high >>> (24 - c * 8)) & 7;
+            if (delta >= 4)
+                delta -= 8;
+            const q = half === 0 ? first : first + delta;
+            if (q < 0 || q > 31) {
+                throw new Error('decodeEtc2: a block in T, H or planar mode, which this does not decode');
+            }
+            value = (q << 3) | (q >> 2);
+        }
+        else {
+            const q = (high >>> (half === 0 ? 28 - c * 8 : 24 - c * 8)) & 15;
+            value = (q << 4) | q;
+        }
+        out[to + c] = clamp255(value + step(table, index));
+    }
+}
+function decodeEacTexel(blocks, at, i, eleven) {
+    const b = blocks[at];
+    const multiplier = blocks[at + 1] >> 4;
+    const table = blocks[at + 1] & 15;
+    const first = (blocks[at + 2] << 16) |
+        (blocks[at + 3] << 8) |
+        blocks[at + 4];
+    const second = (blocks[at + 5] << 16) |
+        (blocks[at + 6] << 8) |
+        blocks[at + 7];
+    const index = i < 8 ? (first >>> (21 - i * 3)) & 7 : (second >>> (21 - (i - 8) * 3)) & 7;
+    return eacValue(b, multiplier, EAC[table][index], eleven);
+}

package/dist/etc2Load.d.ts

@@ -0,0 +1,20 @@
+import type { CompressedTextureFormat, CompressedTextureSource } from '@driftengine/core';
+import type { BcImage } from '@driftengine/drft';
+import type { BcWorker } from './bcLoad.ts';
+export type { Etc2Reply, Etc2Request } from './etc2Answer.ts';
+export { answerEtc2Request } from './etc2Answer.ts';
+/**
+ * Whether `image` can go up as ETC2 or EAC on a device offering `available`, read in the colour
+ * space the slot reads: every format it could become, since which colour format is decided by the
+ * decoded alpha. EAC has no sRGB twin, so a BC4 or BC5 texture read as colour stays an image.
+ */
+export declare function etc2Plan(image: BcImage, srgb: boolean, available: readonly CompressedTextureFormat[]): boolean;
+/** BC textures to ETC2 or EAC chains, one at a time, on a worker. */
+export interface Etc2Encoder {
+    encode(image: BcImage, srgb: boolean): Promise<CompressedTextureSource>;
+    /** Empty while the worker lives; otherwise why the textures stay RGBA. */
+    readonly reason: string;
+    dispose(): void;
+}
+/** An encoder over a worker `spawn` starts: the same factory the decoder is given. */
+export declare function createEtc2Encoder(spawn: () => BcWorker): Etc2Encoder;

package/dist/etc2Load.js

@@ -0,0 +1,124 @@
+/**
+ * BC textures re-encoded as ETC2 or EAC for a device that samples those and not BC — which is a
+ * phone — and the worker that does it.
+ *
+ * **After the picture, not before it.** Such a texture is decoded and shown as RGBA first, exactly
+ * as it was before this existed (`bcLoad.ts`), and its blocks then go to an encode worker of their
+ * own; the chain that comes back replaces the image behind the handle every draw already holds
+ * (`updateSurfaceTexture`). So nothing arrives later than it did, and the texture ends at half a
+ * byte a texel, or a byte with alpha, where it held four. **What it costs** is the encode, on a core
+ * of its own: measured at 0.7 s for a 2048² photograph on a desktop processor, and several times
+ * that on a phone's, one texture at a time. **What it gives up** is the memory a load peaks at,
+ * which is still every texture as RGBA until the encodes catch up: what would make that wrong is a
+ * device that cannot hold the RGBA at all, and the answer then is blocks it samples in the file,
+ * which a KTX2 texture carries through as they are.
+ *
+ * **A worker of its own, not the decode worker**, so a texture waiting to be decoded never waits
+ * behind a second of somebody else's encode; and one job in flight at a time, so a model's hundred
+ * textures are a hundred small messages queued here rather than a hundred copies of their blocks
+ * queued there. **Never on the main thread**: where no worker was named, or the one started fails,
+ * the textures stay RGBA and the loader says why once — a texture held at four bytes a texel is
+ * the state this improves on, never a stall.
+ */
+import { uploadsCompressed } from '@driftengine/core';
+export { answerEtc2Request } from './etc2Answer.js';
+/**
+ * Whether `image` can go up as ETC2 or EAC on a device offering `available`, read in the colour
+ * space the slot reads: every format it could become, since which colour format is decided by the
+ * decoded alpha. EAC has no sRGB twin, so a BC4 or BC5 texture read as colour stays an image.
+ */
+export function etc2Plan(image, srgb, available) {
+    const { format, width, height } = image;
+    if (format === 'bc4')
+        return uploadsCompressed('eac-r11', srgb, width, height, available);
+    if (format === 'bc5')
+        return uploadsCompressed('eac-rg11', srgb, width, height, available);
+    return (uploadsCompressed('etc2-rgb8', srgb, width, height, available) &&
+        uploadsCompressed('etc2-rgba8', srgb, width, height, available));
+}
+/** An encoder over a worker `spawn` starts: the same factory the decoder is given. */
+export function createEtc2Encoder(spawn) {
+    let worker = null;
+    let reason = '';
+    let running = null;
+    const waiting = [];
+    let next = 0;
+    const stop = (why) => {
+        reason = why;
+        worker?.terminate();
+        worker = null;
+        const error = new Error(why);
+        running?.reject(error);
+        running = null;
+        for (const job of waiting)
+            job.reject(error);
+        waiting.length = 0;
+    };
+    const pump = () => {
+        const target = worker;
+        if (running !== null || target === null)
+            return;
+        const job = waiting.shift();
+        if (job === undefined)
+            return;
+        running = job;
+        const { image } = job;
+        /* A copy, for the reason `bcLoad.ts` gives: a level is a view over the fetched file. */
+        const blocks = image.levels[0].slice().buffer;
+        const request = {
+            kind: 'etc2',
+            id: job.id,
+            format: image.format,
+            width: image.width,
+            height: image.height,
+            blocks,
+            srgb: job.srgb,
+        };
+        target.postMessage(request, [blocks]);
+    };
+    try {
+        const started = spawn();
+        worker = started;
+        started.onmessage = (event) => {
+            const reply = event.data;
+            const job = running;
+            if (job === null || reply.id !== job.id)
+                return;
+            running = null;
+            if (reply.format !== undefined && reply.levels !== undefined) {
+                const levels = reply.levels.map((level) => new Uint8Array(level));
+                const { width, height } = job.image;
+                job.resolve({ format: reply.format, width, height, levels });
+            }
+            else {
+                job.reject(new Error(reply.error ?? 'etc2: the encode answered nothing'));
+            }
+            pump();
+        };
+        started.onerror = (event) => {
+            const message = event?.message;
+            stop(`the ETC2 worker failed (${typeof message === 'string' ? message : 'no message'}), so ` +
+                'BC textures stay RGBA on this device');
+        };
+    }
+    catch (error) {
+        stop(`the ETC2 worker would not start (${error instanceof Error ? error.message : String(error)})` +
+            ', so BC textures stay RGBA on this device');
+    }
+    return {
+        get reason() {
+            return reason;
+        },
+        encode(image, srgb) {
+            if (worker === null)
+                return Promise.reject(new Error(reason));
+            return new Promise((resolve, reject) => {
+                waiting.push({ id: next++, image, srgb, resolve, reject });
+                pump();
+            });
+        },
+        dispose() {
+            stop('etc2: the encoder was disposed');
+        },
+    };
+}

package/dist/index.d.ts

@@ -98,6 +98,11 @@ export { ddsBlocks } from './ddsBlocks.ts';
 export { decodeBc } from './bcDecode.ts';
 export { decodeBcImage } from './bcImage.ts';
 export { flipBc5Green } from './bcFlip.ts';
+export { readKtx2 } from './ktx2.ts';
+export type { Ktx2Texture } from './ktx2.ts';
+export { encodeEtc2 } from './etc2Encode.ts';
+export type { Etc2Format } from './etc2Encode.ts';
+export { encodeEtc2Chain } from './etc2Chain.ts';
 export { buildClusters } from './bake/cluster.ts';
 export type { ClusterOptions, ClusterSet } from './bake/cluster.ts';
 export { buildClusterDag } from './bake/clusterLod.ts';