@woosh/meep-engine 3.14.1 → 3.14.2

package/src/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/ktx2/KTX2_IDENTIFIER.d.ts.map

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

package/src/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/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/ktx2/KhrDfModel.d.ts.map

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

package/src/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/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/ktx2/SupercompressionScheme.d.ts.map

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

package/src/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/ktx2/ktx2_read.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Read a KTX2 file into the texel payload the engine uploads.
+ *
+ * **The whole contract is `bytes -> ShadeTexelData`.** 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. What it produces is the ordinary payload — a compressed texture entering this way
+ * is indistinguishable, below `ShadeImage`, from one that arrived any other way.
+ *
+ * **What it reads.** A file whose payload is already in a format WebGPU can sample: any `vkFormat`
+ * that maps to a `GPUTextureFormat` (see {@link vk_format_to_texture_format}), with
+ * {@link SupercompressionScheme.None} or {@link SupercompressionScheme.ZLIB}. That is what
+ * first-party tooling emits, and it needs no transcoder.
+ *
+ * **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 |
+ * |---|---|
+ * | {@link SupercompressionScheme.BasisLZ} | ETC1S, and a transcoder is not a decompressor |
+ * | {@link SupercompressionScheme.Zstandard} | there is no Zstandard decompressor in this repository |
+ * | `VK_FORMAT_UNDEFINED` (ETC1S / UASTC) | Basis Universal, transcoded rather than sampled |
+ * | an unmapped `vkFormat` | WebGPU does not expose it |
+ * | `layerCount > 0`, `faceCount == 6` | array and cube textures, which {@link ShadeTexelData} does not model |
+ * | `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
+ * @returns {ShadeTexelData}
+ * @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): ShadeTexelData;
+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;
+};
+import { ShadeTexelData } from "../shade/renderer/texture/source/ShadeTexelData.js";
+//# sourceMappingURL=ktx2_read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2_read.d.ts","sourceRoot":"","sources":["../../../src/ktx2/ktx2_read.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,iCATW,WAAW,GAAC,UAAU,GACpB,cAAc,CA2F1B;;;;;iBA4Sa,MAAM;;;;iBACN,MAAM;;;;8BACN,MAAM;;+BAheW,oDAAoD"}