@woosh/meep-engine 3.14.2 → 3.14.3

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

@@ -0,0 +1,909 @@
+import pako from "pako";
+import { assert } from "../../../core/assert.js";
+import { ByteCursor } from "../../../core/binary/ByteCursor.js";
+import { zstd_decompress } from "../../../core/binary/zstd/zstd_decompress.js";
+import { EndianType } from "../../../core/binary/EndianType.js";
+import { utf8_decode } from "../../../core/binary/utf8/utf8_decode.js";
+import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
+import {
+    gpu_texture_format_is_block_compressed,
+    gpu_texture_format_level_bytes
+} from "../../../shade/descriptor/texture/format/gpu_texture_format_info.js";
+import { texture_mip_extent } from "../../../shade/util/texture_mip_extent.js";
+import { transcode_basis, transcode_basis_carries_alpha, transcode_basis_formats } from "../basis/transcode_basis.js";
+import { transcode_uastc, transcode_uastc_formats } from "../basis/transcode_uastc.js";
+import { khr_df_model_name, KhrDfModel } from "./KhrDfModel.js";
+import { KTX2_IDENTIFIER } from "./KTX2_IDENTIFIER.js";
+import { ktx2_read_basis_lz_global_data } from "./ktx2_read_basis_lz_global_data.js";
+import { SupercompressionScheme } from "./SupercompressionScheme.js";
+import { vk_format_to_texture_format, VK_FORMAT_UNDEFINED } from "./vk_format_to_texture_format.js";
+
+/**
+ * Offset of the Data Format Descriptor's `colorModel` byte from the start of the DFD section:
+ * past `dfdTotalSize`, then past the basic block's first two words.
+ *
+ * @readonly
+ * @type {number}
+ */
+const DFD_COLOR_MODEL_OFFSET = 4 + 8;
+
+/**
+ * Bytes of the Data Format Descriptor's basic block that come before its samples.
+ *
+ * @readonly
+ * @type {number}
+ */
+const DFD_BASIC_BLOCK_BYTES = 24;
+
+/**
+ * Bytes each sample of the basic block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+const DFD_SAMPLE_BYTES = 16;
+
+/**
+ * Bytes each entry of the level index occupies — three 64-bit fields.
+ *
+ * @readonly
+ * @type {number}
+ */
+const LEVEL_INDEX_ENTRY_BYTES = 24;
+
+/**
+ * The only orientation this reader accepts, as the axis letters KTX2 writes them in.
+ *
+ * `r` then `d` is a top-left origin with rows running down, which is what `queue.writeTexture` takes
+ * and what every tool in this tree assumes; `i` is the third axis running away from the viewer,
+ * which is the order 3D slices are uploaded in. As many letters are checked as the texture has
+ * dimensions, so a 2D file is judged on `rd` alone.
+ *
+ * Deliberately strict about the third axis, which is the one that could go either way: `o` would
+ * mean the slices are stored back to front, and a volume loaded inside out is not a failure anybody
+ * would attribute to the reader. Refusing names the value, so a file that is genuinely fine is a
+ * one-line change here rather than a mystery.
+ *
+ * @readonly
+ * @type {string}
+ */
+const SUPPORTED_ORIENTATION = "rdi";
+
+/**
+ * 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, transcode_target = undefined) {
+    assert.defined(bytes, 'bytes');
+    assert.notNull(bytes, 'bytes');
+
+    // KTX2 is little-endian throughout, which is the one thing the cursor has to be told
+    const cursor = new ByteCursor().init(bytes, EndianType.LittleEndian);
+
+    read_identifier(cursor);
+
+    const vk_format = cursor.u32();
+    const type_size = cursor.u32();
+    const pixel_width = cursor.u32();
+    const pixel_height = cursor.u32();
+    const pixel_depth = cursor.u32();
+    const layer_count = cursor.u32();
+    const face_count = cursor.u32();
+    const level_count = cursor.u32();
+    const supercompression_scheme = cursor.u32();
+
+    const dfd_byte_offset = cursor.u32();
+    const dfd_byte_length = cursor.u32();
+    const kvd_byte_offset = cursor.u32();
+    const kvd_byte_length = cursor.u32();
+
+    /*
+     Where the supercompression global data sits. It holds the BasisLZ endpoint and selector
+     codebooks and the Huffman tables every image in the file shares, and it is read only when the
+     scheme says it is there — for every other scheme these two fields are zero.
+    */
+    const sgd_byte_offset = cursor.u64();
+    const sgd_byte_length = cursor.u64();
+
+    /*
+     The level index follows the header immediately, but the refusals below read from elsewhere in
+     the file and a cursor is one position. Remember where the index starts rather than depending on
+     which of them happened to move it, which is the kind of coupling that survives until someone
+     reorders two lines.
+    */
+    const level_index_position = cursor.position;
+
+    refuse_unsupported_supercompression(supercompression_scheme);
+
+    /*
+     A BasisLZ file's payload is ETC1S, which no device samples, so the format it ends up in is the
+     caller's choice rather than the file's. Every other file already holds a device format and the
+     caller's choice does not enter into it.
+    */
+    const basis_lz = supercompression_scheme === SupercompressionScheme.BasisLZ;
+
+    /*
+     UASTC is the other Basis encoding and does not use BasisLZ — every block stands alone, so there
+     is no global data and nothing to supercompress beyond an ordinary wrapper. It is told apart by
+     the same field ETC1S is: an undefined `vkFormat` and the descriptor's colour model.
+    */
+    const uastc = !basis_lz
+        && vk_format === VK_FORMAT_UNDEFINED
+        && read_dfd_color_model(cursor, dfd_byte_offset, dfd_byte_length) === KhrDfModel.UASTC;
+
+    const format = basis_lz || uastc
+        ? basis_target_format(cursor, dfd_byte_offset, dfd_byte_length, transcode_target, basis_lz)
+        : texture_format_of(cursor, vk_format, dfd_byte_offset, dfd_byte_length);
+
+    refuse_unsupported_shape(pixel_width, pixel_height, pixel_depth, layer_count, face_count, format);
+
+    if ((basis_lz || uastc) && (layer_count > 0 || face_count === 6)) {
+        /*
+         One image per level is what the transcoders take: a BasisLZ file's global data describes its
+         images level by level, and neither transcoder has a notion of a layer or a face. Refused by
+         name rather than transcoded as a stack nothing asked for.
+        */
+        throw new Error(
+            `KTX2: the payload is Basis Universal and the file is`
+            + ` ${layer_count > 0 ? `an array of ${layer_count} layers` : "a cube map"}. The transcoders`
+            + ` take one image per level; encode the layers as separate files, or in a device format.`
+        );
+    }
+
+    refuse_unsupported_metadata(cursor, kvd_byte_offset, kvd_byte_length, pixel_depth);
+
+    if (gpu_texture_format_is_block_compressed(format)) {
+        /*
+         The specification requires this of a block-compressed payload, and it is worth checking
+         rather than ignoring: `typeSize` is the width of the unit a big-endian host would byte-swap,
+         and a block has no such unit. A file claiming otherwise disagrees with itself about what its
+         own bytes are.
+        */
+        if (type_size !== 1) {
+            throw new Error(
+                `KTX2: typeSize is ${type_size} for '${format}', which is block-compressed and must`
+                + ` declare a typeSize of 1`
+            );
+        }
+
+        if (level_count === 0) {
+            throw new Error(
+                `KTX2: levelCount is 0 — "generate the mip chain at load" — for '${format}', which`
+                + ` is block-compressed. Nothing can generate mips for a block format: they come`
+                + ` from the encoder. Re-encode with a mip chain, or declare levelCount 1 and accept`
+                + ` a single-level texture.`
+            );
+        }
+    }
+
+    cursor.seek(level_index_position);
+
+    const level_index = read_level_index(cursor, Math.max(level_count, 1));
+
+    const levels = level_index.map(
+        (entry, level) => read_level(cursor, entry, level, supercompression_scheme)
+    );
+
+    if (uastc) {
+        /*
+         Nothing to gather: a UASTC level is its blocks and every block stands alone, so the levels
+         the index already located are the payload.
+        */
+        return transcode_uastc({ width: pixel_width, height: pixel_height, levels }, format);
+    }
+
+    if (basis_lz) {
+        const payload = ktx2_read_basis_lz_global_data(
+            bytes, sgd_byte_offset, sgd_byte_length, levels.length, levels,
+            read_dfd_sample_count(cursor, dfd_byte_offset, dfd_byte_length) === 2
+        );
+
+        payload.width = pixel_width;
+        payload.height = pixel_height;
+
+        /*
+         The transcoder builds the payload, because it is the thing that knows how many
+         bytes its own output came to. A reader that constructed one here would be asserting a byte
+         count for blocks it did not write.
+        */
+        return transcode_basis(payload, format);
+    }
+
+    const depth = Math.max(pixel_depth, 1);
+    const layers = Math.max(layer_count, 1);
+    const faces = face_count;
+
+    /*
+     A level is exactly as many bytes as its format and extent imply — times the images it holds, for
+     an array or a cube map — and a file whose level index
+     says otherwise is mislabelled — its `vkFormat` or its dimensions are lying about the bytes below
+     them, and a payload that uploads without complaint renders garbage. Checked against the format
+     table here rather than left to the engine because this reader's contract is "the file's levels,
+     each the right size", to a node tool as much as to a renderer. Whether the *number* of levels is
+     one the engine can take is the engine's question, and `texel_data_from_ktx2` asks it.
+
+     The transcoded paths above need no such check: the transcoder wrote those bytes itself.
+    */
+    const images_per_level = layers * faces;
+
+    for (let level = 0; level < levels.length; level++) {
+        const extent = texture_mip_extent(pixel_width, pixel_height, depth, "3d", level);
+        const expected = gpu_texture_format_level_bytes(format, extent[0], extent[1], extent[2])
+            * images_per_level;
+
+        if (levels[level].byteLength !== expected) {
+            throw new Error(
+                `KTX2: level ${level} of a ${pixel_width}x${pixel_height}x${depth} '${format}' payload`
+                + (images_per_level > 1 ? ` holding ${images_per_level} images` : "")
+                + ` should be ${expected} bytes, got ${levels[level].byteLength}`
+            );
+        }
+    }
+
+    return { format, width: pixel_width, height: pixel_height, depth, layers, faces, levels };
+}
+
+/**
+ * @param {ByteCursor} cursor positioned at the start of the file
+ * @throws {Error} for anything that is not a KTX2 file
+ */
+function read_identifier(cursor) {
+    if (cursor.remaining < KTX2_IDENTIFIER.length) {
+        throw new Error(
+            `KTX2: a ${cursor.remaining} byte input is too short to hold the 12 byte identifier`
+        );
+    }
+
+    const identifier = cursor.view_bytes(KTX2_IDENTIFIER.length);
+
+    if (!isArrayEqualStrict(identifier, KTX2_IDENTIFIER)) {
+        const found = Array.from(identifier, byte => byte.toString(16).padStart(2, "0")).join(" ");
+
+        throw new Error(
+            `KTX2: identifier mismatch. Expected AB 4B 54 58 20 32 30 BB 0D 0A 1A 0A, found ${found}.`
+            + ` This is not a KTX2 file — a KTX1 file starts AB 4B 54 58 20 31 31 BB.`
+        );
+    }
+}
+
+/**
+ * @param {SupercompressionScheme|number} scheme
+ * @throws {Error} for a scheme from a later revision of the specification, which cannot be read by
+ * guessing what its levels contain
+ */
+function refuse_unsupported_supercompression(scheme) {
+    if (
+        scheme === SupercompressionScheme.None
+        || scheme === SupercompressionScheme.ZLIB
+        || scheme === SupercompressionScheme.Zstandard
+        || scheme === SupercompressionScheme.BasisLZ
+    ) {
+        return;
+    }
+
+    throw new Error(
+        `KTX2: supercompressionScheme ${scheme} is not one this reader knows — the specification`
+        + ` defines 0 (None), 1 (BasisLZ), 2 (Zstandard) and 3 (ZLIB). A file from a later revision`
+        + ` cannot be read by guessing what its levels contain.`
+    );
+}
+
+/**
+ * The format a BasisLZ file's payload will be transcoded into.
+ *
+ * Unlike every other path through this reader, the answer is not in the file. A BasisLZ payload is
+ * ETC1S, which nothing samples, so what it becomes depends on the device and on which material slot
+ * the texture fills — see `texture_format_preference`. That makes it the caller's to state, and a
+ * caller that has not stated it gets a refusal rather than a guess.
+ *
+ * @param {ByteCursor} cursor
+ * @param {number} dfd_byte_offset
+ * @param {number} dfd_byte_length
+ * @param {TextureFormat|undefined} transcode_target
+ * @returns {TextureFormat}
+ * @throws {Error} for a payload that is not ETC1S, or for no target
+ */
+function basis_target_format(
+    cursor, dfd_byte_offset, dfd_byte_length, transcode_target, basis_lz
+) {
+    const color_model = read_dfd_color_model(cursor, dfd_byte_offset, dfd_byte_length);
+
+    if (basis_lz && color_model !== KhrDfModel.ETC1S) {
+        /*
+         BasisLZ is defined only over ETC1S — a UASTC file carries its blocks uncompressed or behind
+         an ordinary wrapper and never sets this scheme. A file that pairs them is malformed, and
+         saying which two things disagree beats failing later inside a codebook read.
+        */
+        throw new Error(
+            `KTX2: the file declares BasisLZ supercompression, whose payload is always ETC1S, and`
+            + ` its Data Format Descriptor says the colour model is`
+            + ` ${color_model === undefined ? "nothing this reader could read" : khr_df_model_name(color_model)}.`
+        );
+    }
+
+    if (transcode_target === undefined) {
+        throw new Error(
+            `KTX2: the payload is Basis Universal ${khr_df_model_name(color_model)}, which is`
+            + ` transcoded to a device format rather than sampled, and no target format was given.`
+            + ` Pass one — from texture_format_preference(role, support), which is what knows the`
+            + ` device's capabilities and the texture's role.`
+        );
+    }
+
+    if (!Array.isArray(transcode_target)) {
+        return transcode_target;
+    }
+
+    if (transcode_target.length === 0) {
+        throw new Error(
+            `KTX2: the payload is Basis Universal ${khr_df_model_name(color_model)} and the list of`
+            + ` acceptable transcode targets was empty. Pass at least one.`
+        );
+    }
+
+    /*
+     **Choosing from a list is what lets the payload decide.** A caller ranks targets by what the
+     device can sample and what the texture is for. What it cannot rank them by is anything about
+     *this file* — which of the two Basis encodings it holds, and whether it carries alpha — because
+     neither is known until something reads the descriptor, which happens here.
+
+     Two things can rule a target out, and both would otherwise surface as a refusal thrown after the
+     caller had committed, with no second chance to pick differently:
+
+     1. **The encoding's transcoder does not write it.** The two write overlapping but different
+        sets — only UASTC reaches BC5, only ETC1S reaches BC1 — so a list headed by a format the
+        file's own encoding cannot produce has to move down rather than fail. An ASTC-first device
+        loading a model whose normal maps are UASTC hits exactly this.
+     2. **It has no room for the payload's alpha**, which is an ETC1S question: its alpha is a second
+        slice that a target either has somewhere to put or does not. UASTC carries alpha inside the
+        block, and its BC5 target drops channels deliberately because a normal map has none worth
+        keeping, so nothing there is ruled out on those grounds.
+    */
+    const writable = basis_lz ? transcode_basis_formats() : transcode_uastc_formats();
+
+    const supported = transcode_target.filter(
+        format => writable.includes(strip_srgb(format))
+    );
+
+    if (!basis_lz) {
+        return first_or_refuse(supported, transcode_target, color_model, "this encoding cannot produce");
+    }
+
+    const has_alpha = read_dfd_sample_count(cursor, dfd_byte_offset, dfd_byte_length) === 2;
+
+    if (!has_alpha) {
+        return first_or_refuse(supported, transcode_target, color_model, "this encoding cannot produce");
+    }
+
+    return first_or_refuse(
+        supported.filter(format => transcode_basis_carries_alpha(format)),
+        transcode_target,
+        color_model,
+        "can hold this payload's alpha"
+    );
+}
+
+/**
+ * An sRGB format's linear spelling, which is the one a transcoder's format list names.
+ *
+ * The two are the same blocks — which one a texture is created with is decided from the image's
+ * colour space, not here — so a caller may legitimately ask for either and a list that only knows
+ * the linear name would pass over the sRGB one for no reason.
+ *
+ * @param {TextureFormat} format
+ * @returns {TextureFormat}
+ */
+function strip_srgb(format) {
+    return format.endsWith("-srgb") ? format.slice(0, -"-srgb".length) : format;
+}
+
+/**
+ * The head of a filtered list, or a refusal naming what was offered and what was wrong with it.
+ *
+ * @param {TextureFormat[]} usable
+ * @param {TextureFormat[]} offered the caller's whole list, for the message
+ * @param {number} color_model
+ * @param {string} requirement what none of them met, as a phrase completing "none of them ..."
+ * @returns {TextureFormat}
+ * @throws {Error} when nothing is usable
+ */
+function first_or_refuse(usable, offered, color_model, requirement) {
+    if (usable.length > 0) {
+        return usable[0];
+    }
+
+    throw new Error(
+        `KTX2: the payload is Basis Universal ${khr_df_model_name(color_model)} and none of the`
+        + ` targets offered ${requirement}: ${offered.join(", ")}. 'rgba8unorm' always can, and is`
+        + ` what a caller should put at the end of its list.`
+    );
+}
+
+/**
+ * How many samples the Data Format Descriptor's basic block describes.
+ *
+ * For an ETC1S payload this is how the file says whether it carries alpha: one sample is colour
+ * alone, two is colour plus an alpha slice in every image. There is no other field that says so —
+ * the image descriptors carry alpha slice lengths, but reading a zero there would confuse "no alpha"
+ * with "alpha that happens to be empty".
+ *
+ * @param {ByteCursor} cursor
+ * @param {number} byte_offset of the DFD section
+ * @param {number} byte_length
+ * @returns {number}
+ * @throws {Error} for a descriptor block whose size is not a whole number of samples past the fixed
+ * part, which means it is not the basic block this expects
+ */
+function read_dfd_sample_count(cursor, byte_offset, byte_length) {
+    if (byte_offset === 0 || byte_length < DFD_BASIC_BLOCK_BYTES) {
+        throw new Error(
+            `KTX2: an ETC1S payload needs a Data Format Descriptor to say whether it has alpha, and`
+            + ` this file's is ${byte_length} bytes`
+        );
+    }
+
+    // past dfdTotalSize, then past the first word, to the descriptorBlockSize half of the second
+    cursor.seek(byte_offset + 4 + 6);
+
+    const descriptor_block_bytes = cursor.u16();
+
+    const sample_bytes = descriptor_block_bytes - DFD_BASIC_BLOCK_BYTES;
+
+    if (sample_bytes < 0 || sample_bytes % DFD_SAMPLE_BYTES !== 0) {
+        throw new Error(
+            `KTX2: the Data Format Descriptor's basic block is ${descriptor_block_bytes} bytes,`
+            + ` which is not ${DFD_BASIC_BLOCK_BYTES} plus a whole number of`
+            + ` ${DFD_SAMPLE_BYTES} byte samples`
+        );
+    }
+
+    return sample_bytes / DFD_SAMPLE_BYTES;
+}
+
+/**
+ * The `GPUTextureFormat` a file's payload is already in.
+ *
+ * @param {ByteCursor} cursor
+ * @param {number} vk_format
+ * @param {number} dfd_byte_offset
+ * @param {number} dfd_byte_length
+ * @returns {TextureFormat}
+ * @throws {Error} naming the encoding, for a payload that is not in a device format
+ */
+function texture_format_of(cursor, vk_format, dfd_byte_offset, dfd_byte_length) {
+    if (vk_format !== VK_FORMAT_UNDEFINED) {
+        return vk_format_to_texture_format(vk_format);
+    }
+
+    /*
+     `VK_FORMAT_UNDEFINED` is not "no format". It is how a Basis Universal payload is spelled, and
+     the Data Format Descriptor's colour model is the only field that says which of the two encodings
+     it holds. Reading it costs one byte and turns "vkFormat 0" — which says nothing — into the name
+     of the transcoder the file needs.
+    */
+    const color_model = read_dfd_color_model(cursor, dfd_byte_offset, dfd_byte_length);
+
+    if (color_model === KhrDfModel.ETC1S) {
+        /*
+         Reachable only for an ETC1S payload that is not behind BasisLZ, which the specification does
+         not describe: the codebooks and Huffman tables an ETC1S slice is decoded against live in the
+         supercompression global data, and a file declaring no supercompression has none.
+        */
+        throw new Error(
+            `KTX2: the payload is Basis Universal ETC1S and the file declares no BasisLZ`
+            + ` supercompression, so it carries no endpoint or selector codebooks. Its slices are`
+            + ` indices into tables that are not present.`
+        );
+    }
+
+    throw new Error(
+        `KTX2: vkFormat is VK_FORMAT_UNDEFINED, so the payload's encoding is whatever the Data Format`
+        + ` Descriptor says — and it says ${color_model === undefined
+            ? "nothing this reader could read"
+            : khr_df_model_name(color_model)}.`
+        + ` Only ETC1S and UASTC use an undefined vkFormat, and neither is supported.`
+    );
+}
+
+/**
+ * @param {ByteCursor} cursor
+ * @param {number} byte_offset of the DFD section, `0` when there is none
+ * @param {number} byte_length
+ * @returns {KhrDfModel|number|undefined} `undefined` when the file has no DFD, or one too short to
+ * hold a basic descriptor block's colour model
+ */
+function read_dfd_color_model(cursor, byte_offset, byte_length) {
+    if (byte_offset === 0 || byte_length <= DFD_COLOR_MODEL_OFFSET) {
+        return undefined;
+    }
+
+    if (byte_offset + DFD_COLOR_MODEL_OFFSET >= cursor.end) {
+        return undefined;
+    }
+
+    cursor.seek(byte_offset + DFD_COLOR_MODEL_OFFSET);
+
+    return cursor.u8();
+}
+
+/**
+ * @param {number} pixel_width
+ * @param {number} pixel_height
+ * @param {number} pixel_depth
+ * @param {number} layer_count `0` for a texture that is not an array
+ * @param {number} face_count `1`, or `6` for a cube map
+ * @param {TextureFormat} format
+ * @throws {Error} for a shape a {@link TexelPayload} cannot describe — arrays and cube maps are not
+ * among them; a 3D array is, because WebGPU has no such texture
+ */
+function refuse_unsupported_shape(
+    pixel_width, pixel_height, pixel_depth, layer_count, face_count, format
+) {
+    if (pixel_width === 0) {
+        throw new Error("KTX2: pixelWidth is 0, which no texture has");
+    }
+
+    if (pixel_height === 0) {
+        throw new Error(
+            "KTX2: pixelHeight is 0, which is a 1D texture. The payload describes a 2D or 3D"
+            + " image only, and nothing in the engine samples a 1D texture."
+        );
+    }
+
+    if (face_count !== 1 && face_count !== 6) {
+        throw new Error(`KTX2: faceCount is ${face_count}, which is neither 1 nor 6`);
+    }
+
+    if (pixel_depth > 0 && (layer_count > 0 || face_count === 6)) {
+        /*
+         Vulkan has no 3D array or 3D cube image and neither does WebGPU: a "3d" texture's third
+         extent is its depth, and layers are the third extent of a "2d" one. A file claiming both
+         has nowhere to put one of them.
+        */
+        throw new Error(
+            `KTX2: pixelDepth is ${pixel_depth} and the file is`
+            + ` ${layer_count > 0 ? `an array of ${layer_count} layers` : "a cube map"}. A 3D texture`
+            + ` has no layers — WebGPU's third extent is depth or array layers, never both.`
+        );
+    }
+
+    if (pixel_depth > 0 && gpu_texture_format_is_block_compressed(format)) {
+        /*
+         Sampling a block-compressed 3D texture needs `texture-compression-bc-sliced-3d` or its ASTC
+         counterpart, neither of which the renderer requests, and the block layout of a 3D level is
+         not the 2D one repeated per slice for every format. Refusing beats producing a payload whose
+         byte lengths happen to add up.
+        */
+        throw new Error(
+            `KTX2: pixelDepth is ${pixel_depth} and the format is '${format}', which is`
+            + ` block-compressed. A 3D block-compressed texture needs a sliced-3d device feature that`
+            + ` the renderer does not request.`
+        );
+    }
+}
+
+/**
+ * Refuse a file whose metadata says its texels are arranged in a way nothing here rearranges.
+ *
+ * Both keys are cheap to read and expensive to ignore: a flipped orientation renders the texture
+ * upside down and a non-identity swizzle renders it in the wrong channels, and neither failure looks
+ * like a bug in the reader.
+ *
+ * @param {ByteCursor} cursor
+ * @param {number} kvd_byte_offset `0` when the file carries no key/value data
+ * @param {number} kvd_byte_length
+ * @param {number} pixel_depth
+ * @throws {Error} naming the key and its value
+ */
+function refuse_unsupported_metadata(cursor, kvd_byte_offset, kvd_byte_length, pixel_depth) {
+    if (kvd_byte_offset === 0 || kvd_byte_length === 0) {
+        // absent means the default, which is the orientation and swizzle this reader wants
+        return;
+    }
+
+    const key_values = read_key_values(cursor, kvd_byte_offset, kvd_byte_length);
+
+    const orientation = key_values.get("KTXorientation");
+
+    if (orientation !== undefined) {
+        const axes = pixel_depth > 0 ? 3 : 2;
+        const expected = SUPPORTED_ORIENTATION.slice(0, axes);
+
+        if (orientation.slice(0, axes) !== expected) {
+            throw new Error(
+                `KTX2: KTXorientation is '${orientation}', and only '${expected}' is supported —`
+                + ` a top-left origin with rows running down, which is the arrangement`
+                + ` queue.writeTexture takes. Flipping the payload would mean re-encoding every`
+                + ` block, which is the encoder's job.`
+            );
+        }
+    }
+
+    const swizzle = key_values.get("KTXswizzle");
+
+    if (swizzle !== undefined && swizzle !== "rgba") {
+        throw new Error(
+            `KTX2: KTXswizzle is '${swizzle}', and only the identity 'rgba' is supported. Applying a`
+            + ` swizzle means rewriting the texels, which for a block format means re-encoding them.`
+        );
+    }
+}
+
+/**
+ * The file's key/value data, as strings.
+ *
+ * Every value KTX2 defines is a NUL-terminated string, and a value this reader does not recognise is
+ * never looked at, so decoding them all as text costs nothing and keeps the caller simple. A value
+ * that is genuinely binary decodes to nonsense and is ignored, which is what an unrecognised key
+ * gets either way.
+ *
+ * @param {ByteCursor} cursor
+ * @param {number} byte_offset
+ * @param {number} byte_length
+ * @returns {Map<string, string>}
+ * @throws {Error} for a section that runs past the end of the file, or an entry that runs past the
+ * end of the section
+ */
+function read_key_values(cursor, byte_offset, byte_length) {
+    if (byte_offset + byte_length > cursor.end) {
+        throw new Error(
+            `KTX2: the key/value section [${byte_offset}, ${byte_offset + byte_length}) runs past`
+            + ` the end of a ${cursor.end} byte file`
+        );
+    }
+
+    const section = cursor.sub_cursor(byte_offset, byte_length);
+
+    const result = new Map();
+
+    // four bytes is the smallest an entry's length field can be; a shorter tail is the padding of
+    // the last entry rather than the start of another one
+    while (section.remaining >= 4) {
+        const entry_byte_length = section.u32();
+
+        const entry_start = section.position;
+
+        if (entry_byte_length > section.remaining) {
+            throw new Error(
+                `KTX2: a key/value entry declares ${entry_byte_length} bytes with only`
+                + ` ${section.remaining} left in the section`
+            );
+        }
+
+        // the key is NUL-terminated and the value is whatever follows it, to the entry's end
+        const key = section.utf8_string();
+
+        const key_bytes = section.position - entry_start;
+
+        if (key_bytes > entry_byte_length) {
+            throw new Error(
+                `KTX2: the key/value entry '${key}' has no NUL terminator inside its own`
+                + ` ${entry_byte_length} bytes`
+            );
+        }
+
+        const value_bytes = section.view_bytes(entry_byte_length - key_bytes);
+
+        result.set(key, decode_key_value(value_bytes));
+
+        // entries are padded to a four byte boundary, and the padding is not part of the value
+        section.skip(Math.min((4 - (entry_byte_length % 4)) % 4, section.remaining));
+    }
+
+    return result;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} the value, without the NUL that terminates it
+ */
+function decode_key_value(bytes) {
+    const end = bytes.indexOf(0);
+
+    return utf8_decode(bytes, 0, end === -1 ? bytes.length : end);
+}
+
+/**
+ * @typedef {Object} Ktx2LevelIndexEntry
+ * @property {number} byte_offset where this level's bytes are, from the start of the file
+ * @property {number} byte_length how many of them there are, supercompressed
+ * @property {number} uncompressed_byte_length how many there are after inflation
+ */
+
+/**
+ * @param {ByteCursor} cursor positioned at the start of the level index
+ * @param {number} entry_count `levelCount`, or `1` when that is zero
+ * @returns {Ktx2LevelIndexEntry[]} index 0 first, which is the base level
+ * @throws {Error} for an index that runs past the end of the file
+ */
+function read_level_index(cursor, entry_count) {
+    cursor.require(entry_count * LEVEL_INDEX_ENTRY_BYTES, `level index of ${entry_count} levels`);
+
+    const entries = [];
+
+    for (let i = 0; i < entry_count; i++) {
+        entries.push({
+            byte_offset: cursor.u64(),
+            byte_length: cursor.u64(),
+            uncompressed_byte_length: cursor.u64(),
+        });
+    }
+
+    return entries;
+}
+
+/**
+ * One level's texel bytes, inflated if the file supercompressed them.
+ *
+ * @param {ByteCursor} cursor
+ * @param {Ktx2LevelIndexEntry} entry
+ * @param {number} level `0` is the base
+ * @param {SupercompressionScheme|number} scheme already known to be one of the two supported ones
+ * @returns {Uint8Array} a view onto the file where the scheme is `None`, its own memory otherwise
+ * @throws {Error} naming the level, for one that runs past the end of the file or inflates to the
+ * wrong size
+ */
+function read_level(cursor, entry, level, scheme) {
+    const { byte_offset, byte_length, uncompressed_byte_length } = entry;
+
+    /*
+     Checked here rather than left to the cursor because the cursor's message names a byte range and
+     this one names the level, which is the difference between a file that is truncated and a level
+     index that points somewhere it should not.
+    */
+    if (byte_offset + byte_length > cursor.end) {
+        throw new Error(
+            `KTX2: level ${level} claims bytes [${byte_offset}, ${byte_offset + byte_length}) of a`
+            + ` ${cursor.end} byte file, which is past its end`
+        );
+    }
+
+    cursor.seek(byte_offset);
+
+    const stored = cursor.view_bytes(byte_length);
+
+    if (scheme === SupercompressionScheme.None || scheme === SupercompressionScheme.BasisLZ) {
+        /*
+         A view, not a copy. The level data is nearly the whole of a texture file, and `writeTexture`
+         takes a view as readily as it takes its own array — copying here would double the peak
+         memory of every texture load to no end.
+
+         BasisLZ belongs on this side of the branch even though it is nominally a supercompression
+         scheme: its level bytes are the ETC1S slices themselves, entropy-coded against codebooks in
+         the global data. Undoing that is the transcoder's, and there is nothing to unwrap here —
+         which is also why such a level declares an `uncompressedByteLength` of zero.
+        */
+        return stored;
+    }
+
+    /*
+     `pako.inflate` rather than `png_inflate`: what that function adds over this call is PNG's two
+     peculiarities — a stream split across IDAT chunks, and a fallback that abandons the adler32
+     check because real encoders get it wrong. A KTX2 level is one stream, and a texture payload
+     whose checksum fails should fail rather than decode to blocks nobody verified.
+
+     What it also adds, and what this has to do for itself: **pako throws a bare string.** Not an
+     Error — `"incorrect header check"`, with no stack, no `.message`, and nothing saying which file
+     or which level it came from. Letting that escape would make the one path this reader adds beyond
+     the plan the one path that does not refuse by name.
+    */
+    let inflated;
+
+    if (scheme === SupercompressionScheme.Zstandard) {
+        /*
+         The level declares what it inflates to, so the frame's own declared size is checked against
+         it rather than trusted — a Zstandard frame carries its content size and a KTX2 level carries
+         it too, and a file where the two disagree is one where something has been re-wrapped without
+         being re-indexed.
+        */
+        try {
+            inflated = zstd_decompress(stored, uncompressed_byte_length);
+        } catch (error) {
+            throw new Error(
+                `KTX2: level ${level} is not a readable Zstandard frame: ${error?.message ?? error}`
+            );
+        }
+    } else {
+        try {
+            inflated = pako.inflate(stored);
+        } catch (error) {
+            throw new Error(
+                `KTX2: level ${level} is not a readable zlib stream: ${error?.message ?? error}`
+            );
+        }
+    }
+
+    if (uncompressed_byte_length !== inflated.byteLength) {
+        throw new Error(
+            `KTX2: level ${level} declares an uncompressedByteLength of ${uncompressed_byte_length}`
+            + ` but inflates to ${inflated.byteLength} bytes`
+        );
+    }
+
+    return inflated;
+}