@woosh/meep-engine 3.14.2 → 3.14.4

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

@@ -289,6 +289,30 @@ 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.
  *

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/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);
 

package/src/shade/device/mock/SoftwareGPUTexture.d.ts

@@ -12,15 +12,17 @@ export class SoftwareGPUTexture extends SoftwareGPUObjectBase implements GPUText
     /**
      * The texture a device hands back for a descriptor it rejected.
      *
+     * @param {SoftwareGPUDevice} device
      * @param {GPUTextureDescriptor} descriptor as asked for, so a log can say what was wanted
      * @returns {SoftwareGPUTexture}
      */
-    static invalid(descriptor: GPUTextureDescriptor): SoftwareGPUTexture;
+    static invalid(device: SoftwareGPUDevice, descriptor: GPUTextureDescriptor): SoftwareGPUTexture;
     /**
+     * @param {SoftwareGPUDevice} device
      * @param {GPUTextureDescriptor} descriptor
      * @param {boolean} [valid] whether the device accepted `descriptor`; see {@link isValid}
      */
-    constructor(descriptor: GPUTextureDescriptor, valid?: boolean);
+    constructor(device: SoftwareGPUDevice, descriptor: GPUTextureDescriptor, valid?: boolean);
     /**
      * Whether the device accepted the descriptor this was made from. See
      * {@link SoftwareGPUBuffer#isValid} — WebGPU hands back a texture for a descriptor it rejects,

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

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUTexture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUTexture.js"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AACH,yEAFgB,UAAU;IA+CtB;;;;;OAKG;IACH,kDAFa,kBAAkB,CAI9B;IA/BD;;;OAGG;IACH,sDAFW,OAAO,EAmBjB;IAtCD;;;;;;OAMG;IACH,uBAEC;IAoBG,WAAuC;IACvC,YAAyC;IACzC,wBAAiE;IAEjE,YAA+B;IAC/B,eAA6C;IAC7C,WAA6B;IAC7B,iBAA8C;IAC9C,mBAAkD;IAatD;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,wCAEC;IAED;;;;;;;;;OASG;IACH,8BAUC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,WAAW,CAgBvB;IAED;;;OAGG;IACH,kEAMC;IAED;;;OAGG;IACH,gBAOC;IAGL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;;CANhD;sCA1MqC,4BAA4B"}
+{"version":3,"file":"SoftwareGPUTexture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUTexture.js"],"names":[],"mappings":"AAYA;;;;;;;;;GASG;AACH,yEAFgB,UAAU;IAkEtB;;;;;;OAMG;IACH,6EAFa,kBAAkB,CAI9B;IAnCD;;;;OAIG;IACH,iFAFW,OAAO,EAqBjB;IAzDD;;;;;;OAMG;IACH,uBAEC;IAuCG,WAAuC;IACvC,YAAyC;IACzC,wBAAiE;IAEjE,YAA+B;IAC/B,eAA6C;IAC7C,WAA6B;IAC7B,iBAA8C;IAC9C,mBAAkD;IActD;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,wCAEC;IAED;;;;;;;;;OASG;IACH,8BAUC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,WAAW,CAgBvB;IAED;;;OAGG;IACH,kEAqBC;IAED;;;OAGG;IACH,gBAOC;IAGL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;;CANhD;sCA7OqC,4BAA4B"}

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

@@ -6,6 +6,7 @@ import {
     gpu_texture_format_row_count
 } from "../../descriptor/texture/format/gpu_texture_format_info.js";
 import { texture_mip_size } from "../../util/texture_mip_extent.js";
+import { SoftwareGPUValidationError } from "./SoftwareGPUError.js";
 import { SoftwareGPUObjectBase } from "./SoftwareGPUObjectBase.js";
 import { SoftwareGPUTextureView } from "./SoftwareGPUTextureView.js";
 
@@ -42,13 +43,32 @@ export class SoftwareGPUTexture extends SoftwareGPUObjectBase {
     #mip_data = [];
 
     /**
+     * The device that made this, which is where a refused view is reported.
+     *
+     * @type {SoftwareGPUDevice}
+     */
+    #device;
+
+    /**
+     * The formats a view may reinterpret this texture as, beyond its own — `viewFormats` of the
+     * descriptor. WebGPU allows only its own format and these, which is how `rgba8unorm-srgb` is
+     * read as `rgba8unorm` without a copy and only when the creator said it might be.
+     *
+     * @type {GPUTextureFormat[]}
+     */
+    #view_formats;
+
+    /**
+     * @param {SoftwareGPUDevice} device
      * @param {GPUTextureDescriptor} descriptor
      * @param {boolean} [valid] whether the device accepted `descriptor`; see {@link isValid}
      */
-    constructor(descriptor, valid = true) {
+    constructor(device, descriptor, valid = true) {
         super(descriptor);
 
+        this.#device = device;
         this.#valid = valid;
+        this.#view_formats = [...(descriptor.viewFormats ?? [])];
 
         const size = descriptor.size;
 
@@ -67,11 +87,12 @@ export class SoftwareGPUTexture extends SoftwareGPUObjectBase {
     /**
      * The texture a device hands back for a descriptor it rejected.
      *
+     * @param {SoftwareGPUDevice} device
      * @param {GPUTextureDescriptor} descriptor as asked for, so a log can say what was wanted
      * @returns {SoftwareGPUTexture}
      */
-    static invalid(descriptor) {
-        return new SoftwareGPUTexture(descriptor, false);
+    static invalid(device, descriptor) {
+        return new SoftwareGPUTexture(device, descriptor, false);
     }
 
     /**
@@ -193,6 +214,21 @@ export class SoftwareGPUTexture extends SoftwareGPUObjectBase {
             throw new Error('createView on a destroyed texture');
         }
 
+        const format = descriptor?.format;
+
+        /*
+         A view may reinterpret the texture only as a format its descriptor declared. Reported the
+         way the device reports a refused descriptor — through the error scopes — rather than thrown,
+         so a caller reading an sRGB texture as linear without having said so at creation fails the
+         same way it fails on hardware.
+        */
+        if (format !== undefined && format !== this.format && !this.#view_formats.includes(format)) {
+            this.#device.generate_error(new SoftwareGPUValidationError(
+                `createView: '${format}' is neither the format of '${this.label}' (${this.format})`
+                + ` nor one of its viewFormats (${this.#view_formats.join(', ') || 'none'})`
+            ));
+        }
+
         return new SoftwareGPUTextureView(this, descriptor);
     }
 

package/src/shade/device/mock/SoftwareGPUTextureView.d.ts

@@ -9,6 +9,13 @@ export class SoftwareGPUTextureView extends SoftwareGPUObjectBase implements GPU
      */
     constructor(texture: SoftwareGPUTexture, descriptor?: GPUTextureViewDescriptor);
     texture: SoftwareGPUTexture;
+    /**
+     * What the view was asked to be, retained so a test can read which format a texture is
+     * being reinterpreted as — a real view exposes none of it.
+     *
+     * @type {GPUTextureViewDescriptor}
+     */
+    descriptor: GPUTextureViewDescriptor;
     /**
      * @readonly
      * @type {boolean}

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

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUTextureView.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUTextureView.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,6EAFgB,cAAc;IAG1B;;;OAGG;IACH,gFAGC;IADG,4BAAsB;IAI9B;;;OAGG;IACH,mCAFU,OAAO,CAEwC;CANxD;sCAfqC,4BAA4B"}
+{"version":3,"file":"SoftwareGPUTextureView.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUTextureView.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,6EAFgB,cAAc;IAG1B;;;OAGG;IACH,gFAWC;IATG,4BAAsB;IAEtB;;;;;OAKG;IACH,qCAAkC;IAI1C;;;OAGG;IACH,mCAFU,OAAO,CAEwC;CANxD;sCAvBqC,4BAA4B"}

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

@@ -12,6 +12,14 @@ export class SoftwareGPUTextureView extends SoftwareGPUObjectBase {
     constructor(texture, descriptor) {
         super(descriptor);
         this.texture = texture;
+
+        /**
+         * What the view was asked to be, retained so a test can read which format a texture is
+         * being reinterpreted as — a real view exposes none of it.
+         *
+         * @type {GPUTextureViewDescriptor}
+         */
+        this.descriptor = descriptor ?? {};
     }
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AAsHA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CAyDvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}
+{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AAiLA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CA4DvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}

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

@@ -1,4 +1,6 @@
 import { array_buffer_copy } from "../../../core/collection/array/typed/array_buffer_copy.js";
+import { gpu_texture_format_physical_size } from "../../descriptor/texture/format/gpu_texture_format_info.js";
+import { COPY_BYTES_PER_ROW_ALIGNMENT } from "../COPY_BYTES_PER_ROW_ALIGNMENT.js";
 
 /**
  * The three texture copy commands — texture↔texture, buffer→texture, texture→buffer — differ only in
@@ -70,14 +72,38 @@ function texture_endpoint_refusal(info, role, required_usage, required_usage_nam
 
     const origin = normalize_origin(info.origin);
 
-    if (origin.x + extent.width > texture.mip_width(mip) || origin.y + extent.height > texture.mip_height(mip)) {
-        return `${role} region at (${origin.x}, ${origin.y}) sized ${extent.width}x${extent.height} exceeds mip ${mip} of '${texture.label}' (${texture.mip_width(mip)}x${texture.mip_height(mip)})`;
+    /*
+     A copy addresses whole blocks. Its origin sits on a block boundary, its extent is a whole number
+     of blocks, and the level it must fit is the *physical* one — the logical size rounded up to
+     blocks — so a 2x2 tail of a BC chain is copied as one 4x4 block and nothing smaller. WebGPU's
+     rule, not Vulkan's: there is no "partial at the edge" allowance. Checked on Dawn, which refuses
+     a 2x2 extent on a 2x2 level with `copySize.width (2) is not a multiple of compressed texture
+     format block width (4)`. Uncompressed formats are 1x1 blocks and pass trivially.
+    */
+    const format = texture.format_info;
+
+    const physical = gpu_texture_format_physical_size(texture.format, texture.mip_width(mip), texture.mip_height(mip));
+
+    if (origin.x + extent.width > physical[0] || origin.y + extent.height > physical[1]) {
+        return `${role} region at (${origin.x}, ${origin.y}) sized ${extent.width}x${extent.height} exceeds mip ${mip} of '${texture.label}' (${physical[0]}x${physical[1]})`;
     }
 
     if (origin.z + extent.depth > texture.depthOrArrayLayers) {
         return `${role} region reaches layer ${origin.z + extent.depth} of '${texture.label}', which has ${texture.depthOrArrayLayers}`;
     }
 
+    if (origin.x % format.block_width !== 0 || origin.y % format.block_height !== 0) {
+        return `${role} origin (${origin.x}, ${origin.y}) is not on a ${format.block_width}x${format.block_height} block boundary of ${texture.format}`;
+    }
+
+    if (extent.width % format.block_width !== 0) {
+        return `${role} copySize.width (${extent.width}) is not a multiple of the ${format.block_width}-texel block width of ${texture.format}`;
+    }
+
+    if (extent.height % format.block_height !== 0) {
+        return `${role} copySize.height (${extent.height}) is not a multiple of the ${format.block_height}-texel block height of ${texture.format}`;
+    }
+
     return null;
 }
 
@@ -88,9 +114,11 @@ function texture_endpoint_refusal(info, role, required_usage, required_usage_nam
  * @param {string} role
  * @param {GPUFlagsConstant} required_usage
  * @param {string} required_usage_name
+ * @param {GPUTextureFormatInfo} format of the texture at the other end, which decides the block size
+ * @param {{width: number, height: number, depth: number}} extent
  * @returns {string|null}
  */
-function buffer_endpoint_refusal(info, role, required_usage, required_usage_name) {
+function buffer_endpoint_refusal(info, role, required_usage, required_usage_name, format, extent) {
     const buffer = info.buffer;
 
     if (!buffer.isValid) {
@@ -109,8 +137,39 @@ function buffer_endpoint_refusal(info, role, required_usage, required_usage_name
         return `${role} buffer '${buffer.label}' was not created with ${required_usage_name}`;
     }
 
-    if ((info.offset ?? 0) % 4 !== 0) {
-        return `${role} buffer offset ${info.offset} is not a multiple of 4`;
+    const offset = info.offset ?? 0;
+
+    // WebGPU's "validating linear texture data": the offset lands on a whole block, and the rows are
+    // strided at a multiple of 256 whenever there is more than one of them to stride between
+    if (offset % format.bytes_per_block !== 0) {
+        return `${role} buffer offset ${offset} is not a multiple of the ${format.bytes_per_block}-byte block`;
+    }
+
+    const rows = Math.ceil(extent.height / format.block_height);
+    const tight_row = Math.ceil(extent.width / format.block_width) * format.bytes_per_block;
+
+    const multi_row = rows * extent.depth > 1;
+
+    if (info.bytesPerRow === undefined) {
+        if (multi_row) {
+            return `${role} bytesPerRow is required for a copy of more than one row`;
+        }
+    } else {
+        if (info.bytesPerRow % COPY_BYTES_PER_ROW_ALIGNMENT !== 0) {
+            return `${role} bytesPerRow ${info.bytesPerRow} is not a multiple of ${COPY_BYTES_PER_ROW_ALIGNMENT}`;
+        }
+
+        if (info.bytesPerRow < tight_row) {
+            return `${role} bytesPerRow ${info.bytesPerRow} is less than the ${tight_row} bytes a row of ${extent.width} texels takes`;
+        }
+    }
+
+    if (info.rowsPerImage === undefined) {
+        if (extent.depth > 1) {
+            return `${role} rowsPerImage is required for a copy of more than one layer`;
+        }
+    } else if (info.rowsPerImage < rows) {
+        return `${role} rowsPerImage ${info.rowsPerImage} is less than the ${rows} rows a layer of ${extent.height} texels takes`;
     }
 
     return null;
@@ -143,9 +202,9 @@ export function texture_copy_refusal({ texture_source, buffer_source, texture_de
         }
     }
 
-    if (buffer_source !== undefined) {
-        const refusal = buffer_endpoint_refusal(
-            buffer_source, 'source', GPUBufferUsage.COPY_SRC, 'COPY_SRC'
+    if (texture_destination !== undefined) {
+        const refusal = texture_endpoint_refusal(
+            texture_destination, 'destination', GPUTextureUsage.COPY_DST, 'COPY_DST', extent
         );
 
         if (refusal !== null) {
@@ -153,9 +212,12 @@ export function texture_copy_refusal({ texture_source, buffer_source, texture_de
         }
     }
 
-    if (texture_destination !== undefined) {
-        const refusal = texture_endpoint_refusal(
-            texture_destination, 'destination', GPUTextureUsage.COPY_DST, 'COPY_DST', extent
+    // one side is always a texture, and it is the side that knows the block size a buffer is read in
+    const format = (texture_source ?? texture_destination).texture.format_info;
+
+    if (buffer_source !== undefined) {
+        const refusal = buffer_endpoint_refusal(
+            buffer_source, 'source', GPUBufferUsage.COPY_SRC, 'COPY_SRC', format, extent
         );
 
         if (refusal !== null) {
@@ -165,7 +227,7 @@ export function texture_copy_refusal({ texture_source, buffer_source, texture_de
 
     if (buffer_destination !== undefined) {
         const refusal = buffer_endpoint_refusal(
-            buffer_destination, 'destination', GPUBufferUsage.COPY_DST, 'COPY_DST'
+            buffer_destination, 'destination', GPUBufferUsage.COPY_DST, 'COPY_DST', format, extent
         );
 
         if (refusal !== null) {

package/src/shade/playground/basis_textures/README.md

@@ -0,0 +1,105 @@
+# Basis / KTX2 textures
+
+The same scene twice — once with JPEG textures the browser decodes to RGBA8, once with KTX2/Basis
+textures the engine transcodes to a block format — with the GPU memory each costs.
+
+This is tier 8 of the compressed-texture plan's testing ladder, and the only tier with a GPU in it.
+Everything below it runs device-free: the transcoders against the reference encoder's own output,
+the container reader against real and synthesised files, the format tables against themselves. What
+none of that can answer is whether a transcoded payload is a *texture* — whether `createTexture`
+accepts the format, and whether `writeTexture` accepts the block-aligned row layout that a
+container's mip chain implies.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+Then open `/src/shade/playground/basis_textures/index.html`.
+
+Both models are served out of `test_assets/`, which is gitignored — see `test_assets/README.md` for
+how to put Sponza there. The Basis variant is built from it by the tool beside this file:
+
+```bash
+node make_basis_gltf.mjs ../../../../test_assets/Sponza/glTF/Sponza.gltf ../../../../test_assets/Sponza_basis
+```
+
+That needs the `basisu` encoder, which is not a dependency of anything here — `npm i --no-save
+basis_universal` in this directory, or put the binary on `PATH`. It encodes normal maps as UASTC and
+everything else as ETC1S, which is what a real pipeline does and what makes the two transcoder paths
+both appear in one scene.
+
+## What it measured
+
+On an NVIDIA Lovelace device, 2026-09-02:
+
+| | textures | GPU memory | formats |
+|---|---|---|---|
+| JPEG | 69 | 335.3 MiB | 69 × `rgba8` |
+| Basis | 69 | 83.8 MiB | 45 × `bc7-rgba-unorm`, 24 × `bc5-rg-unorm` |
+
+**4.00× less texture memory**, both sides counted the same way and both including their full mip
+chain. All 69 textures uploaded; none was refused by the device.
+
+The format split is the role wiring working: the 24 normal maps are the 24 BC5 textures, chosen
+because a tangent-space normal reconstructs Z in the shader and so spends its eight bits per texel
+on two channels instead of four. Nothing else in the scene reaches BC5.
+
+Three things this page found that no device-free test had:
+
+- **Mip generation was requested for block formats.** `ShadeTexture` asks for generated mips by
+  default, which is right for a decoded JPEG and impossible for a transcoded payload — no BC format
+  can be a render attachment. Every compressed texture was refused at upload. Fixed in `load_gltf`,
+  which now clears the flag when the image's format cannot generate them; the chain in the container
+  is used instead.
+- **`TextureManager.gpu_memory_usage` is a running total, and nothing evicts.** Taking a scene out of
+  the graph leaves its textures in the cache, so reading the total after the second load reported the
+  sum of both and flattered the comparison to 5.00×. The page measures the difference across the
+  upload instead.
+- **Every texture was upside down**, which no number on this page could see — the VRAM table was
+  correct in every particular while the scene was mirrored. `make_basis_gltf.mjs` passed `-y_flip` to
+  `basisu`. glTF puts UV (0,0) at the top-left, and a KTX2 with no `KTXorientation` key means exactly
+  that, so `KHR_texture_basisu` wants a top-down payload; `basisu` writes no such key either way, so
+  the flag bakes in a mirror that no reader can detect or undo. The engine was never at fault. Verify
+  a converter change by encoding an image with a top/bottom asymmetry and checking which row comes
+  back — that is how this was pinned.
+
+## The uncompressed floor
+
+Set **pretend support** to `none` and the scene still loads, at 335.3 MiB across the same 69
+textures — exactly what the JPEG path costs, and with the same sRGB split. Every compressed format in
+WebGPU is an optional feature, so a device exposing none of them is legal; `rgba8unorm` is mandatory,
+so it is the floor. It is also the fastest path here (11.4 s against ~19 s), because the BC re-encode
+is the expensive half and this skips it.
+
+## Known gap
+
+**ETC2 is written** — an ETC1S block already *is* an ETC1 block, so it is a repack that matches the
+reference transcoder byte for byte, and an ETC2-capable device gets eight bits a texel instead of
+thirty-two.
+
+**ASTC is written too**, and leads every role's preference on a device that has it. It was pulled
+once — §9.16 — on a misread measurement: the deviation blamed on this decoder was the reference
+encoder's own loss against the ETC1S source. With the specification in hand it came back at **48.81
+dB against `basisu`'s 48.28** on the same fixture, better on total error and one level behind at the
+peak. §9.17 has the arithmetic that mattered: the interpolation widens endpoints to sixteen bits
+before weighting them, and colour endpoint mode 8 swaps and blue-contracts a pair written the wrong
+way round.
+
+**UASTC repacks to ASTC**, which is the path that format was designed for: its fields are ASTC’s
+fields, so nothing is fitted and nothing is lost. Byte-identical to the reference transcoder on 2320
+of 2352 fixture blocks, and provably equivalent on the rest. That closes the last gap — a no-BC
+device now costs **83.8 MiB on Sponza, the same as desktop**, where it was 173.1 MiB.
+
+Still unwritten: ETC2 from UASTC, for a device with ETC2 but not ASTC. The availability figures
+suggest that population is close to empty.
+
+## Why it cannot draw here
+
+The renderer needs `maxImmediateSize` ≥ 24 bytes and assumes the 64-byte floor every conformant
+device reports. A Chrome build without immediate-data support offers 0, and the frame loop then dies
+in `GPUTypedTable/Upload elements` — for every playground in this directory, not just this one. The
+measurements above do not depend on a frame: textures are uploaded explicitly through
+`TextureManager.obtain`, which is the same call the renderer makes and the same moment the device
+accepts the format or does not. Seeing the scene needs a browser with immediate data.