@woosh/meep-engine 3.14.0 → 3.14.2

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_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,51 @@ 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;
+/**
+ * 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;;;;;;;;;;;;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;;;;;;;;;;;;iBArWa,MAAM;;;;kBACN,MAAM;;;;qBACN,MAAM;;;;;aACN,kBAAkB;;;;;cAElB,OAAO"}

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

@@ -1,3 +1,6 @@
+import { assert } from "../../../../core/assert.js";
+import { texture_mip_extent } from "../../../util/texture_mip_extent.js";
+
 /**
  * What one texel block of a {@link GPUTextureFormat} is.
  *
@@ -237,6 +240,26 @@ export function gpu_texture_format_names() {
     return Object.keys(FORMATS);
 }
 
+/**
+ * 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) {
+    const info = gpu_texture_format_info(format);
+
+    return info.block_width !== 1 || info.block_height !== 1;
+}
+
 /**
  * Bytes one row of `width` texels occupies, tightly packed.
  *
@@ -265,3 +288,82 @@ export function gpu_texture_format_row_count(format, height) {
 
     return Math.ceil(height / info.block_height);
 }
+
+/**
+ * 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, width, height, depth_or_layers) {
+    return gpu_texture_format_row_bytes(format, width)
+        * gpu_texture_format_row_count(format, height)
+        * depth_or_layers;
+}
+
+/**
+ * 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,
+    size,
+    dimension,
+    mip_level_count,
+    sample_count
+) {
+    assert.isArrayLike(size, 'size');
+    assert.isString(dimension, 'dimension');
+    assert.isNonNegativeInteger(mip_level_count, 'mip_level_count');
+    assert.isNonNegativeInteger(sample_count, 'sample_count');
+
+    // throws here rather than inside the loop, for a name that is not a GPUTextureFormat
+    gpu_texture_format_info(format);
+
+    const width = Math.floor(size[0]);
+    const height = Math.floor(size[1]);
+    const depth_or_layers = Math.floor(size[2]);
+
+    let total = 0;
+
+    for (let mip = 0; mip < mip_level_count; mip++) {
+        const extent = texture_mip_extent(width, height, depth_or_layers, dimension, mip);
+
+        total += gpu_texture_format_level_bytes(format, extent[0], extent[1], extent[2]);
+    }
+
+    return total * sample_count;
+}

package/src/shade/device/graph/TextureResourceDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextureResourceDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/graph/TextureResourceDescriptor.js"],"names":[],"mappings":";;;sCAeU,MAAM;;;;;AAOhB;IAmCI;;;;;;;;OAQG;IACH,kEAPW,MAAM,EAAE,GAKN,yBAAyB,CA8BrC;IAED;;;;OAIG;IACH,yCAFa,yBAAyB,CAoBrC;IAhGD;;;;;;;;;OASG;IACH,mBAFU,uBAAuB,GAAC,MAAM,CAEyB;IAGjE,yBAAyC;IACzC,oBAAgB;IAEhB,sBAAkB;IAElB;;;OAGG;IACH,WAFU,sBAAoB,MAAM,CAEpB;IAEhB;;OAEG;IACH,QAFU,MAAM,mBAAiB,CAEX;IAEtB;;OAEG;IACH,OAFU,MAAM,uBAAqB,CAEG;IAiFxC;;;;OAIG;IACH,cAHW,yBAAyB,GACvB,OAAO,CAWnB;CAKJ;mCAnJM,4EAA4E"}
+{"version":3,"file":"TextureResourceDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/graph/TextureResourceDescriptor.js"],"names":[],"mappings":";;;sCAgBU,MAAM;;;;;AAOhB;IAmCI;;;;;;;;OAQG;IACH,kEAPW,MAAM,EAAE,GAKN,yBAAyB,CAkCrC;IAED;;;;OAIG;IACH,yCAFa,yBAAyB,CAoBrC;IApGD;;;;;;;;;OASG;IACH,mBAFU,uBAAuB,GAAC,MAAM,CAEyB;IAGjE,yBAAyC;IACzC,oBAAgB;IAEhB,sBAAkB;IAElB;;;OAGG;IACH,WAFU,sBAAoB,MAAM,CAEpB;IAEhB;;OAEG;IACH,QAFU,MAAM,mBAAiB,CAEX;IAEtB;;OAEG;IACH,OAFU,MAAM,uBAAqB,CAEG;IAqFxC;;;;OAIG;IACH,cAHW,yBAAyB,GACvB,OAAO,CAWnB;CAKJ;mCAxJM,4EAA4E"}