@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,87 @@
+import { uastc_block_texels, uastc_decode_block, UASTC_BLOCK_BYTES } from "./uastc_decode_block.js";
+
+/**
+ * Side of a UASTC block, in texels.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BLOCK_SIZE = 4;
+
+/**
+ * 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, block_count, width, height) {
+    const out = new Uint8Array(width * height * 4);
+
+    const blocks_x = Math.ceil(width / BLOCK_SIZE);
+
+    const texels = new Uint8Array(64);
+
+    for (let block = 0; block < block_count; block++) {
+        uastc_block_texels(
+            uastc_decode_block(blocks, block * UASTC_BLOCK_BYTES), texels, 0
+        );
+
+        const block_x = (block % blocks_x) * BLOCK_SIZE;
+        const block_y = Math.floor(block / blocks_x) * BLOCK_SIZE;
+
+        for (let row = 0; row < BLOCK_SIZE; row++) {
+            const y = block_y + row;
+
+            if (y >= height) {
+                break;
+            }
+
+            for (let column = 0; column < BLOCK_SIZE; column++) {
+                const x = block_x + column;
+
+                if (x >= width) {
+                    break;
+                }
+
+                const from = (row * BLOCK_SIZE + column) * 4;
+                const to = (y * width + x) * 4;
+
+                out[to] = texels[from];
+                out[to + 1] = texels[from + 1];
+                out[to + 2] = texels[from + 2];
+                out[to + 3] = texels[from + 3];
+            }
+        }
+    }
+
+    return out;
+}

package/src/format/texture/bc/bc1_write_block.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Write one BC1 block from its two packed endpoints and sixteen indices.
+ *
+ * **Layout only — no fitting.** Little-endian: the first endpoint's sixteen bits, the second's, then
+ * thirty-two bits of two-bit indices with texel 0 lowest, so each row of four texels is one byte.
+ *
+ * Which palette the indices select is decided by the endpoints' order, as the format defines it:
+ * `first > second` as sixteen-bit words gives the four-colour mode, `first <= second` the
+ * three-colour one whose index 3 is transparent black. Nothing here checks which was meant.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} first the 5:6:5 endpoint index 0 selects
+ * @param {number} second the 5:6:5 endpoint index 1 selects
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..3`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc1_write_block(out: Uint8Array, byte_offset: number, first: number, second: number, indices: ArrayLike<number>): void;
+/**
+ * Bytes one BC1 block occupies: two 5:6:5 endpoints and sixteen two-bit indices.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC1_BLOCK_BYTES: number;
+//# sourceMappingURL=bc1_write_block.d.ts.map

package/src/format/texture/bc/bc1_write_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc1_write_block.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/bc/bc1_write_block.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qCATW,UAAU,eACV,MAAM,SACN,MAAM,UACN,MAAM,WACN,UAAU,MAAM,CAAC,QAkB3B;AAxCD;;;;;GAKG;AACH,8BAFU,MAAM,CAEiB"}

package/src/format/texture/bc/bc1_write_block.js

@@ -0,0 +1,41 @@
+/**
+ * Bytes one BC1 block occupies: two 5:6:5 endpoints and sixteen two-bit indices.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC1_BLOCK_BYTES = 8;
+
+/**
+ * Write one BC1 block from its two packed endpoints and sixteen indices.
+ *
+ * **Layout only — no fitting.** Little-endian: the first endpoint's sixteen bits, the second's, then
+ * thirty-two bits of two-bit indices with texel 0 lowest, so each row of four texels is one byte.
+ *
+ * Which palette the indices select is decided by the endpoints' order, as the format defines it:
+ * `first > second` as sixteen-bit words gives the four-colour mode, `first <= second` the
+ * three-colour one whose index 3 is transparent black. Nothing here checks which was meant.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} first the 5:6:5 endpoint index 0 selects
+ * @param {number} second the 5:6:5 endpoint index 1 selects
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..3`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc1_write_block(out, byte_offset, first, second, indices) {
+    out[byte_offset] = first & 0xFF;
+    out[byte_offset + 1] = (first >> 8) & 0xFF;
+    out[byte_offset + 2] = second & 0xFF;
+    out[byte_offset + 3] = (second >> 8) & 0xFF;
+
+    for (let row = 0; row < 4; row++) {
+        out[byte_offset + 4 + row] =
+            (indices[row * 4] & 3)
+            | ((indices[row * 4 + 1] & 3) << 2)
+            | ((indices[row * 4 + 2] & 3) << 4)
+            | ((indices[row * 4 + 3] & 3) << 6);
+    }
+}

package/src/format/texture/bc/bc4_write_block.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Write one BC4 block from its two endpoints and sixteen indices.
+ *
+ * **Layout only — no fitting.** Which endpoints and which indices is the encoder's business; this
+ * is the bit arrangement, kept apart so a CPU encoder, a GPU encoder's byte-for-byte cross-check and
+ * the transcoder that already writes BC5 all share one statement of it. The block is little-endian:
+ * the first endpoint in byte 0, the second in byte 1, then forty-eight bits of three-bit indices with
+ * texel 0 in the lowest bits — so texel `t` sits at bit `16 + 3t` of the block, and the sixteen
+ * indices split exactly into two runs of eight that each fill three bytes.
+ *
+ * Which palette the indices select is decided by the endpoints' order, as the format defines it:
+ * `first > second` gives eight interpolated values, `first <= second` gives six plus a hard 0 and a
+ * hard 255. Nothing here checks which was meant.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} first the endpoint index 0 selects, `0..255`
+ * @param {number} second the endpoint index 1 selects, `0..255`
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..7`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc4_write_block(out: Uint8Array, byte_offset: number, first: number, second: number, indices: ArrayLike<number>): void;
+/**
+ * Bytes one BC4 block occupies — and one channel of a BC5 block, which is two of these side by side.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC4_BLOCK_BYTES: number;
+//# sourceMappingURL=bc4_write_block.d.ts.map

package/src/format/texture/bc/bc4_write_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc4_write_block.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/bc/bc4_write_block.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qCATW,UAAU,eACV,MAAM,SACN,MAAM,UACN,MAAM,WACN,UAAU,MAAM,CAAC,QAuB3B;AAjDD;;;;;GAKG;AACH,8BAFU,MAAM,CAEiB"}

package/src/format/texture/bc/bc4_write_block.js

@@ -0,0 +1,50 @@
+/**
+ * Bytes one BC4 block occupies — and one channel of a BC5 block, which is two of these side by side.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC4_BLOCK_BYTES = 8;
+
+/**
+ * Write one BC4 block from its two endpoints and sixteen indices.
+ *
+ * **Layout only — no fitting.** Which endpoints and which indices is the encoder's business; this
+ * is the bit arrangement, kept apart so a CPU encoder, a GPU encoder's byte-for-byte cross-check and
+ * the transcoder that already writes BC5 all share one statement of it. The block is little-endian:
+ * the first endpoint in byte 0, the second in byte 1, then forty-eight bits of three-bit indices with
+ * texel 0 in the lowest bits — so texel `t` sits at bit `16 + 3t` of the block, and the sixteen
+ * indices split exactly into two runs of eight that each fill three bytes.
+ *
+ * Which palette the indices select is decided by the endpoints' order, as the format defines it:
+ * `first > second` gives eight interpolated values, `first <= second` gives six plus a hard 0 and a
+ * hard 255. Nothing here checks which was meant.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} first the endpoint index 0 selects, `0..255`
+ * @param {number} second the endpoint index 1 selects, `0..255`
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..7`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc4_write_block(out, byte_offset, first, second, indices) {
+    out[byte_offset] = first;
+    out[byte_offset + 1] = second;
+
+    for (let half = 0; half < 2; half++) {
+        // eight indices of three bits are twenty-four bits: three whole bytes, no carry between halves
+        let word = 0;
+
+        for (let i = 0; i < 8; i++) {
+            word |= (indices[half * 8 + i] & 7) << (3 * i);
+        }
+
+        const at = byte_offset + 2 + half * 3;
+
+        out[at] = word & 0xFF;
+        out[at + 1] = (word >> 8) & 0xFF;
+        out[at + 2] = (word >> 16) & 0xFF;
+    }
+}

package/src/format/texture/bc/bc6h_write_block_mode11.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Write one BC6H block in mode 11: one region, two ten-bit endpoints per channel, no delta.
+ *
+ * **Layout only — no fitting.** From the format's table: five mode bits, `00011` for mode 11, then
+ * the endpoints ten bits each in the order `rw gw bw rx gx bx` — the first endpoint's red, green and
+ * blue, then the second's — and from bit 65 the sixteen four-bit indices, texel 0 stored in three
+ * bits because its top bit is implied zero. That last rule is the encoder's to honour and this does
+ * not check it.
+ *
+ * The endpoints are the quantised ten-bit values, as the decoder reads them before it unquantises;
+ * what they mean in half-float terms is the decoder's arithmetic, not the layout's.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {ArrayLike<number>} first three ten-bit values, RGB
+ * @param {ArrayLike<number>} second three ten-bit values, RGB
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..15`, texel 0 below 8
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc6h_write_block_mode11(out: Uint8Array, byte_offset: number, first: ArrayLike<number>, second: ArrayLike<number>, indices: ArrayLike<number>): void;
+/**
+ * Bytes one BC6H block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC6H_BLOCK_BYTES: number;
+//# sourceMappingURL=bc6h_write_block_mode11.d.ts.map

package/src/format/texture/bc/bc6h_write_block_mode11.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc6h_write_block_mode11.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/bc/bc6h_write_block_mode11.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6CATW,UAAU,eACV,MAAM,SACN,UAAU,MAAM,CAAC,UACjB,UAAU,MAAM,CAAC,WACjB,UAAU,MAAM,CAAC,QAqC3B;AA7DD;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB"}

package/src/format/texture/bc/bc6h_write_block_mode11.js

@@ -0,0 +1,62 @@
+/**
+ * Bytes one BC6H block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC6H_BLOCK_BYTES = 16;
+
+/**
+ * Write one BC6H block in mode 11: one region, two ten-bit endpoints per channel, no delta.
+ *
+ * **Layout only — no fitting.** From the format's table: five mode bits, `00011` for mode 11, then
+ * the endpoints ten bits each in the order `rw gw bw rx gx bx` — the first endpoint's red, green and
+ * blue, then the second's — and from bit 65 the sixteen four-bit indices, texel 0 stored in three
+ * bits because its top bit is implied zero. That last rule is the encoder's to honour and this does
+ * not check it.
+ *
+ * The endpoints are the quantised ten-bit values, as the decoder reads them before it unquantises;
+ * what they mean in half-float terms is the decoder's arithmetic, not the layout's.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {ArrayLike<number>} first three ten-bit values, RGB
+ * @param {ArrayLike<number>} second three ten-bit values, RGB
+ * @param {ArrayLike<number>} indices sixteen, in raster order, each `0..15`, texel 0 below 8
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc6h_write_block_mode11(out, byte_offset, first, second, indices) {
+    out.fill(0, byte_offset, byte_offset + BC6H_BLOCK_BYTES);
+
+    let bit = byte_offset * 8;
+
+    /**
+     * @param {number} value
+     * @param {number} count
+     */
+    const write = (value, count) => {
+        for (let i = 0; i < count; i++) {
+            if (((value >> i) & 1) !== 0) {
+                out[(bit + i) >> 3] |= 1 << ((bit + i) & 7);
+            }
+        }
+
+        bit += count;
+    };
+
+    write(0b00011, 5);
+
+    for (let channel = 0; channel < 3; channel++) {
+        write(first[channel] & 1023, 10);
+    }
+
+    for (let channel = 0; channel < 3; channel++) {
+        write(second[channel] & 1023, 10);
+    }
+
+    for (let texel = 0; texel < 16; texel++) {
+        write(indices[texel] & 15, texel === 0 ? 3 : 4);
+    }
+}

package/src/format/texture/ktx2/KTX2_IDENTIFIER.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The twelve bytes every KTX2 file starts with: `«KTX 20»\r\n\x1A\n`.
+ *
+ * The escape sequences are not decoration. `\r\n` catches a transfer that translated line endings,
+ * `\x1A` stops a DOS `type` from printing the rest of the file, and the high bytes at either end of
+ * `«…»` fail a naive "is this text" check. A file that does not begin with exactly these is not a
+ * KTX2 file and is refused by name rather than parsed hopefully.
+ *
+ * @see https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html#_identifier
+ * @readonly
+ * @type {Uint8Array}
+ */
+export const KTX2_IDENTIFIER: Uint8Array;
+//# sourceMappingURL=KTX2_IDENTIFIER.d.ts.map

package/src/format/texture/ktx2/KTX2_IDENTIFIER.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KTX2_IDENTIFIER.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/KTX2_IDENTIFIER.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,8BAFU,UAAU,CAIjB"}

package/src/format/texture/ktx2/KTX2_IDENTIFIER.js

@@ -0,0 +1,15 @@
+/**
+ * The twelve bytes every KTX2 file starts with: `«KTX 20»\r\n\x1A\n`.
+ *
+ * The escape sequences are not decoration. `\r\n` catches a transfer that translated line endings,
+ * `\x1A` stops a DOS `type` from printing the rest of the file, and the high bytes at either end of
+ * `«…»` fail a naive "is this text" check. A file that does not begin with exactly these is not a
+ * KTX2 file and is refused by name rather than parsed hopefully.
+ *
+ * @see https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html#_identifier
+ * @readonly
+ * @type {Uint8Array}
+ */
+export const KTX2_IDENTIFIER = new Uint8Array([
+    0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A
+]);

package/src/format/texture/ktx2/KhrDfModel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @param {KhrDfModel|number} model
+ * @returns {string} the specification's name for `model`, or a description of the number when it
+ * names nothing this reader knows
+ */
+export function khr_df_model_name(model: KhrDfModel | number): string;
+/**
+ * The `colorModel` field of a Khronos Data Format basic descriptor block.
+ *
+ * Only the models a KTX2 file can carry are named, and only two of them matter to this reader: when
+ * `vkFormat` is `VK_FORMAT_UNDEFINED` the payload is Basis Universal, and this field is the one
+ * thing in the file that says which of the two Basis encodings it is. Every other model reaches the
+ * reader through `vkFormat` instead, so the value is read for the refusal message rather than for
+ * the format.
+ */
+export type KhrDfModel = number;
+export namespace KhrDfModel {
+    let Unspecified: number;
+    let RGBSDA: number;
+    let BC1A: number;
+    let BC2: number;
+    let BC3: number;
+    let BC4: number;
+    let BC5: number;
+    let BC6H: number;
+    let BC7: number;
+    let ETC1: number;
+    let ETC2: number;
+    let ASTC: number;
+    let ETC1S: number;
+    let PVRTC: number;
+    let PVRTC2: number;
+    let UASTC: number;
+}
+//# sourceMappingURL=KhrDfModel.d.ts.map

package/src/format/texture/ktx2/KhrDfModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KhrDfModel.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/KhrDfModel.js"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,yCAJW,UAAU,GAAC,MAAM,GACf,MAAM,CAWlB;;;;;;;;;;yBArCS,MAAM"}

package/src/format/texture/ktx2/KhrDfModel.js

@@ -0,0 +1,49 @@
+/**
+ * The `colorModel` field of a Khronos Data Format basic descriptor block.
+ *
+ * Only the models a KTX2 file can carry are named, and only two of them matter to this reader: when
+ * `vkFormat` is `VK_FORMAT_UNDEFINED` the payload is Basis Universal, and this field is the one
+ * thing in the file that says which of the two Basis encodings it is. Every other model reaches the
+ * reader through `vkFormat` instead, so the value is read for the refusal message rather than for
+ * the format.
+ *
+ * @see https://registry.khronos.org/DataFormat/specs/1.3/dataformat.v1.3.html#_khr_df_model
+ * @readonly
+ * @enum {number}
+ */
+export const KhrDfModel = {
+    Unspecified: 0,
+    /** ordinary colour channels — red, green, blue, stencil, depth, alpha */
+    RGBSDA: 1,
+    BC1A: 128,
+    BC2: 129,
+    BC3: 130,
+    BC4: 131,
+    BC5: 132,
+    BC6H: 133,
+    BC7: 134,
+    ETC1: 160,
+    ETC2: 161,
+    ASTC: 162,
+    /** Basis Universal, low quality tier. Transcoded, never sampled directly. */
+    ETC1S: 163,
+    PVRTC: 164,
+    PVRTC2: 165,
+    /** Basis Universal, high quality tier. Transcoded, never sampled directly. */
+    UASTC: 166,
+};
+
+/**
+ * @param {KhrDfModel|number} model
+ * @returns {string} the specification's name for `model`, or a description of the number when it
+ * names nothing this reader knows
+ */
+export function khr_df_model_name(model) {
+    for (const [name, value] of Object.entries(KhrDfModel)) {
+        if (value === model) {
+            return name;
+        }
+    }
+
+    return `colour model ${model}`;
+}

package/src/format/texture/ktx2/SupercompressionScheme.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What, if anything, was applied to a KTX2 level's bytes after encoding.
+ *
+ * Orthogonal to `vkFormat`: supercompression wraps an already-encoded payload, so a BC7 file and a
+ * ZLIB-supercompressed BC7 file hold the same blocks and differ only in how they got there. The one
+ * exception is {@link BasisLZ }, which is not a wrapper at all — it is an encoding, with its own
+ * global data in the SGD section, and a file that uses it carries no `vkFormat`.
+ */
+export type SupercompressionScheme = number;
+export namespace SupercompressionScheme {
+    let None: number;
+    let BasisLZ: number;
+    let Zstandard: number;
+    let ZLIB: number;
+}
+//# sourceMappingURL=SupercompressionScheme.d.ts.map

package/src/format/texture/ktx2/SupercompressionScheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupercompressionScheme.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/SupercompressionScheme.js"],"names":[],"mappings":";;;;;;;;qCAUU,MAAM"}

package/src/format/texture/ktx2/SupercompressionScheme.js

@@ -0,0 +1,23 @@
+/**
+ * What, if anything, was applied to a KTX2 level's bytes after encoding.
+ *
+ * Orthogonal to `vkFormat`: supercompression wraps an already-encoded payload, so a BC7 file and a
+ * ZLIB-supercompressed BC7 file hold the same blocks and differ only in how they got there. The one
+ * exception is {@link BasisLZ}, which is not a wrapper at all — it is an encoding, with its own
+ * global data in the SGD section, and a file that uses it carries no `vkFormat`.
+ *
+ * @see https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html#_supercompressionscheme
+ * @readonly
+ * @enum {number}
+ */
+export const SupercompressionScheme = {
+    /** the level bytes are the texel bytes */
+    None: 0,
+    /** ETC1S with a BasisLZ-coded endpoint/selector codebook. Needs a transcoder, not a decompressor. */
+    BasisLZ: 1,
+    /** each level is an independent Zstandard frame */
+    Zstandard: 2,
+    /** each level is an independent zlib stream, RFC 1950 framing */
+    ZLIB: 3,
+};
+

package/src/format/texture/ktx2/ktx2_read.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Read a KTX2 file into a {@link TexelPayload}.
+ *
+ * **The whole contract is `bytes -> TexelPayload`.** No device, no queue, no engine: the same
+ * function serves a worker, a node tool and the offline encoder, which is why a container reader is
+ * not engine code. The engine's door is `texel_data_from_ktx2`, which wraps the payload in a
+ * `ShadeTexelData` — a compressed texture entering that way is indistinguishable, below `ShadeImage`,
+ * from one that arrived any other way.
+ *
+ * **What it reads.** Two kinds of file, and the difference between them is the whole shape of this
+ * function:
+ *
+ * 1. **Already in a device format** — any `vkFormat` that maps to a `GPUTextureFormat` (see
+ *    {@link vk_format_to_texture_format}). That is what first-party tooling emits, and the payload
+ *    reaches the GPU untouched.
+ * 2. **Basis Universal**, in either encoding: ETC1S behind
+ *    {@link SupercompressionScheme.BasisLZ}, transcoded by {@link transcode_basis}, and UASTC, which
+ *    uses no supercompression scheme of its own, transcoded by {@link transcode_uastc}. That is what
+ *    the web's model pipeline emits — `gltf-transform` and `toktx` produce one or the other by
+ *    default, ETC1S for colour and UASTC where quality matters.
+ *
+ * **Array textures and cube maps are read.** A level holds its images back to back — layer-major,
+ * then face, then depth slice, with no padding between them, which is KTX2's own order and the one
+ * `writeTexture` takes for `depthOrArrayLayers`. The payload reports `layers` and `faces` and leaves
+ * what to do with them to the caller: the engine's adapter refuses what its texture type cannot yet
+ * hold, and a reader that refused for it would be refusing well-formed files on another tier's behalf.
+ *
+ * Any of them may be wrapped: {@link SupercompressionScheme.ZLIB} is undone by `pako` and
+ * {@link SupercompressionScheme.Zstandard} by {@link zstd_decompress}. Wrapping is a property of the
+ * file rather than of the payload, so it is undone before anything looks at what is inside.
+ *
+ * **The second kind is a compatibility path, not the delivery path.** Transcoding pays CPU time on
+ * load to recover a format the device could have been handed directly, and meep's own pipeline hands
+ * it directly. Reading it is what lets the engine open third-party content at all.
+ *
+ * **`transcode_target` is required for a Basis file and meaningless for any other.** Which format
+ * such a payload should become depends on the device and on the material slot the texture fills,
+ * neither of which a container reader knows — see `texture_format_preference`. Omitting it is not a
+ * default but an absence, and a Basis file read without one is refused rather than guessed at.
+ *
+ * **What it refuses, by name.** Everything else, individually, because the point of a refusal is to
+ * say which feature is missing rather than to produce a texture full of the wrong bytes:
+ *
+ * | Refused | Why |
+ * |---|---|
+ * | a Basis file with no `transcode_target` | see above |
+ * | an unmapped `vkFormat` | WebGPU does not expose it |
+ * | `layerCount > 0` or `faceCount == 6` with `pixelDepth > 0` | a 3D array — WebGPU's 3D textures have no layers |
+ * | `layerCount > 0` or `faceCount == 6` on a Basis payload | the transcoders take one image per level |
+ * | `pixelHeight == 0` | a 1D texture, likewise |
+ * | a 3D block-compressed payload | needs `texture-compression-*-sliced-3d`, which nothing here asks for |
+ * | `levelCount == 0` on a block format | see below |
+ * | a non-default `KTXorientation` or `KTXswizzle` | the bytes would need rearranging, and nothing here rearranges them |
+ *
+ * **`levelCount == 0` means "generate the mip chain at load", which is not the same as `1`.** It is
+ * an *instruction*, and the payload type carries data rather than instructions: the engine's
+ * instruction is `ShadeTextureFlags.GenerateMipMaps`, which lives on the `ShadeTexture` and is
+ * honoured or thrown. So a `levelCount == 0` file reads as the single level it physically contains,
+ * and whether mips get generated is the caller's to state — which is the same rule that makes a
+ * supplied chain and a generated one distinguishable at all. For a block-compressed payload the
+ * instruction cannot be honoured by anything, at any layer, so that combination is refused here
+ * rather than left to fail later with a message about a flag the file never mentioned.
+ *
+ * **The level index is base-first; the image data usually is not.** KTX2 conventionally stores the
+ * smallest level at the lowest offset, so levels are read through `byteOffset` and never by walking
+ * the file. `levels[0]` is the base level whatever order the file laid its bytes out in.
+ *
+ * Level bytes are views onto `bytes`, not copies, wherever supercompression permits it — the payload
+ * is the overwhelming majority of a texture file, and copying it to hand it to `writeTexture` would
+ * double the peak memory of every texture load for nothing.
+ *
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {TextureFormat|TextureFormat[]} [transcode_target] what a Basis payload should be
+ * transcoded into. Required for such a file and ignored for every other; see above for why it is not
+ * defaulted.
+ *
+ * **An array is an ordered preference, not a set**, and is the form to use when more than one target
+ * would do. Whether a file carries alpha is knowable only from its descriptor, which is read here, so
+ * a caller that names a single three-channel format for a payload that turns out to have alpha gets a
+ * refusal where it could have got its second choice. Given the list, this passes over the targets that
+ * cannot hold what the file contains and takes the first that can
+ * @returns {TexelPayload}
+ * @throws {Error} naming the feature, for a file this reader does not read; naming the field, for a
+ * file that is truncated or self-inconsistent
+ *
+ * @see https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function ktx2_read(bytes: ArrayBuffer | Uint8Array, transcode_target?: TextureFormat | TextureFormat[]): TexelPayload;
+export type Ktx2LevelIndexEntry = {
+    /**
+     * where this level's bytes are, from the start of the file
+     */
+    byte_offset: number;
+    /**
+     * how many of them there are, supercompressed
+     */
+    byte_length: number;
+    /**
+     * how many there are after inflation
+     */
+    uncompressed_byte_length: number;
+};
+//# sourceMappingURL=ktx2_read.d.ts.map

package/src/format/texture/ktx2/ktx2_read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2_read.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/ktx2/ktx2_read.js"],"names":[],"mappings":"AAuEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,iCAlBW,WAAW,GAAC,UAAU,qBACtB,gBAAc,eAAe,GAS3B,YAAY,CAgLxB;;;;;iBAgda,MAAM;;;;iBACN,MAAM;;;;8BACN,MAAM"}