@woosh/meep-engine 3.14.1 → 3.14.2

package/src/ktx2/ktx2_read_basis_lz_global_data.js

@@ -0,0 +1,189 @@
+import { ByteCursor } from "../core/binary/ByteCursor.js";
+import { EndianType } from "../core/binary/EndianType.js";
+
+/**
+ * Bytes the global data header occupies: two 16-bit counts and four 32-bit lengths.
+ *
+ * @readonly
+ * @type {number}
+ */
+const GLOBAL_HEADER_BYTES = 20;
+
+/**
+ * Bytes each image descriptor occupies: a flags word and two offset/length pairs.
+ *
+ * @readonly
+ * @type {number}
+ */
+const IMAGE_DESC_BYTES = 20;
+
+/**
+ * The image flag marking a frame that refers to the one before it.
+ *
+ * @readonly
+ * @type {number}
+ */
+const IMAGE_FLAG_IS_P_FRAME = 0x02;
+
+/**
+ * Read the BasisLZ supercompression global data.
+ *
+ * This is the codebook every image in the file shares — endpoints, selectors and Huffman tables —
+ * plus one descriptor per image saying where that image's slices sit inside its mip level. The
+ * structure is the *container's*, defined by KTX2 rather than by Basis; what is inside the four
+ * sections is the codec's, and is decoded by the transcoder.
+ *
+ * **Slice offsets are relative to their own mip level**, not to the file, which is why the level
+ * bytes are passed in already located rather than the file being re-walked here.
+ *
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {number} byte_offset of the global data section, from `sgdByteOffset`
+ * @param {number} byte_length from `sgdByteLength`
+ * @param {number} image_count one per level, for the 2D non-array textures this reader accepts
+ * @param {Uint8Array[]} level_bytes one per level, base first, as located by the level index
+ * @param {boolean} has_alpha whether the file's images carry a second slice, from the descriptor
+ * @returns {import("../basis/transcode_basis.js").BasisEtc1sPayload} without its dimensions, which
+ * the caller holds
+ * @throws {Error} naming the field, for global data that is truncated or disagrees with itself
+ *
+ * @see the KTX2 specification, Appendix C
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function ktx2_read_basis_lz_global_data(
+    bytes, byte_offset, byte_length, image_count, level_bytes, has_alpha
+) {
+    if (byte_offset === 0 || byte_length === 0) {
+        throw new Error(
+            "KTX2: the file declares BasisLZ supercompression and carries no supercompression global"
+            + " data. The endpoint and selector codebooks live there, and without them the levels"
+            + " are a stream of indices into nothing."
+        );
+    }
+
+    const cursor = new ByteCursor().init(bytes, EndianType.LittleEndian);
+
+    cursor.seek(byte_offset);
+
+    const endpoint_count = cursor.u16();
+    const selector_count = cursor.u16();
+    const endpoints_byte_length = cursor.u32();
+    const selectors_byte_length = cursor.u32();
+    const tables_byte_length = cursor.u32();
+    const extended_byte_length = cursor.u32();
+
+    /*
+     The specification requires this exactly, and checking it is worth the two lines: every section
+     below is located by adding lengths, so a header that does not add up produces sections that
+     overlap or run past the end, and the failure would surface as a corrupt Huffman table rather
+     than as a malformed file.
+    */
+    const expected_byte_length = GLOBAL_HEADER_BYTES
+        + IMAGE_DESC_BYTES * image_count
+        + endpoints_byte_length
+        + selectors_byte_length
+        + tables_byte_length
+        + extended_byte_length;
+
+    if (byte_length !== expected_byte_length) {
+        throw new Error(
+            `KTX2: sgdByteLength is ${byte_length}, and the header's own section lengths add up to`
+            + ` ${expected_byte_length} for ${image_count} image${image_count === 1 ? "" : "s"}`
+        );
+    }
+
+    if (extended_byte_length !== 0) {
+        throw new Error(
+            `KTX2: the BasisLZ global data declares ${extended_byte_length} bytes of extended data,`
+            + ` and the specification requires 0 for an ETC1S payload`
+        );
+    }
+
+    if (endpoint_count === 0 || selector_count === 0) {
+        throw new Error(
+            `KTX2: the BasisLZ global data declares ${endpoint_count} endpoints and`
+            + ` ${selector_count} selectors, and a slice's indices refer into both`
+        );
+    }
+
+    const images = [];
+
+    for (let image = 0; image < image_count; image++) {
+        const flags = cursor.u32();
+        const rgb_byte_offset = cursor.u32();
+        const rgb_byte_length = cursor.u32();
+        const alpha_byte_offset = cursor.u32();
+        const alpha_byte_length = cursor.u32();
+
+        if ((flags & IMAGE_FLAG_IS_P_FRAME) !== 0) {
+            /*
+             A P-frame's blocks may copy their indices from the previous frame, which needs the
+             frames decoded in order and the previous one kept. Nothing here plays a video texture,
+             and a still image never sets this — so refusing names the feature rather than decoding
+             the frame as though every block stood alone, which would be wrong exactly where the
+             encoder saved the most.
+            */
+            throw new Error(
+                `KTX2: image ${image} is a P frame of an animation sequence, which refers to the`
+                + ` frame before it. Texture video is not transcoded here.`
+            );
+        }
+
+        const level = level_bytes[image];
+
+        images.push({
+            rgb: slice_of(level, rgb_byte_offset, rgb_byte_length, image, "rgb"),
+            alpha: has_alpha
+                ? slice_of(level, alpha_byte_offset, alpha_byte_length, image, "alpha")
+                : undefined,
+        });
+    }
+
+    const endpoints = cursor.view_bytes(endpoints_byte_length);
+    const selectors = cursor.view_bytes(selectors_byte_length);
+    const tables = cursor.view_bytes(tables_byte_length);
+
+    return {
+        has_alpha,
+        endpoint_count,
+        selector_count,
+        endpoints,
+        selectors,
+        tables,
+        images,
+    };
+}
+
+/**
+ * One slice, as a view into its mip level's bytes.
+ *
+ * @param {Uint8Array} level
+ * @param {number} byte_offset within `level`
+ * @param {number} byte_length
+ * @param {number} image for the error message
+ * @param {string} which for the error message
+ * @returns {Uint8Array}
+ * @throws {Error} for a slice that runs past its level
+ */
+function slice_of(level, byte_offset, byte_length, image, which) {
+    if (level === undefined) {
+        throw new Error(
+            `KTX2: the BasisLZ global data describes image ${image}, and the level index has no`
+            + ` level for it`
+        );
+    }
+
+    if (byte_length === 0) {
+        throw new Error(`KTX2: image ${image} declares an empty ${which} slice`);
+    }
+
+    if (byte_offset + byte_length > level.byteLength) {
+        throw new Error(
+            `KTX2: image ${image}'s ${which} slice claims bytes`
+            + ` [${byte_offset}, ${byte_offset + byte_length}) of a ${level.byteLength} byte mip`
+            + ` level, which is past its end`
+        );
+    }
+
+    return level.subarray(byte_offset, byte_offset + byte_length);
+}

package/src/ktx2/vk_format_to_texture_format.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Every `vkFormat` this module maps, for a test that wants to sweep them.
+ *
+ * @returns {number[]}
+ */
+export function vk_formats_mapped(): number[];
+/**
+ * Every `vkFormat` this module names but deliberately does not map, for the test that keeps the two
+ * tables from overlapping.
+ *
+ * @returns {number[]}
+ */
+export function vk_formats_unmappable(): number[];
+/**
+ * The Vulkan name of `vk_format`, where this module knows it.
+ *
+ * @param {number} vk_format
+ * @returns {string} the `VK_FORMAT_…` name, or `vkFormat <n>` for one outside both tables
+ */
+export function vk_format_name(vk_format: number): string;
+/**
+ * The {@link TextureFormat} holding the same bytes as `vk_format`.
+ *
+ * Byte for byte, not approximately: every mapping here is a pair of names for one memory layout, so
+ * a payload passes through unchanged and the only thing the mapping decides is what the sampler is
+ * told about it. The single caveat is BC1, noted beside its rows in the table.
+ *
+ * @param {number} vk_format as read from a KTX2 header
+ * @returns {TextureFormat}
+ * @throws {Error} naming the format, for one WebGPU does not expose
+ */
+export function vk_format_to_texture_format(vk_format: number): TextureFormat;
+/**
+ * `VkFormat` numbers that map onto a {@link TextureFormat}, and the ones that deliberately do not.
+ *
+ * KTX2 names its payload's encoding with a Vulkan format number, so reading one means owning a
+ * corner of Vulkan's enumeration. Only the part WebGPU also exposes can be mapped; everything else
+ * is a refusal, and the point of writing the refusals down beside the mappings is that a file the
+ * engine cannot use says *which* format it holds instead of failing somewhere downstream with a
+ * number nobody recognises.
+ *
+ * @see https://registry.khronos.org/vulkan/specs/latest/man/html/VkFormat.html
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * `VK_FORMAT_UNDEFINED`. In a KTX2 file this does not mean "no format" — it means the payload is
+ * Basis Universal and the Data Format Descriptor, not `vkFormat`, says which of the two it is.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const VK_FORMAT_UNDEFINED: number;
+import { TextureFormat } from "../shade/descriptor/texture/format/TextureFormat.js";
+//# sourceMappingURL=vk_format_to_texture_format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vk_format_to_texture_format.d.ts","sourceRoot":"","sources":["../../../src/ktx2/vk_format_to_texture_format.js"],"names":[],"mappings":"AAqOA;;;;GAIG;AACH,qCAFa,MAAM,EAAE,CAIpB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,EAAE,CAIpB;AAED;;;;;GAKG;AACH,0CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,uDAJW,MAAM,GACJ,aAAa,CAuBzB;AA/RD;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,kCAFU,MAAM,CAEqB;8BAvBP,qDAAqD"}

package/src/ktx2/vk_format_to_texture_format.js

@@ -0,0 +1,290 @@
+import { TextureFormat } from "../shade/descriptor/texture/format/TextureFormat.js";
+
+/**
+ * `VkFormat` numbers that map onto a {@link TextureFormat}, and the ones that deliberately do not.
+ *
+ * KTX2 names its payload's encoding with a Vulkan format number, so reading one means owning a
+ * corner of Vulkan's enumeration. Only the part WebGPU also exposes can be mapped; everything else
+ * is a refusal, and the point of writing the refusals down beside the mappings is that a file the
+ * engine cannot use says *which* format it holds instead of failing somewhere downstream with a
+ * number nobody recognises.
+ *
+ * @see https://registry.khronos.org/vulkan/specs/latest/man/html/VkFormat.html
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * `VK_FORMAT_UNDEFINED`. In a KTX2 file this does not mean "no format" — it means the payload is
+ * Basis Universal and the Data Format Descriptor, not `vkFormat`, says which of the two it is.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const VK_FORMAT_UNDEFINED = 0;
+
+/**
+ * `[vkFormat, Vulkan name, GPUTextureFormat]`.
+ *
+ * Sorted by `vkFormat`, which is how the Vulkan header reads and how a reviewer checks a row against
+ * it. The one entry that is not a straight rename is BC1, which is commented where it sits.
+ *
+ * @type {[number, string, TextureFormat][]}
+ */
+const MAPPED = [
+    [9, "VK_FORMAT_R8_UNORM", TextureFormat.R8UNORM],
+    [10, "VK_FORMAT_R8_SNORM", TextureFormat.R8SNORM],
+    [13, "VK_FORMAT_R8_UINT", TextureFormat.R8UINT],
+    [14, "VK_FORMAT_R8_SINT", TextureFormat.R8SINT],
+
+    [16, "VK_FORMAT_R8G8_UNORM", TextureFormat.RG8UNORM],
+    [17, "VK_FORMAT_R8G8_SNORM", TextureFormat.RG8SNORM],
+    [20, "VK_FORMAT_R8G8_UINT", TextureFormat.RG8UINT],
+    [21, "VK_FORMAT_R8G8_SINT", TextureFormat.RG8SINT],
+
+    [37, "VK_FORMAT_R8G8B8A8_UNORM", TextureFormat.RGBA8UNORM],
+    [38, "VK_FORMAT_R8G8B8A8_SNORM", TextureFormat.RGBA8SNORM],
+    [41, "VK_FORMAT_R8G8B8A8_UINT", TextureFormat.RGBA8UINT],
+    [42, "VK_FORMAT_R8G8B8A8_SINT", TextureFormat.RGBA8SINT],
+    [43, "VK_FORMAT_R8G8B8A8_SRGB", TextureFormat.RGBA8UNORM_SRGB],
+
+    [44, "VK_FORMAT_B8G8R8A8_UNORM", TextureFormat.BGRA8UNORM],
+    [50, "VK_FORMAT_B8G8R8A8_SRGB", TextureFormat.BGRA8UNORM_SRGB],
+
+    [64, "VK_FORMAT_A2B10G10R10_UNORM_PACK32", TextureFormat.RGB10A2UNORM],
+    [68, "VK_FORMAT_A2B10G10R10_UINT_PACK32", TextureFormat.RGB10A2UINT],
+
+    [70, "VK_FORMAT_R16_UNORM", TextureFormat.R16UNORM],
+    [71, "VK_FORMAT_R16_SNORM", TextureFormat.R16SNORM],
+    [74, "VK_FORMAT_R16_UINT", TextureFormat.R16UINT],
+    [75, "VK_FORMAT_R16_SINT", TextureFormat.R16SINT],
+    [76, "VK_FORMAT_R16_SFLOAT", TextureFormat.R16FLOAT],
+
+    [77, "VK_FORMAT_R16G16_UNORM", TextureFormat.RG16UNORM],
+    [78, "VK_FORMAT_R16G16_SNORM", TextureFormat.RG16SNORM],
+    [81, "VK_FORMAT_R16G16_UINT", TextureFormat.RG16UINT],
+    [82, "VK_FORMAT_R16G16_SINT", TextureFormat.RG16SINT],
+    [83, "VK_FORMAT_R16G16_SFLOAT", TextureFormat.RG16FLOAT],
+
+    [91, "VK_FORMAT_R16G16B16A16_UNORM", TextureFormat.RGBA16UNORM],
+    [92, "VK_FORMAT_R16G16B16A16_SNORM", TextureFormat.RGBA16SNORM],
+    [95, "VK_FORMAT_R16G16B16A16_UINT", TextureFormat.RGBA16UINT],
+    [96, "VK_FORMAT_R16G16B16A16_SINT", TextureFormat.RGBA16SINT],
+    [97, "VK_FORMAT_R16G16B16A16_SFLOAT", TextureFormat.RGBA16FLOAT],
+
+    [98, "VK_FORMAT_R32_UINT", TextureFormat.R32UINT],
+    [99, "VK_FORMAT_R32_SINT", TextureFormat.R32SINT],
+    [100, "VK_FORMAT_R32_SFLOAT", TextureFormat.R32FLOAT],
+
+    [101, "VK_FORMAT_R32G32_UINT", TextureFormat.RG32UINT],
+    [102, "VK_FORMAT_R32G32_SINT", TextureFormat.RG32SINT],
+    [103, "VK_FORMAT_R32G32_SFLOAT", TextureFormat.RG32FLOAT],
+
+    [107, "VK_FORMAT_R32G32B32A32_UINT", TextureFormat.RGBA32UINT],
+    [108, "VK_FORMAT_R32G32B32A32_SINT", TextureFormat.RGBA32SINT],
+    [109, "VK_FORMAT_R32G32B32A32_SFLOAT", TextureFormat.RGBA32FLOAT],
+
+    [122, "VK_FORMAT_B10G11R11_UFLOAT_PACK32", TextureFormat.RG11B10UFLOAT],
+    [123, "VK_FORMAT_E5B9G9R9_UFLOAT_PACK32", TextureFormat.RGB9E5UFLOAT],
+
+    /*
+     BC — 131 and 132 are the RGB spelling, and WebGPU has no name for it.
+
+     `VK_FORMAT_BC1_RGB_*` and `VK_FORMAT_BC1_RGBA_*` are the same sixty-four bits per block; the only
+     difference is what a block in three-colour mode does with its fourth index — the RGB spelling
+     reads it as opaque black, the RGBA spelling as transparent. So a file naming the RGB spelling is
+     decoded here with punch-through alpha honoured.
+
+     Mapped rather than refused, because refusing would reject a large share of real BC1 content over
+     a difference no encoder targeting the RGB spelling exercises: having no alpha to store, it has no
+     reason to emit that index at all. A consumer that needs the guarantee ignores alpha at the sample
+     site, which is what an opaque texture's material does anyway.
+    */
+    [131, "VK_FORMAT_BC1_RGB_UNORM_BLOCK", TextureFormat.BC1_RGBA_UNORM],
+    [132, "VK_FORMAT_BC1_RGB_SRGB_BLOCK", TextureFormat.BC1_RGBA_UNORM_SRGB],
+    [133, "VK_FORMAT_BC1_RGBA_UNORM_BLOCK", TextureFormat.BC1_RGBA_UNORM],
+    [134, "VK_FORMAT_BC1_RGBA_SRGB_BLOCK", TextureFormat.BC1_RGBA_UNORM_SRGB],
+    [135, "VK_FORMAT_BC2_UNORM_BLOCK", TextureFormat.BC2_RGBA_UNORM],
+    [136, "VK_FORMAT_BC2_SRGB_BLOCK", TextureFormat.BC2_RGBA_UNORM_SRGB],
+    [137, "VK_FORMAT_BC3_UNORM_BLOCK", TextureFormat.BC3_RGBA_UNORM],
+    [138, "VK_FORMAT_BC3_SRGB_BLOCK", TextureFormat.BC3_RGBA_UNORM_SRGB],
+    [139, "VK_FORMAT_BC4_UNORM_BLOCK", TextureFormat.BC4_R_UNORM],
+    [140, "VK_FORMAT_BC4_SNORM_BLOCK", TextureFormat.BC4_R_SNORM],
+    [141, "VK_FORMAT_BC5_UNORM_BLOCK", TextureFormat.BC5_RG_UNORM],
+    [142, "VK_FORMAT_BC5_SNORM_BLOCK", TextureFormat.BC5_RG_SNORM],
+    [143, "VK_FORMAT_BC6H_UFLOAT_BLOCK", TextureFormat.BC6H_RGB_UFLOAT],
+    [144, "VK_FORMAT_BC6H_SFLOAT_BLOCK", TextureFormat.BC6H_RGB_FLOAT],
+    [145, "VK_FORMAT_BC7_UNORM_BLOCK", TextureFormat.BC7_RGBA_UNORM],
+    [146, "VK_FORMAT_BC7_SRGB_BLOCK", TextureFormat.BC7_RGBA_UNORM_SRGB],
+
+    // ETC2 and EAC
+    [147, "VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK", TextureFormat.ETC2_RGB8UNORM],
+    [148, "VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK", TextureFormat.ETC2_RGB8UNORM_SRGB],
+    [149, "VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK", TextureFormat.ETC2_RGB8A1UNORM],
+    [150, "VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK", TextureFormat.ETC2_RGB8A1UNORM_SRGB],
+    [151, "VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK", TextureFormat.ETC2_RGBA8UNORM],
+    [152, "VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK", TextureFormat.ETC2_RGBA8UNORM_SRGB],
+    [153, "VK_FORMAT_EAC_R11_UNORM_BLOCK", TextureFormat.EAC_R11UNORM],
+    [154, "VK_FORMAT_EAC_R11_SNORM_BLOCK", TextureFormat.EAC_R11SNORM],
+    [155, "VK_FORMAT_EAC_R11G11_UNORM_BLOCK", TextureFormat.EAC_RG11UNORM],
+    [156, "VK_FORMAT_EAC_R11G11_SNORM_BLOCK", TextureFormat.EAC_RG11SNORM],
+
+    // ASTC LDR — every block size WebGPU exposes, which is every block size Vulkan defines for LDR
+    [157, "VK_FORMAT_ASTC_4x4_UNORM_BLOCK", TextureFormat.ASTC_4X4_UNORM],
+    [158, "VK_FORMAT_ASTC_4x4_SRGB_BLOCK", TextureFormat.ASTC_4X4_UNORM_SRGB],
+    [159, "VK_FORMAT_ASTC_5x4_UNORM_BLOCK", TextureFormat.ASTC_5X4_UNORM],
+    [160, "VK_FORMAT_ASTC_5x4_SRGB_BLOCK", TextureFormat.ASTC_5X4_UNORM_SRGB],
+    [161, "VK_FORMAT_ASTC_5x5_UNORM_BLOCK", TextureFormat.ASTC_5X5_UNORM],
+    [162, "VK_FORMAT_ASTC_5x5_SRGB_BLOCK", TextureFormat.ASTC_5X5_UNORM_SRGB],
+    [163, "VK_FORMAT_ASTC_6x5_UNORM_BLOCK", TextureFormat.ASTC_6X5_UNORM],
+    [164, "VK_FORMAT_ASTC_6x5_SRGB_BLOCK", TextureFormat.ASTC_6X5_UNORM_SRGB],
+    [165, "VK_FORMAT_ASTC_6x6_UNORM_BLOCK", TextureFormat.ASTC_6X6_UNORM],
+    [166, "VK_FORMAT_ASTC_6x6_SRGB_BLOCK", TextureFormat.ASTC_6X6_UNORM_SRGB],
+    [167, "VK_FORMAT_ASTC_8x5_UNORM_BLOCK", TextureFormat.ASTC_8X5_UNORM],
+    [168, "VK_FORMAT_ASTC_8x5_SRGB_BLOCK", TextureFormat.ASTC_8X5_UNORM_SRGB],
+    [169, "VK_FORMAT_ASTC_8x6_UNORM_BLOCK", TextureFormat.ASTC_8X6_UNORM],
+    [170, "VK_FORMAT_ASTC_8x6_SRGB_BLOCK", TextureFormat.ASTC_8X6_UNORM_SRGB],
+    [171, "VK_FORMAT_ASTC_8x8_UNORM_BLOCK", TextureFormat.ASTC_8X8_UNORM],
+    [172, "VK_FORMAT_ASTC_8x8_SRGB_BLOCK", TextureFormat.ASTC_8X8_UNORM_SRGB],
+    [173, "VK_FORMAT_ASTC_10x5_UNORM_BLOCK", TextureFormat.ASTC_10X5_UNORM],
+    [174, "VK_FORMAT_ASTC_10x5_SRGB_BLOCK", TextureFormat.ASTC_10X5_UNORM_SRGB],
+    [175, "VK_FORMAT_ASTC_10x6_UNORM_BLOCK", TextureFormat.ASTC_10X6_UNORM],
+    [176, "VK_FORMAT_ASTC_10x6_SRGB_BLOCK", TextureFormat.ASTC_10X6_UNORM_SRGB],
+    [177, "VK_FORMAT_ASTC_10x8_UNORM_BLOCK", TextureFormat.ASTC_10X8_UNORM],
+    [178, "VK_FORMAT_ASTC_10x8_SRGB_BLOCK", TextureFormat.ASTC_10X8_UNORM_SRGB],
+    [179, "VK_FORMAT_ASTC_10x10_UNORM_BLOCK", TextureFormat.ASTC_10X10_UNORM],
+    [180, "VK_FORMAT_ASTC_10x10_SRGB_BLOCK", TextureFormat.ASTC_10X10_UNORM_SRGB],
+    [181, "VK_FORMAT_ASTC_12x10_UNORM_BLOCK", TextureFormat.ASTC_12X10_UNORM],
+    [182, "VK_FORMAT_ASTC_12x10_SRGB_BLOCK", TextureFormat.ASTC_12X10_UNORM_SRGB],
+    [183, "VK_FORMAT_ASTC_12x12_UNORM_BLOCK", TextureFormat.ASTC_12X12_UNORM],
+    [184, "VK_FORMAT_ASTC_12x12_SRGB_BLOCK", TextureFormat.ASTC_12X12_UNORM_SRGB],
+];
+
+/**
+ * `[vkFormat, Vulkan name, why it cannot be mapped]`.
+ *
+ * Not the whole of what is missing — Vulkan defines hundreds of formats and most will never appear
+ * in a texture file — but every entry here is one a real encoder emits, so a file that hits one is
+ * told what is wrong with it rather than handed a bare number. Anything outside both tables is
+ * refused by number, which is the honest answer for a format this reader has never heard of.
+ *
+ * @type {[number, string, string][]}
+ */
+const UNMAPPABLE = [
+    [15, "VK_FORMAT_R8_SRGB", "WebGPU has no single-channel sRGB format"],
+    [22, "VK_FORMAT_R8G8_SRGB", "WebGPU has no two-channel sRGB format"],
+
+    [23, "VK_FORMAT_R8G8B8_UNORM", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+    [29, "VK_FORMAT_R8G8B8_SRGB", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+    [30, "VK_FORMAT_B8G8R8_UNORM", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+    [36, "VK_FORMAT_B8G8R8_SRGB", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+    [90, "VK_FORMAT_R16G16B16_SFLOAT", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+    [106, "VK_FORMAT_R32G32B32_SFLOAT", "WebGPU has no three-channel formats; re-encode with an alpha channel"],
+
+    [45, "VK_FORMAT_B8G8R8A8_SNORM", "WebGPU exposes BGRA as unorm and unorm-srgb only"],
+    [48, "VK_FORMAT_B8G8R8A8_UINT", "WebGPU exposes BGRA as unorm and unorm-srgb only"],
+    [49, "VK_FORMAT_B8G8R8A8_SINT", "WebGPU exposes BGRA as unorm and unorm-srgb only"],
+
+    [58, "VK_FORMAT_A2R10G10B10_UNORM_PACK32", "WebGPU packs ten-bit channels as rgb10a2 only, which is Vulkan's A2B10G10R10 order"],
+    [62, "VK_FORMAT_A2R10G10B10_UINT_PACK32", "WebGPU packs ten-bit channels as rgb10a2 only, which is Vulkan's A2B10G10R10 order"],
+    [65, "VK_FORMAT_A2B10G10R10_SNORM_PACK32", "WebGPU exposes rgb10a2 as unorm and uint only"],
+    [69, "VK_FORMAT_A2B10G10R10_SINT_PACK32", "WebGPU exposes rgb10a2 as unorm and uint only"],
+
+    [124, "VK_FORMAT_D16_UNORM", "depth and stencil are render pass state rather than image content"],
+    [126, "VK_FORMAT_D32_SFLOAT", "depth and stencil are render pass state rather than image content"],
+    [125, "VK_FORMAT_X8_D24_UNORM_PACK32", "depth and stencil are render pass state rather than image content"],
+    [127, "VK_FORMAT_S8_UINT", "depth and stencil are render pass state rather than image content"],
+    [129, "VK_FORMAT_D24_UNORM_S8_UINT", "depth and stencil are render pass state rather than image content"],
+    [130, "VK_FORMAT_D32_SFLOAT_S8_UINT", "depth and stencil are render pass state rather than image content"],
+
+    /*
+     Named rather than mapped, deliberately. These two are byte-identical to VK_FORMAT_R8G8B8A8_UNORM
+     and _SRGB — but only on a little-endian host, because a PACK32 format names its components from
+     the most significant bit of a 32-bit word rather than in memory order. Mapping them would bake
+     an endianness assumption into the one table whose entire claim is that a mapping is a pair of
+     names for one byte layout.
+    */
+    [51, "VK_FORMAT_A8B8G8R8_UNORM_PACK32", "a packed spelling whose byte order depends on the host; re-declare it as VK_FORMAT_R8G8B8A8_UNORM, which states the layout the payload actually has"],
+    [57, "VK_FORMAT_A8B8G8R8_SRGB_PACK32", "a packed spelling whose byte order depends on the host; re-declare it as VK_FORMAT_R8G8B8A8_SRGB, which states the layout the payload actually has"],
+];
+
+/**
+ * @type {Map<number, TextureFormat>}
+ */
+const FORMAT_BY_VK = new Map(MAPPED.map(([vk, , format]) => [vk, format]));
+
+/**
+ * @type {Map<number, string>}
+ */
+const NAME_BY_VK = new Map([
+    [VK_FORMAT_UNDEFINED, "VK_FORMAT_UNDEFINED"],
+    ...MAPPED.map(([vk, name]) => [vk, name]),
+    ...UNMAPPABLE.map(([vk, name]) => [vk, name]),
+]);
+
+/**
+ * @type {Map<number, string>}
+ */
+const REASON_BY_VK = new Map(UNMAPPABLE.map(([vk, , reason]) => [vk, reason]));
+
+/**
+ * Every `vkFormat` this module maps, for a test that wants to sweep them.
+ *
+ * @returns {number[]}
+ */
+export function vk_formats_mapped() {
+    return MAPPED.map(([vk]) => vk);
+}
+
+/**
+ * Every `vkFormat` this module names but deliberately does not map, for the test that keeps the two
+ * tables from overlapping.
+ *
+ * @returns {number[]}
+ */
+export function vk_formats_unmappable() {
+    return UNMAPPABLE.map(([vk]) => vk);
+}
+
+/**
+ * The Vulkan name of `vk_format`, where this module knows it.
+ *
+ * @param {number} vk_format
+ * @returns {string} the `VK_FORMAT_…` name, or `vkFormat <n>` for one outside both tables
+ */
+export function vk_format_name(vk_format) {
+    return NAME_BY_VK.get(vk_format) ?? `vkFormat ${vk_format}`;
+}
+
+/**
+ * The {@link TextureFormat} holding the same bytes as `vk_format`.
+ *
+ * Byte for byte, not approximately: every mapping here is a pair of names for one memory layout, so
+ * a payload passes through unchanged and the only thing the mapping decides is what the sampler is
+ * told about it. The single caveat is BC1, noted beside its rows in the table.
+ *
+ * @param {number} vk_format as read from a KTX2 header
+ * @returns {TextureFormat}
+ * @throws {Error} naming the format, for one WebGPU does not expose
+ */
+export function vk_format_to_texture_format(vk_format) {
+    const format = FORMAT_BY_VK.get(vk_format);
+
+    if (format !== undefined) {
+        return format;
+    }
+
+    const reason = REASON_BY_VK.get(vk_format);
+
+    if (reason !== undefined) {
+        throw new Error(
+            `${vk_format_name(vk_format)} (vkFormat ${vk_format}) has no GPUTextureFormat: ${reason}`
+        );
+    }
+
+    throw new Error(
+        `vkFormat ${vk_format} is not a format this reader maps to a GPUTextureFormat.`
+        + ` Only formats WebGPU exposes can be sampled, and this one is either outside that set or`
+        + ` outside the set of Vulkan formats a texture file has been seen to carry.`
+    );
+}

package/src/shade/descriptor/GPUTextureUsage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Useful for when WebGPU constants are not available.
+ *
+ * Unlike {@link GPUTextureFormat }, which is a WebIDL enum and therefore just a string, `GPUTextureUsage`
+ * is a real global namespace object. Reading it where WebGPU is absent throws a `ReferenceError` —
+ * and a class field such as {@link TextureDescriptor }'s `usage` reads it at *module load*, so the
+ * `import` itself throws before any code runs.
+ *
+ * Under vitest a stub in `vitest.setup.mjs` covers that. Nothing covers it anywhere else: a CLI, an
+ * asset-pipeline script, or an offline texture encoder is not a test, and importing a descriptor
+ * from one has to work.
+ *
+ * Companion to {@link GPUShaderStage }, for the same reason.
+ */
+export type GPUTextureUsage = number;
+export namespace GPUTextureUsage {
+    let COPY_SRC: number;
+    let COPY_DST: number;
+    let TEXTURE_BINDING: number;
+    let STORAGE_BINDING: number;
+    let RENDER_ATTACHMENT: number;
+}
+//# sourceMappingURL=GPUTextureUsage.d.ts.map

package/src/shade/descriptor/GPUTextureUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUTextureUsage.d.ts","sourceRoot":"","sources":["../../../../src/shade/descriptor/GPUTextureUsage.js"],"names":[],"mappings":";;;;;;;;;;;;;;8BAeU,MAAM"}

package/src/shade/descriptor/GPUTextureUsage.js

@@ -0,0 +1,24 @@
+/**
+ * Useful for when WebGPU constants are not available.
+ *
+ * Unlike {@link GPUTextureFormat}, which is a WebIDL enum and therefore just a string, `GPUTextureUsage`
+ * is a real global namespace object. Reading it where WebGPU is absent throws a `ReferenceError` —
+ * and a class field such as {@link TextureDescriptor}'s `usage` reads it at *module load*, so the
+ * `import` itself throws before any code runs.
+ *
+ * Under vitest a stub in `vitest.setup.mjs` covers that. Nothing covers it anywhere else: a CLI, an
+ * asset-pipeline script, or an offline texture encoder is not a test, and importing a descriptor
+ * from one has to work.
+ *
+ * Companion to {@link GPUShaderStage}, for the same reason.
+ *
+ * @see https://www.w3.org/TR/webgpu/#namespacedef-gputextureusage
+ * @enum {number}
+ */
+export const GPUTextureUsage = {
+    COPY_SRC: 0x01,
+    COPY_DST: 0x02,
+    TEXTURE_BINDING: 0x04,
+    STORAGE_BINDING: 0x08,
+    RENDER_ATTACHMENT: 0x10,
+}

package/src/shade/descriptor/WebGPUExtensionType.d.ts

@@ -7,5 +7,8 @@ export namespace WebGPUExtensionType {
     let Float32Filterable: string;
     let ShaderF16: string;
     let TextureFormatsTier1: string;
+    let TextureCompressionBC: string;
+    let TextureCompressionETC2: string;
+    let TextureCompressionASTC: string;
 }
 //# sourceMappingURL=WebGPUExtensionType.d.ts.map

package/src/shade/descriptor/WebGPUExtensionType.js

@@ -59,4 +59,30 @@ export const WebGPUExtensionType = {
      * @see https://www.w3.org/TR/webgpu/#texture-formats-tier1
      */
     TextureFormatsTier1: "texture-formats-tier1",
+
+    /**
+     * Adds the BC (S3TC / DXT / RGTC / BPTC) compressed texture formats — `bc1` through `bc7`.
+     *
+     * Desktop's compression family. Sampling one costs nothing: the hardware decodes it, which is
+     * the whole reason to ship textures this way rather than transcoding on load.
+     *
+     * @see https://www.w3.org/TR/webgpu/#texture-compression-bc
+     */
+    TextureCompressionBC: "texture-compression-bc",
+
+    /**
+     * Adds the ETC2 and EAC compressed texture formats.
+     *
+     * @see https://www.w3.org/TR/webgpu/#texture-compression-etc2
+     */
+    TextureCompressionETC2: "texture-compression-etc2",
+
+    /**
+     * Adds the ASTC compressed texture formats, every block size.
+     *
+     * Mobile and Apple's family, and the one with a block-size choice to make.
+     *
+     * @see https://www.w3.org/TR/webgpu/#texture-compression-astc
+     */
+    TextureCompressionASTC: "texture-compression-astc",
 }

package/src/shade/descriptor/texture/TextureDescriptor.d.ts

@@ -52,15 +52,11 @@ export class TextureDescriptor extends ObjectDescriptorBase implements GPUTextur
         height: number;
         depthOrArrayLayers: number;
     };
-    /**
-     *
-     * @return {number}
-     */
-    get bits_per_sample(): number;
     /**
      * The number is just an estimate, actual VRAM usage will depend on the GPU.
      * Usually accurate, but when it's not - it's close.
-     * @returns {number}
+     *
+     * @returns {number} bytes
      */
     get memory_footprint(): number;
     /**

package/src/shade/descriptor/texture/TextureDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextureDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/texture/TextureDescriptor.js"],"names":[],"mappings":"AA+BA;;;GAGG;AACH,uEAFe,oBAAoB;IA8K/B;;;;OAIG;IACH,yCAFY,iBAAiB,CAQ5B;IA/KD,sBAAkB;IAClB,oBAAgB;IAEhB;;;OAGG;IACH,WAFU,sBAAoB,MAAM,CAEnB;IAEjB;;OAEG;IACH,yBAAsB;IAEtB;;OAEG;IACH,OAFU,MAAM,uBAAqB,CAEG;IAExC;;;OAGG;IACH,aAFU,kBAAkB,CAEX;IAEjB;;;OAGG;IACH,eAAyB;IAEzB;;;OAGG;IACH;eAU4B,MAAM;gBAAS,MAAM;4BAAqB,MAAM;OAJ3E;IAED;;;OAGG;IACH;eAF4B,MAAM;gBAAS,MAAM;4BAAqB,MAAM;MAI3E;IAGD;;;OAGG;IACH,8BAkBC;IAGD;;;;OAIG;IACH,+BAgBC;IAED;;;;OAIG;IACH,cAHW,iBAAiB,GAChB,OAAO,CAelB;IAED;;;OAGG;IACH,YAFW,iBAAiB,QAa3B;IAcD;;;OAGG;IACH,uCASC;IAeD;;;OAGG;IACH,2CAwCC;IAIL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAP9C;qCAjQoC,4BAA4B"}
+{"version":3,"file":"TextureDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/texture/TextureDescriptor.js"],"names":[],"mappings":"AAgCA;;;GAGG;AACH,uEAFe,oBAAoB;IA6J/B;;;;OAIG;IACH,yCAFY,iBAAiB,CAQ5B;IA9JD,sBAAkB;IAClB,oBAAgB;IAEhB;;;OAGG;IACH,WAFU,sBAAoB,MAAM,CAEnB;IAEjB;;OAEG;IACH,yBAAsB;IAEtB;;OAEG;IACH,OAFU,MAAM,uBAAqB,CAEG;IAExC;;;OAGG;IACH,aAFU,kBAAkB,CAEX;IAEjB;;;OAGG;IACH,eAAyB;IAEzB;;;OAGG;IACH;eAU4B,MAAM;gBAAS,MAAM;4BAAqB,MAAM;OAJ3E;IAED;;;OAGG;IACH;eAF4B,MAAM;gBAAS,MAAM;4BAAqB,MAAM;MAI3E;IAGD;;;;;OAKG;IACH,+BAuBC;IAED;;;;OAIG;IACH,cAHW,iBAAiB,GAChB,OAAO,CAelB;IAED;;;OAGG;IACH,YAFW,iBAAiB,QAa3B;IAcD;;;OAGG;IACH,uCASC;IAeD;;;OAGG;IACH,2CAwCC;IAIL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAP9C;qCAjPoC,4BAA4B"}