@woosh/meep-engine 3.14.1 → 3.14.3

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"}

package/src/shade/descriptor/texture/TextureDescriptor.js

@@ -5,8 +5,9 @@ import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualS
 import Signal from "../../../core/events/signal/Signal.js";
 import { computeStringHash } from "../../../core/primitives/strings/computeStringHash.js";
 import { warn_limited } from "../../util/warn_limited.js";
-import { gpu_texture_format_channel_bit_count } from "./format/gpu_texture_format_channel_bit_count.js";
+import { gpu_texture_format_memory_footprint } from "./format/gpu_texture_format_info.js";
 import { ObjectDescriptorBase } from "../ObjectDescriptorBase.js";
+import { GPUTextureUsage } from "../GPUTextureUsage.js";
 
 
 /**
@@ -93,52 +94,35 @@ export class TextureDescriptor extends ObjectDescriptorBase {
     }
 
 
-    /**
-     *
-     * @return {number}
-     */
-    get bits_per_sample() {
-        const f = this.format;
-
-        const bit_counts = gpu_texture_format_channel_bit_count[f];
-
-        if (bit_counts === undefined) {
-            // unknown
-            warn_limited(`Unsupported texture format: ${f}`);
-            return 0;
-        }
-
-        let total = 0;
-
-        for (let i = 0; i < bit_counts.length; i++) {
-            total += bit_counts[i];
-        }
-
-        return total;
-    }
-
-
     /**
      * 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() {
-        const size = this.#size;
+        try {
+            return gpu_texture_format_memory_footprint(
+                this.format,
+                this.#size,
+                this.dimension,
+                this.mipLevelCount,
+                this.sampleCount
+            );
+        } catch (e) {
+            /*
+             Usually an unknown format, which for a descriptor means one `createTexture` would refuse
+             anyway. Reporting zero keeps a budget readout and a pool eviction from taking a frame
+             down over an accounting number, and the warning is what says so out loud.
+
+             The message carries the cause rather than naming the format as the culprit: this also
+             catches the argument asserts, and a descriptor with a garbage `mipLevelCount` should not
+             be reported as having a bad format.
+            */
+            warn_limited(`Cannot size texture '${this.label}' (${this.format}): ${e.message}`);
 
-        let pixel_count = 0;
-
-        // add up mip pixels
-        for (let i = 0; i < this.mipLevelCount; i++) {
-            let mip_w = Math.max(size[0] >> i, 1);
-            let mip_h = Math.max(size[1] >> i, 1);
-            let mip_d = Math.max(size[2] >> i, 1);
-
-            pixel_count += mip_w * mip_h * mip_d;
+            return 0;
         }
-
-        // consumers (gpu_memory_usage) expect bytes
-        return (pixel_count * this.bits_per_sample * this.sampleCount) / 8;
     }
 
     /**

package/src/shade/descriptor/texture/format/TextureFormat.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Every {@link GPUTextureFormat }, as a named constant.
+ *
+ * `GPUTextureFormat` is a WebIDL enum, which in JavaScript means a bare string — there is no global
+ * to read and nothing here is a shim for a missing one. What this adds is threefold:
+ *
+ *  1. **A resolvable type.** `@webgpu/types` is not a dependency of this package, so every
+ *     `@param {GPUTextureFormat}` in the tree resolves to nothing and `generate-types` emits `any`.
+ *     An in-tree `@enum {string}` types those parameters without putting browser typings on a node
+ *     tool's path.
+ *  2. **A typo is `undefined` at the call site**, rather than `'rgba8'` travelling one layer down to
+ *     {@link gpu_texture_format_info } and throwing there.
+ *  3. **One enumeration.** The names were already the key set of that table; naming them makes the
+ *     set the source rather than an implementation detail of a lookup.
+ *
+ * **The values are the WebGPU strings verbatim**, so a member is passable straight to
+ * `createTexture` and no translation exists at any boundary — the same discipline
+ * {@link WebGPUExtensionType } keeps. Keys are the value uppercased with `-` as `_`, mechanically and
+ * without exception, which is what `TextureFormat.spec.js` asserts in both directions.
+ */
+export type TextureFormat = string;
+export namespace TextureFormat {
+    let R8UNORM: string;
+    let R8SNORM: string;
+    let R8UINT: string;
+    let R8SINT: string;
+    let R16UNORM: string;
+    let R16SNORM: string;
+    let R16UINT: string;
+    let R16SINT: string;
+    let R16FLOAT: string;
+    let RG8UNORM: string;
+    let RG8SNORM: string;
+    let RG8UINT: string;
+    let RG8SINT: string;
+    let R32UINT: string;
+    let R32SINT: string;
+    let R32FLOAT: string;
+    let RG16UNORM: string;
+    let RG16SNORM: string;
+    let RG16UINT: string;
+    let RG16SINT: string;
+    let RG16FLOAT: string;
+    let RGBA8UNORM: string;
+    let RGBA8UNORM_SRGB: string;
+    let RGBA8SNORM: string;
+    let RGBA8UINT: string;
+    let RGBA8SINT: string;
+    let BGRA8UNORM: string;
+    let BGRA8UNORM_SRGB: string;
+    let RGB9E5UFLOAT: string;
+    let RGB10A2UINT: string;
+    let RGB10A2UNORM: string;
+    let RG11B10UFLOAT: string;
+    let RG32UINT: string;
+    let RG32SINT: string;
+    let RG32FLOAT: string;
+    let RGBA16UNORM: string;
+    let RGBA16SNORM: string;
+    let RGBA16UINT: string;
+    let RGBA16SINT: string;
+    let RGBA16FLOAT: string;
+    let RGBA32UINT: string;
+    let RGBA32SINT: string;
+    let RGBA32FLOAT: string;
+    let STENCIL8: string;
+    let DEPTH16UNORM: string;
+    let DEPTH24PLUS: string;
+    let DEPTH24PLUS_STENCIL8: string;
+    let DEPTH32FLOAT: string;
+    let DEPTH32FLOAT_STENCIL8: string;
+    let BC1_RGBA_UNORM: string;
+    let BC1_RGBA_UNORM_SRGB: string;
+    let BC2_RGBA_UNORM: string;
+    let BC2_RGBA_UNORM_SRGB: string;
+    let BC3_RGBA_UNORM: string;
+    let BC3_RGBA_UNORM_SRGB: string;
+    let BC4_R_UNORM: string;
+    let BC4_R_SNORM: string;
+    let BC5_RG_UNORM: string;
+    let BC5_RG_SNORM: string;
+    let BC6H_RGB_UFLOAT: string;
+    let BC6H_RGB_FLOAT: string;
+    let BC7_RGBA_UNORM: string;
+    let BC7_RGBA_UNORM_SRGB: string;
+    let ETC2_RGB8UNORM: string;
+    let ETC2_RGB8UNORM_SRGB: string;
+    let ETC2_RGB8A1UNORM: string;
+    let ETC2_RGB8A1UNORM_SRGB: string;
+    let ETC2_RGBA8UNORM: string;
+    let ETC2_RGBA8UNORM_SRGB: string;
+    let EAC_R11UNORM: string;
+    let EAC_R11SNORM: string;
+    let EAC_RG11UNORM: string;
+    let EAC_RG11SNORM: string;
+    let ASTC_4X4_UNORM: string;
+    let ASTC_4X4_UNORM_SRGB: string;
+    let ASTC_5X4_UNORM: string;
+    let ASTC_5X4_UNORM_SRGB: string;
+    let ASTC_5X5_UNORM: string;
+    let ASTC_5X5_UNORM_SRGB: string;
+    let ASTC_6X5_UNORM: string;
+    let ASTC_6X5_UNORM_SRGB: string;
+    let ASTC_6X6_UNORM: string;
+    let ASTC_6X6_UNORM_SRGB: string;
+    let ASTC_8X5_UNORM: string;
+    let ASTC_8X5_UNORM_SRGB: string;
+    let ASTC_8X6_UNORM: string;
+    let ASTC_8X6_UNORM_SRGB: string;
+    let ASTC_8X8_UNORM: string;
+    let ASTC_8X8_UNORM_SRGB: string;
+    let ASTC_10X5_UNORM: string;
+    let ASTC_10X5_UNORM_SRGB: string;
+    let ASTC_10X6_UNORM: string;
+    let ASTC_10X6_UNORM_SRGB: string;
+    let ASTC_10X8_UNORM: string;
+    let ASTC_10X8_UNORM_SRGB: string;
+    let ASTC_10X10_UNORM: string;
+    let ASTC_10X10_UNORM_SRGB: string;
+    let ASTC_12X10_UNORM: string;
+    let ASTC_12X10_UNORM_SRGB: string;
+    let ASTC_12X12_UNORM: string;
+    let ASTC_12X12_UNORM_SRGB: string;
+}
+//# sourceMappingURL=TextureFormat.d.ts.map

package/src/shade/descriptor/texture/format/TextureFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextureFormat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/TextureFormat.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;4BAqBU,MAAM"}

package/src/shade/descriptor/texture/format/TextureFormat.js

@@ -0,0 +1,146 @@
+/**
+ * Every {@link GPUTextureFormat}, as a named constant.
+ *
+ * `GPUTextureFormat` is a WebIDL enum, which in JavaScript means a bare string — there is no global
+ * to read and nothing here is a shim for a missing one. What this adds is threefold:
+ *
+ *  1. **A resolvable type.** `@webgpu/types` is not a dependency of this package, so every
+ *     `@param {GPUTextureFormat}` in the tree resolves to nothing and `generate-types` emits `any`.
+ *     An in-tree `@enum {string}` types those parameters without putting browser typings on a node
+ *     tool's path.
+ *  2. **A typo is `undefined` at the call site**, rather than `'rgba8'` travelling one layer down to
+ *     {@link gpu_texture_format_info} and throwing there.
+ *  3. **One enumeration.** The names were already the key set of that table; naming them makes the
+ *     set the source rather than an implementation detail of a lookup.
+ *
+ * **The values are the WebGPU strings verbatim**, so a member is passable straight to
+ * `createTexture` and no translation exists at any boundary — the same discipline
+ * {@link WebGPUExtensionType} keeps. Keys are the value uppercased with `-` as `_`, mechanically and
+ * without exception, which is what `TextureFormat.spec.js` asserts in both directions.
+ *
+ * @see https://www.w3.org/TR/webgpu/#enumdef-gputextureformat
+ * @enum {string}
+ */
+export const TextureFormat = {
+    // 8-bit
+    R8UNORM: "r8unorm",
+    R8SNORM: "r8snorm",
+    R8UINT: "r8uint",
+    R8SINT: "r8sint",
+
+    // 16-bit
+    R16UNORM: "r16unorm",
+    R16SNORM: "r16snorm",
+    R16UINT: "r16uint",
+    R16SINT: "r16sint",
+    R16FLOAT: "r16float",
+    RG8UNORM: "rg8unorm",
+    RG8SNORM: "rg8snorm",
+    RG8UINT: "rg8uint",
+    RG8SINT: "rg8sint",
+
+    // 32-bit
+    R32UINT: "r32uint",
+    R32SINT: "r32sint",
+    R32FLOAT: "r32float",
+    RG16UNORM: "rg16unorm",
+    RG16SNORM: "rg16snorm",
+    RG16UINT: "rg16uint",
+    RG16SINT: "rg16sint",
+    RG16FLOAT: "rg16float",
+    RGBA8UNORM: "rgba8unorm",
+    RGBA8UNORM_SRGB: "rgba8unorm-srgb",
+    RGBA8SNORM: "rgba8snorm",
+    RGBA8UINT: "rgba8uint",
+    RGBA8SINT: "rgba8sint",
+    BGRA8UNORM: "bgra8unorm",
+    BGRA8UNORM_SRGB: "bgra8unorm-srgb",
+    // packed — the name says nothing useful about the size
+    RGB9E5UFLOAT: "rgb9e5ufloat",
+    RGB10A2UINT: "rgb10a2uint",
+    RGB10A2UNORM: "rgb10a2unorm",
+    RG11B10UFLOAT: "rg11b10ufloat",
+
+    // 64-bit
+    RG32UINT: "rg32uint",
+    RG32SINT: "rg32sint",
+    RG32FLOAT: "rg32float",
+    RGBA16UNORM: "rgba16unorm",
+    RGBA16SNORM: "rgba16snorm",
+    RGBA16UINT: "rgba16uint",
+    RGBA16SINT: "rgba16sint",
+    RGBA16FLOAT: "rgba16float",
+
+    // 128-bit
+    RGBA32UINT: "rgba32uint",
+    RGBA32SINT: "rgba32sint",
+    RGBA32FLOAT: "rgba32float",
+
+    // depth and stencil
+    STENCIL8: "stencil8",
+    DEPTH16UNORM: "depth16unorm",
+    // no defined byte layout for the depth aspect, so WebGPU forbids copying it; 4 is what this mock
+    // allocates, which is enough for a render target and is never handed to a copy
+    DEPTH24PLUS: "depth24plus",
+    DEPTH24PLUS_STENCIL8: "depth24plus-stencil8",
+    DEPTH32FLOAT: "depth32float",
+    DEPTH32FLOAT_STENCIL8: "depth32float-stencil8",
+
+    // BC, 4×4 blocks
+    BC1_RGBA_UNORM: "bc1-rgba-unorm",
+    BC1_RGBA_UNORM_SRGB: "bc1-rgba-unorm-srgb",
+    BC2_RGBA_UNORM: "bc2-rgba-unorm",
+    BC2_RGBA_UNORM_SRGB: "bc2-rgba-unorm-srgb",
+    BC3_RGBA_UNORM: "bc3-rgba-unorm",
+    BC3_RGBA_UNORM_SRGB: "bc3-rgba-unorm-srgb",
+    BC4_R_UNORM: "bc4-r-unorm",
+    BC4_R_SNORM: "bc4-r-snorm",
+    BC5_RG_UNORM: "bc5-rg-unorm",
+    BC5_RG_SNORM: "bc5-rg-snorm",
+    BC6H_RGB_UFLOAT: "bc6h-rgb-ufloat",
+    BC6H_RGB_FLOAT: "bc6h-rgb-float",
+    BC7_RGBA_UNORM: "bc7-rgba-unorm",
+    BC7_RGBA_UNORM_SRGB: "bc7-rgba-unorm-srgb",
+
+    // ETC2 / EAC, 4×4 blocks
+    ETC2_RGB8UNORM: "etc2-rgb8unorm",
+    ETC2_RGB8UNORM_SRGB: "etc2-rgb8unorm-srgb",
+    ETC2_RGB8A1UNORM: "etc2-rgb8a1unorm",
+    ETC2_RGB8A1UNORM_SRGB: "etc2-rgb8a1unorm-srgb",
+    ETC2_RGBA8UNORM: "etc2-rgba8unorm",
+    ETC2_RGBA8UNORM_SRGB: "etc2-rgba8unorm-srgb",
+    EAC_R11UNORM: "eac-r11unorm",
+    EAC_R11SNORM: "eac-r11snorm",
+    EAC_RG11UNORM: "eac-rg11unorm",
+    EAC_RG11SNORM: "eac-rg11snorm",
+
+    // ASTC — every block size, all 16 bytes
+    ASTC_4X4_UNORM: "astc-4x4-unorm",
+    ASTC_4X4_UNORM_SRGB: "astc-4x4-unorm-srgb",
+    ASTC_5X4_UNORM: "astc-5x4-unorm",
+    ASTC_5X4_UNORM_SRGB: "astc-5x4-unorm-srgb",
+    ASTC_5X5_UNORM: "astc-5x5-unorm",
+    ASTC_5X5_UNORM_SRGB: "astc-5x5-unorm-srgb",
+    ASTC_6X5_UNORM: "astc-6x5-unorm",
+    ASTC_6X5_UNORM_SRGB: "astc-6x5-unorm-srgb",
+    ASTC_6X6_UNORM: "astc-6x6-unorm",
+    ASTC_6X6_UNORM_SRGB: "astc-6x6-unorm-srgb",
+    ASTC_8X5_UNORM: "astc-8x5-unorm",
+    ASTC_8X5_UNORM_SRGB: "astc-8x5-unorm-srgb",
+    ASTC_8X6_UNORM: "astc-8x6-unorm",
+    ASTC_8X6_UNORM_SRGB: "astc-8x6-unorm-srgb",
+    ASTC_8X8_UNORM: "astc-8x8-unorm",
+    ASTC_8X8_UNORM_SRGB: "astc-8x8-unorm-srgb",
+    ASTC_10X5_UNORM: "astc-10x5-unorm",
+    ASTC_10X5_UNORM_SRGB: "astc-10x5-unorm-srgb",
+    ASTC_10X6_UNORM: "astc-10x6-unorm",
+    ASTC_10X6_UNORM_SRGB: "astc-10x6-unorm-srgb",
+    ASTC_10X8_UNORM: "astc-10x8-unorm",
+    ASTC_10X8_UNORM_SRGB: "astc-10x8-unorm-srgb",
+    ASTC_10X10_UNORM: "astc-10x10-unorm",
+    ASTC_10X10_UNORM_SRGB: "astc-10x10-unorm-srgb",
+    ASTC_12X10_UNORM: "astc-12x10-unorm",
+    ASTC_12X10_UNORM_SRGB: "astc-12x10-unorm-srgb",
+    ASTC_12X12_UNORM: "astc-12x12-unorm",
+    ASTC_12X12_UNORM_SRGB: "astc-12x12-unorm-srgb",
+};

package/src/shade/descriptor/texture/format/gpu_texture_format_feature.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The feature a device must have been created with before `format` may be used, or `undefined`
+ * for a format every device has.
+ *
+ * Every compressed format in WebGPU is optional, and all-or-nothing within its family: asking for
+ * `bc7-rgba-unorm` on a device without `texture-compression-bc` is a validation error at
+ * `createTexture`, not a fallback. This is the one table that says which feature that is — read by
+ * {@link gpu_texture_compression_support} to turn a device's features into the formats it may ask
+ * for, and by the software device to refuse a texture the way a real one would.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {GPUFeatureName|undefined}
+ * @throws {Error} for a name that is not a GPUTextureFormat
+ */
+export function gpu_texture_format_feature(format: GPUTextureFormat): GPUFeatureName | undefined;
+//# sourceMappingURL=gpu_texture_format_feature.d.ts.map

package/src/shade/descriptor/texture/format/gpu_texture_format_feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_format_feature.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_format_feature.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AACH,sEAHa,iBAAe,SAAS,CAcpC"}

package/src/shade/descriptor/texture/format/gpu_texture_format_feature.js

@@ -0,0 +1,44 @@
+import { WebGPUExtensionType } from "../../WebGPUExtensionType.js";
+import { gpu_texture_format_info } from "./gpu_texture_format_info.js";
+
+/**
+ * Which optional feature each compressed family arrives under.
+ *
+ * Derived from the format's name rather than listed per format, because the three families
+ * partition the table cleanly by prefix and a hand-written list is one more thing to forget a format
+ * from. ETC2 and EAC arrive together, under one feature.
+ *
+ * @type {[GPUFeatureName, RegExp][]}
+ */
+const FAMILIES = [
+    [WebGPUExtensionType.TextureCompressionBC, /^bc[0-9]/],
+    [WebGPUExtensionType.TextureCompressionETC2, /^(etc2|eac)-/],
+    [WebGPUExtensionType.TextureCompressionASTC, /^astc-/],
+];
+
+/**
+ * The feature a device must have been created with before `format` may be used, or `undefined`
+ * for a format every device has.
+ *
+ * Every compressed format in WebGPU is optional, and all-or-nothing within its family: asking for
+ * `bc7-rgba-unorm` on a device without `texture-compression-bc` is a validation error at
+ * `createTexture`, not a fallback. This is the one table that says which feature that is — read by
+ * {@link gpu_texture_compression_support} to turn a device's features into the formats it may ask
+ * for, and by the software device to refuse a texture the way a real one would.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {GPUFeatureName|undefined}
+ * @throws {Error} for a name that is not a GPUTextureFormat
+ */
+export function gpu_texture_format_feature(format) {
+    // throws for a name that is not a format, which is worth knowing before the answer is "none"
+    gpu_texture_format_info(format);
+
+    for (const [feature, pattern] of FAMILIES) {
+        if (pattern.test(format)) {
+            return feature;
+        }
+    }
+
+    return undefined;
+}

package/src/shade/descriptor/texture/format/gpu_texture_format_info.d.ts

@@ -18,6 +18,21 @@ export function gpu_texture_format_info(format: GPUTextureFormat): GPUTextureFor
  * @returns {GPUTextureFormat[]}
  */
 export function gpu_texture_format_names(): GPUTextureFormat[];
+/**
+ * Whether `format` stores more than one texel per block.
+ *
+ * The one question the plain `block_width !== 1 || block_height !== 1` answers, and it was written
+ * out inline in three places — {@link SoftwareGPUTexture.bytes_per_texel},
+ * {@link gpu_texture_format_can_generate_mipmaps} and {@link download_texture_data} — each of which
+ * needs it to refuse something. A container reader asking "may this file even be a 3D texture" makes
+ * four, which is the count at which the same arithmetic in four places has already gone wrong once in
+ * this tree.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {boolean}
+ * @throws {Error} for a name that is not a GPUTextureFormat
+ */
+export function gpu_texture_format_is_block_compressed(format: GPUTextureFormat): boolean;
 /**
  * Bytes one row of `width` texels occupies, tightly packed.
  *
@@ -37,6 +52,67 @@ export function gpu_texture_format_row_bytes(format: GPUTextureFormat, width: nu
  * @returns {number}
  */
 export function gpu_texture_format_row_count(format: GPUTextureFormat, height: number): number;
+/**
+ * The extent WebGPU addresses a level of `format` by: its size rounded up to whole blocks.
+ *
+ * **A copy is sized in blocks, not texels.** The 2x2 and 1x1 tail of a BC chain are each one 4x4
+ * block, and `writeTexture`, `copyBufferToTexture` and `copyTextureToBuffer` all require the copy
+ * extent to be a multiple of the block size and bound it by *this* size rather than the logical
+ * one — Dawn refuses `copySize.width (2) is not a multiple of compressed texture format block width
+ * (4)` for a 2x2 level written as 2x2, and takes 4x4. The logical size still says how many texels
+ * the level has; this says how many the copy commands count. For a 1x1-block format the two agree.
+ *
+ * @param {GPUTextureFormat} format
+ * @param {number} width texels, at this level
+ * @param {number} height texels, at this level
+ * @returns {number[]} `[width, height]` rounded up to the block
+ */
+export function gpu_texture_format_physical_size(format: GPUTextureFormat, width: number, height: number): number[];
+/**
+ * Bytes one mip level occupies, tightly packed, all its layers included.
+ *
+ * The composition of {@link gpu_texture_format_row_bytes} and
+ * {@link gpu_texture_format_row_count} — which is trivial, and was written out in four places before
+ * it was written down in one.
+ *
+ * @param {GPUTextureFormat} format
+ * @param {number} width texels, at this level
+ * @param {number} height texels, at this level
+ * @param {number} depth_or_layers at this level
+ * @returns {number} bytes
+ */
+export function gpu_texture_format_level_bytes(format: GPUTextureFormat, width: number, height: number, depth_or_layers: number): number;
+/**
+ * Bytes a whole texture occupies, mip chain included.
+ *
+ * Block-aware, which is the point: `channels × bytes_per_channel × width × height` is right only for
+ * the 1×1-block formats and reports nonsense — or, where the caller consults a per-channel table
+ * that has no entry, zero — for every BC, ETC2 and ASTC format.
+ *
+ * **Only a 3D texture's depth halves per level.** The third component of an array texture's size is
+ * its layer count, and every layer has every mip; halving it under-reports a six-layer cube map by
+ * close to half. Hence `dimension`, which both descriptors that call this already carry.
+ *
+ * Every argument is required. There is no sensible default for a mip count or a sample count — a
+ * caller that does not know them is not in a position to ask this question, and a defaulted `1`
+ * would answer a different one convincingly.
+ *
+ * An estimate, in that a driver may pad, align or compress behind the API. Usually exact, and close
+ * when it is not.
+ *
+ * @param {GPUTextureFormat} format
+ * @param {ArrayLike<number>} size `[width, height, depthOrArrayLayers]` in texels. Read by index,
+ * and floored — `TextureResourceDescriptor.resolution` is a `Float64Array`
+ * @param {GPUTextureDimension|string} dimension `"3d"` makes the third component a depth that
+ * halves per level; anything else makes it a layer count that does not
+ * @param {number} mip_level_count
+ * @param {number} sample_count
+ * @returns {number} bytes
+ * @throws {Error} for a name that is not a GPUTextureFormat — see {@link gpu_texture_format_info}.
+ * A caller that would rather report something than fail (a profile capture, a memory readout) is the
+ * one placed to decide that, and says so where it catches
+ */
+export function gpu_texture_format_memory_footprint(format: GPUTextureFormat, size: ArrayLike<number>, dimension: GPUTextureDimension | string, mip_level_count: number, sample_count: number): number;
 /**
  * What one texel block of a {@link GPUTextureFormat } is.
  *

package/src/shade/descriptor/texture/format/gpu_texture_format_info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpu_texture_format_info.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_format_info.js"],"names":[],"mappings":"AA+MA;;;;;;;;;;;;GAYG;AACH,mEAJa,oBAAoB,CAYhC;AAED;;;;GAIG;AACH,4CAFa,kBAAkB,CAI9B;AAED;;;;;;;;;GASG;AACH,8EAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;GAMG;AACH,+EAHW,MAAM,GACJ,MAAM,CAMlB;;;;;;;;;;;;iBAlQa,MAAM;;;;kBACN,MAAM;;;;qBACN,MAAM;;;;;aACN,kBAAkB;;;;;cAElB,OAAO"}
+{"version":3,"file":"gpu_texture_format_info.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_format_info.js"],"names":[],"mappings":"AAkNA;;;;;;;;;;;;GAYG;AACH,mEAJa,oBAAoB,CAYhC;AAED;;;;GAIG;AACH,4CAFa,kBAAkB,CAI9B;AAED;;;;;;;;;;;;;GAaG;AACH,kFAHa,OAAO,CAOnB;AAED;;;;;;;;;GASG;AACH,8EAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;GAMG;AACH,+EAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;;;;;;;GAcG;AACH,kFAJW,MAAM,UACN,MAAM,GACJ,MAAM,EAAE,CASpB;AAED;;;;;;;;;;;;GAYG;AACH,gFALW,MAAM,UACN,MAAM,mBACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oFAXW,UAAU,MAAM,CAAC,aAEjB,sBAAoB,MAAM,mBAE1B,MAAM,gBACN,MAAM,GACJ,MAAM,CAiClB;;;;;;;;;;;;iBA7Xa,MAAM;;;;kBACN,MAAM;;;;qBACN,MAAM;;;;;aACN,kBAAkB;;;;;cAElB,OAAO"}