@woosh/meep-engine 3.14.1 → 3.14.3

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,106 @@ export function gpu_texture_format_row_count(format, height) {
 
     return Math.ceil(height / info.block_height);
 }
+
+/**
+ * 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, width, height) {
+    const info = gpu_texture_format_info(format);
+
+    return [
+        Math.ceil(width / info.block_width) * info.block_width,
+        Math.ceil(height / info.block_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/descriptor/texture/format/gpu_texture_format_srgb.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The sRGB counterpart of a format, or `undefined` where it has none.
+ *
+ * The two differ only in how a sample is decoded — the bytes are identical, and the size arithmetic
+ * in {@link gpu_texture_format_info} is the same for both. Which is exactly why the choice cannot be
+ * made when the *bytes* are chosen: a transcoder targeting `bc7-rgba-unorm` and one targeting
+ * `bc7-rgba-unorm-srgb` do the same work, so the encoding is picked by what the device can sample
+ * and the decode by what the texture *means*.
+ *
+ * @param {GPUTextureFormat} format a linear format; an sRGB one is returned unchanged, since it is
+ *        already its own counterpart
+ * @returns {GPUTextureFormat|undefined}
+ * @throws {Error} if `format` is not a GPUTextureFormat at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gpu_texture_format_srgb(format: GPUTextureFormat): GPUTextureFormat | undefined;
+//# sourceMappingURL=gpu_texture_format_srgb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_format_srgb.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_format_srgb.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;GAgBG;AACH,mEANa,mBAAiB,SAAS,CAetC"}

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

@@ -0,0 +1,50 @@
+import { gpu_texture_format_info, gpu_texture_format_names } from "./gpu_texture_format_info.js";
+
+/**
+ * Every format that has an sRGB counterpart, mapped to it.
+ *
+ * **Derived from the format table rather than listed.** WebGPU spells every sRGB format as its
+ * linear name plus `-srgb` — `rgba8unorm-srgb`, `bc7-rgba-unorm-srgb`, `astc-4x4-unorm-srgb` — with
+ * no exceptions, so a hand-written list would be a second copy of the table that could disagree with
+ * it. Building the pairs by suffix means a format added to the table brings its own pairing.
+ *
+ * @readonly
+ * @type {Map<GPUTextureFormat, GPUTextureFormat>}
+ */
+const SRGB_OF = new Map();
+
+for (const name of gpu_texture_format_names()) {
+    const linear = name.endsWith("-srgb") ? name.slice(0, -"-srgb".length) : undefined;
+
+    if (linear !== undefined) {
+        SRGB_OF.set(linear, name);
+    }
+}
+
+/**
+ * The sRGB counterpart of a format, or `undefined` where it has none.
+ *
+ * The two differ only in how a sample is decoded — the bytes are identical, and the size arithmetic
+ * in {@link gpu_texture_format_info} is the same for both. Which is exactly why the choice cannot be
+ * made when the *bytes* are chosen: a transcoder targeting `bc7-rgba-unorm` and one targeting
+ * `bc7-rgba-unorm-srgb` do the same work, so the encoding is picked by what the device can sample
+ * and the decode by what the texture *means*.
+ *
+ * @param {GPUTextureFormat} format a linear format; an sRGB one is returned unchanged, since it is
+ *        already its own counterpart
+ * @returns {GPUTextureFormat|undefined}
+ * @throws {Error} if `format` is not a GPUTextureFormat at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function gpu_texture_format_srgb(format) {
+    // throws for a name that is not a format, which is worth knowing before the lookup misses
+    gpu_texture_format_info(format);
+
+    if (format.endsWith("-srgb")) {
+        return format;
+    }
+
+    return SRGB_OF.get(format);
+}

package/src/shade/device/COPY_BYTES_PER_ROW_ALIGNMENT.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What `bytesPerRow` must be a multiple of in `copyBufferToTexture` and `copyTextureToBuffer`.
+ *
+ * A property of the buffer-texture copy commands, not of any format: `writeTexture` has no such
+ * requirement, which is why a tightly packed payload uploads straight from host memory while a
+ * buffer produced on the device has to be laid out with padded rows before it can be copied into a
+ * texture. WebGPU does not expose the number as a constant, so it is named here once.
+ *
+ * @see https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-copybuffertotexture
+ * @readonly
+ * @type {number}
+ */
+export const COPY_BYTES_PER_ROW_ALIGNMENT: number;
+//# sourceMappingURL=COPY_BYTES_PER_ROW_ALIGNMENT.d.ts.map

package/src/shade/device/COPY_BYTES_PER_ROW_ALIGNMENT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"COPY_BYTES_PER_ROW_ALIGNMENT.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/COPY_BYTES_PER_ROW_ALIGNMENT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,2CAFU,MAAM,CAEgC"}

package/src/shade/device/COPY_BYTES_PER_ROW_ALIGNMENT.js

@@ -0,0 +1,13 @@
+/**
+ * What `bytesPerRow` must be a multiple of in `copyBufferToTexture` and `copyTextureToBuffer`.
+ *
+ * A property of the buffer-texture copy commands, not of any format: `writeTexture` has no such
+ * requirement, which is why a tightly packed payload uploads straight from host memory while a
+ * buffer produced on the device has to be laid out with padded rows before it can be copied into a
+ * texture. WebGPU does not expose the number as a constant, so it is named here once.
+ *
+ * @see https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-copybuffertotexture
+ * @readonly
+ * @type {number}
+ */
+export const COPY_BYTES_PER_ROW_ALIGNMENT = 256;

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

package/src/shade/device/graph/TextureResourceDescriptor.js

@@ -1,156 +1,161 @@
-import { assert } from "../../../core/assert.js";
-import { array_copy } from "../../../core/collection/array/array_copy.js";
-import { combine_hash } from "../../../core/collection/array/combine_hash.js";
-import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
-import { computeHashFloatArray } from "../../../core/math/hash/computeHashFloatArray.js";
-import { computeStringHash } from "../../../core/primitives/strings/computeStringHash.js";
-import {
-    ResourceDescriptor
-} from "../../../engine/graphics/render/frame_graph/resource/ResourceDescriptor.js";
-import { compute_max_mip_count } from "../../util/compute_max_mip_count.js";
-import { decode_bitmask_enum } from "../decode_bitmask_enum.js";
-
-/**
- * **Vestigial.** Nothing branches on it — see {@link TextureResourceDescriptor.resolution_domain}.
- *
- * @enum {number}
- */
-export const TextureResolutionDomain = {
-    Absolute: 0,
-    PresentationRelative: 1
-}
-
-export class TextureResourceDescriptor extends ResourceDescriptor {
-    /**
-     * **Vestigial. Do not read this to decide how to interpret {@link resolution}.**
-     *
-     * No code branches on it; only {@link hash} folds it in. {@link from} stores whatever
-     * resolution it is given without touching this field, and every caller gives it pixels — so a
-     * descriptor's resolution is absolute pixels whatever this says, including on the default
-     * `PresentationRelative` that {@link from} leaves in place.
-     *
-     * @type {TextureResolutionDomain|number}
-     */
-    resolution_domain = TextureResolutionDomain.PresentationRelative;
-
-    // TODO use Uint32 instead
-    resolution = new Float64Array([1, 1, 1]);
-    sampleCount = 1;
-
-    mipLevelCount = 1;
-
-    /**
-     *
-     * @type {GPUTextureDimension|string}
-     */
-    dimension = "2d"
-
-    /**
-     * @type {string|GPUTextureFormat}
-     */
-    format = "rgba8unorm";
-
-    /**
-     * @type {number|GPUTextureUsageFlags}
-     */
-    usage = GPUTextureUsage.TEXTURE_BINDING;
-
-    /**
-     *
-     * @param {number[]} resolution
-     * @param {GPUTextureDimension|string} [dimension]
-     * @param {GPUTextureFormat|string} format
-     * @param {GPUTextureUsageFlags|number} [usage]
-     * @param {boolean} [enableMips]
-     * @returns {TextureResourceDescriptor}
-     */
-    static from({
-                    resolution,
-                    dimension = "2d",
-                    format,
-                    usage = GPUTextureUsage.TEXTURE_BINDING,
-                    enableMips = false
-                }) {
-
-        assert.isString(format, 'format');
-        assert.defined(resolution, 'resolution');
-        assert.isArrayLike(resolution, 'resolution');
-        assert.isBoolean(enableMips, 'enableMips');
-
-        const r = new TextureResourceDescriptor();
-
-        array_copy(resolution, 0, r.resolution, 0, Math.min(r.resolution.length, resolution.length));
-        r.dimension = dimension;
-        r.format = format;
-        r.usage = usage;
-
-        if (enableMips === true) {
-
-            r.mipLevelCount = compute_max_mip_count(resolution[0], resolution[1]);
-
-        }
-
-        return r;
-
-    }
-
-    /**
-     *
-     * @param {GPUTexture} texture
-     * @returns {TextureResourceDescriptor}
-     */
-    static fromTexture(texture) {
-        const r = new TextureResourceDescriptor();
-
-        r.format = texture.format;
-        r.dimension = texture.dimension;
-
-        r.usage = texture.usage;
-        r.sampleCount = texture.sampleCount;
-        r.resolution_domain = TextureResolutionDomain.Absolute;
-
-        r.resolution[0] = texture.width;
-        r.resolution[1] = texture.height;
-        r.resolution[2] = texture.depthOrArrayLayers;
-
-
-        r.mipLevelCount = texture.mipLevelCount;
-
-        return r;
-    }
-
-    get type() {
-        return "texture";
-    }
-
-    hash() {
-        return combine_hash(
-            this.resolution_domain,
-            this.mipLevelCount,
-            computeHashFloatArray(this.resolution),
-            this.sampleCount,
-            this.usage,
-            computeStringHash(this.format)
-        );
-    }
-
-    /**
-     *
-     * @param {TextureResourceDescriptor} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return isArrayEqualStrict(this.resolution, other.resolution)
-            && this.mipLevelCount === other.mipLevelCount
-            && this.resolution_domain === other.resolution_domain
-            && this.sampleCount === other.sampleCount
-            && this.dimension === other.dimension
-            && this.format === other.format
-            && this.usage === other.usage
-            ;
-    }
-
-    toString() {
-        return `Texture{ resolution = [${this.resolution.join(",")}], mipLevelCount = ${this.mipLevelCount}, dimension = ${this.dimension}, format = ${this.format}, usage = ${decode_bitmask_enum(this.usage, GPUTextureUsage).join(' | ')}, sampleCount = ${this.sampleCount} }`;
-    }
+import { assert } from "../../../core/assert.js";
+import { array_copy } from "../../../core/collection/array/array_copy.js";
+import { combine_hash } from "../../../core/collection/array/combine_hash.js";
+import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
+import { computeHashFloatArray } from "../../../core/math/hash/computeHashFloatArray.js";
+import { computeStringHash } from "../../../core/primitives/strings/computeStringHash.js";
+import {
+    ResourceDescriptor
+} from "../../../engine/graphics/render/frame_graph/resource/ResourceDescriptor.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+import { decode_bitmask_enum } from "../decode_bitmask_enum.js";
+import { GPUTextureUsage } from "../../descriptor/GPUTextureUsage.js";
+
+/**
+ * **Vestigial.** Nothing branches on it — see {@link TextureResourceDescriptor.resolution_domain}.
+ *
+ * @enum {number}
+ */
+export const TextureResolutionDomain = {
+    Absolute: 0,
+    PresentationRelative: 1
+}
+
+export class TextureResourceDescriptor extends ResourceDescriptor {
+    /**
+     * **Vestigial. Do not read this to decide how to interpret {@link resolution}.**
+     *
+     * No code branches on it; only {@link hash} folds it in. {@link from} stores whatever
+     * resolution it is given without touching this field, and every caller gives it pixels — so a
+     * descriptor's resolution is absolute pixels whatever this says, including on the default
+     * `PresentationRelative` that {@link from} leaves in place.
+     *
+     * @type {TextureResolutionDomain|number}
+     */
+    resolution_domain = TextureResolutionDomain.PresentationRelative;
+
+    // TODO use Uint32 instead
+    resolution = new Float64Array([1, 1, 1]);
+    sampleCount = 1;
+
+    mipLevelCount = 1;
+
+    /**
+     *
+     * @type {GPUTextureDimension|string}
+     */
+    dimension = "2d"
+
+    /**
+     * @type {string|GPUTextureFormat}
+     */
+    format = "rgba8unorm";
+
+    /**
+     * @type {number|GPUTextureUsageFlags}
+     */
+    usage = GPUTextureUsage.TEXTURE_BINDING;
+
+    /**
+     *
+     * @param {number[]} resolution
+     * @param {GPUTextureDimension|string} [dimension]
+     * @param {GPUTextureFormat|string} format
+     * @param {GPUTextureUsageFlags|number} [usage]
+     * @param {boolean} [enableMips]
+     * @returns {TextureResourceDescriptor}
+     */
+    static from({
+                    resolution,
+                    dimension = "2d",
+                    format,
+                    usage = GPUTextureUsage.TEXTURE_BINDING,
+                    enableMips = false
+                }) {
+
+        assert.isString(format, 'format');
+        assert.defined(resolution, 'resolution');
+        assert.isArrayLike(resolution, 'resolution');
+        assert.isBoolean(enableMips, 'enableMips');
+
+        const r = new TextureResourceDescriptor();
+
+        array_copy(resolution, 0, r.resolution, 0, Math.min(r.resolution.length, resolution.length));
+        r.dimension = dimension;
+        r.format = format;
+        r.usage = usage;
+
+        if (enableMips === true) {
+
+            // `r.resolution` rather than the argument: it has already been padded to three, so a
+            // caller that gave two axes reads as depth 1 instead of `undefined`
+            r.mipLevelCount = texture_mip_level_count(
+                r.resolution[0], r.resolution[1], r.resolution[2], r.dimension
+            );
+
+        }
+
+        return r;
+
+    }
+
+    /**
+     *
+     * @param {GPUTexture} texture
+     * @returns {TextureResourceDescriptor}
+     */
+    static fromTexture(texture) {
+        const r = new TextureResourceDescriptor();
+
+        r.format = texture.format;
+        r.dimension = texture.dimension;
+
+        r.usage = texture.usage;
+        r.sampleCount = texture.sampleCount;
+        r.resolution_domain = TextureResolutionDomain.Absolute;
+
+        r.resolution[0] = texture.width;
+        r.resolution[1] = texture.height;
+        r.resolution[2] = texture.depthOrArrayLayers;
+
+
+        r.mipLevelCount = texture.mipLevelCount;
+
+        return r;
+    }
+
+    get type() {
+        return "texture";
+    }
+
+    hash() {
+        return combine_hash(
+            this.resolution_domain,
+            this.mipLevelCount,
+            computeHashFloatArray(this.resolution),
+            this.sampleCount,
+            this.usage,
+            computeStringHash(this.format)
+        );
+    }
+
+    /**
+     *
+     * @param {TextureResourceDescriptor} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return isArrayEqualStrict(this.resolution, other.resolution)
+            && this.mipLevelCount === other.mipLevelCount
+            && this.resolution_domain === other.resolution_domain
+            && this.sampleCount === other.sampleCount
+            && this.dimension === other.dimension
+            && this.format === other.format
+            && this.usage === other.usage
+            ;
+    }
+
+    toString() {
+        return `Texture{ resolution = [${this.resolution.join(",")}], mipLevelCount = ${this.mipLevelCount}, dimension = ${this.dimension}, format = ${this.format}, usage = ${decode_bitmask_enum(this.usage, GPUTextureUsage).join(' | ')}, sampleCount = ${this.sampleCount} }`;
+    }
 }

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+OA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmHD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAnoBa,mBAAiB,IAAI;;sCA9OG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA4PA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAwID;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAxpBa,mBAAiB,IAAI;;sCA3PG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -12,6 +12,7 @@ import { SoftwareGPUSampler } from "./SoftwareGPUSampler.js";
 import { SoftwareGPUShaderModule } from "./SoftwareGPUShaderModule.js";
 import { SoftwareGPUTexture } from "./SoftwareGPUTexture.js";
 import { SoftwareGPUUncapturedErrorEvent } from "./SoftwareGPUUncapturedErrorEvent.js";
+import { gpu_texture_format_feature } from "../../descriptor/texture/format/gpu_texture_format_feature.js";
 import { gpu_texture_format_info } from "../../descriptor/texture/format/gpu_texture_format_info.js";
 
 /**
@@ -191,7 +192,19 @@ const CORE_FEATURE = "core-features-and-limits";
  *
  * @type {GPUFeatureName[]}
  */
-const SUPPORTED_OPTIONAL_FEATURES = ["timestamp-query", "subgroups"];
+const SUPPORTED_OPTIONAL_FEATURES = [
+    "timestamp-query",
+    "subgroups",
+    /*
+     The three compression families are the same argument as `subgroups` again, with one thing this
+     device *can* honour: `createTexture` of a block format is a validation error without the family's
+     feature on a real device, and refusing it here is what lets an orchestration spec catch a caller
+     that never asked for the feature — the mistake that otherwise surfaces only on hardware.
+    */
+    "texture-compression-bc",
+    "texture-compression-etc2",
+    "texture-compression-astc",
+];
 
 /**
  * A buffer that can be mapped for reading may combine that with nothing but `COPY_DST`, and one
@@ -665,6 +678,27 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
             return error.message;
         }
 
+        const feature = gpu_texture_format_feature(descriptor.format);
+
+        if (feature !== undefined && !this.#features.has(feature)) {
+            return `'${descriptor.format}' needs the '${feature}' feature, which this device was not created with`;
+        }
+
+        // a compressed texture's base level is whole blocks; only its mip tail may be partial
+        const block = gpu_texture_format_info(descriptor.format);
+
+        if (width % block.block_width !== 0 || height % block.block_height !== 0) {
+            return `${width}x${height} is not a multiple of the ${block.block_width}x${block.block_height} block of '${descriptor.format}'`;
+        }
+
+        for (const view_format of descriptor.viewFormats ?? []) {
+            try {
+                gpu_texture_format_info(view_format);
+            } catch (error) {
+                return `viewFormats: ${error.message}`;
+            }
+        }
+
         const limits = this.limits;
 
         if (dimension === "1d") {
@@ -728,10 +762,10 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
         if (refusal !== null) {
             this.generate_error(new SoftwareGPUValidationError(`createTexture: ${refusal}`));
 
-            return SoftwareGPUTexture.invalid(descriptor);
+            return SoftwareGPUTexture.invalid(this, descriptor);
         }
 
-        const texture = new SoftwareGPUTexture(descriptor);
+        const texture = new SoftwareGPUTexture(this, descriptor);
 
         this.#track(texture);