@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/texture/atlas/GPUTileAtlas3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTileAtlas3D.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/GPUTileAtlas3D.js"],"names":[],"mappings":"AAijBA;;;;;;;;GAQG;AACH,2CANW,MAAM,WACN,MAAM,WACN,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAchC;AAED;;;;;;;;;;GAUG;AACH,sDANW,MAAM,WACN,MAAM,cACN,MAAM,OACN,MAAM,EAAE,GACN,OAAO,CAuBnB;AAED;;;;;;;;;;;;;GAaG;AACH,mDAPW,UAAU,gBACV,MAAM,UACN,MAAM,mBACN,MAAM,OACN,UAAU,GACR,UAAU,CAwCtB;AA1pBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IA0EI;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAlB8B,MAAM;QACC,MAAM;QAEhB,YAAY,EAA5B,MAAM;QACU,MAAM,EAAtB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,QAAQ,EAAxB,MAAM;QAEwB,KAAK;QAInB,KAAK,EAArB,MAAM;OA4DhB;IAED;;OAEG;IACH,iCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;OAEG;IACH,yBAEC;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;OAKG;IACH,YAFa,MAAM,CAkBlB;IAED;;OAEG;IACH,WAFW,MAAM,QAOhB;IAED;;;;;;;OAOG;IACH,kBAJW,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAehC;IAED;;;;;;OAMG;IACH,YAHW,MAAM,WACN,UAAU,QA4BpB;IAED;;;;;;;;;;;OAWG;IACH,mDANW,MAAM,kCAEN,MAAM,iBACN,MAAM,QA2BhB;IAED,gBAEC;;CA0HJ;kCA7iBiC,yBAAyB"}
+{"version":3,"file":"GPUTileAtlas3D.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/GPUTileAtlas3D.js"],"names":[],"mappings":"AA8lBA;;;;;;;;GAQG;AACH,2CANW,MAAM,WACN,MAAM,WACN,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAchC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,sDARW,MAAM,WACN,MAAM,eACN,MAAM,eACN,MAAM,iBACN,MAAM,OACN,MAAM,EAAE,GACN,OAAO,CAoCnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,mDATW,UAAU,gBAEV,UAAU,MAAM,CAAC,UACjB,MAAM,mBACN,MAAM,OACN,UAAU,GAER,UAAU,CAkDtB;AAtuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IA4FI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAnB8B,MAAM;QACC,MAAM;QAEd,YAAY,EAA9B,MAAM,EAAE;QAEQ,MAAM,EAAtB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,OAAO,EAAvB,MAAM;QAEU,QAAQ,EAAxB,MAAM;QAEwB,KAAK;QAInB,KAAK,EAArB,MAAM;OA0EhB;IAED;;OAEG;IACH,iCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,8BAEC;IAED;;;OAGG;IACH,sCAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;;OAIG;IACH,mCAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;OAKG;IACH,YAFa,MAAM,CAkBlB;IAED;;OAEG;IACH,WAFW,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,kBAJW,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAehC;IAED;;;;;;;OAOG;IACH,YAJW,MAAM,WACN,UAAU,QAiCpB;IAED;;;;;;;;;;;OAWG;IACH,mDANW,MAAM,kCAEN,MAAM,iBACN,MAAM,QA+BhB;IAED,gBAEC;;CAsHJ;kCA1lBiC,yBAAyB"}

package/src/shade/renderer/texture/atlas/GPUTileAtlas3D.js

@@ -3,31 +3,36 @@ import { gpu_texture_format_info } from "../../../descriptor/texture/format/gpu_
 import { GPUTextureContext } from "../GPUTextureContext.js";
 
 /**
- * One 3-D texture cut into equal tiles, each tile a `content_size³` block of texels wrapped in a
- * `border`-texel skirt, handed out one slot at a time.
+ * One 3-D texture cut into equal tiles, each tile a block of `content_size[0] × content_size[1] ×
+ * content_size[2]` texels wrapped in a `border`-texel skirt, handed out one slot at a time. A tile
+ * has its own length along each axis; a cube is the case where the three are equal, declared as
+ * such.
  *
  * **What the border is for.** A tile sampled with a linear filter reads half a texel past its
  * content on every side. The skirt holds the texels a *wrapping* tile would find there — the
- * opposite edge of the same content — so a trilinear tap at the tile's edge blends with the tile's
- * other side and never with the neighbouring slot. {@link tile_atlas_bordered_block} builds that
- * skirt on the host; a producer writing on the device (a compute bake copying in through
- * {@link copy_from_buffer}, or storing into the texture from a shader) writes the whole
- * `tile_size³` block, skirt included, itself. One texel of border is what a linear filter needs; a
- * wider one is for a consumer that steps further (a distance field marched across a tile), which is
- * why it is a parameter. A consumer that never reads past its tile — loads clamped to the content —
- * wants none.
+ * opposite edge of the same content, along each axis by that axis's length — so a trilinear tap at
+ * the tile's edge blends with the tile's other side and never with the neighbouring slot.
+ * {@link tile_atlas_bordered_block} builds that skirt on the host; a producer writing on the device
+ * (a compute bake copying in through {@link copy_from_buffer}, or storing into the texture from a
+ * shader) writes the whole `tile_size` block, skirt included, itself. One texel of border is what a
+ * linear filter needs; a wider one is for a consumer that steps further (a distance field marched
+ * across a tile), which is why it is a parameter. A consumer that never reads past its tile — loads
+ * clamped to the content — wants none. The border is the same on every side and every axis.
  *
  * **Slots are linear, and grow two ways.** Slot `s` sits at grid cell
  * `(s mod slots_x, floor(s / slots_x) mod slots_y, floor(s / (slots_x · slots_y)))`, x fastest and
- * z slowest. When none is free, {@link allocate}:
+ * z slowest, and a cell is one tile along each axis: its texel origin is the cell times
+ * {@link tile_size}, per axis ({@link slot_origin}; `chunk_tile_atlas_slot_origin` on the device).
+ * When no slot is free, {@link allocate}:
  * - **adds a layer** of `slots_x · slots_y` slots at the end of z. Nothing already placed moves, so
  *   the old extent is copied across as it was. This is the common grow.
- * - **widens the layer** once z is at the device's `maxTextureDimension3D`: the smaller of x and y
- *   doubles (x on a tie, capped at the device), the layers halve, and every tile is copied to where
- *   its slot sits under the new footprint ({@link tile_atlas_widened_footprint}). A slot keeps its
- *   index and its texels; its *origin* changes. Rare, and as costly as a full copy.
+ * - **widens the layer** once z is at the device's `maxTextureDimension3D`: the side narrower in
+ *   texels doubles (x on a tie, each capped at its own limit), the layers halve, and every tile is
+ *   copied to where its slot sits under the new footprint ({@link tile_atlas_widened_footprint}). A
+ *   slot keeps its index and its texels; its *origin* changes. Rare, and as costly as a full copy.
  *
- * {@link capacity_limit} is where both run out: the device's limit in tiles along every axis.
+ * {@link capacity_limit} is where both run out: along every axis, as many tiles of that axis's
+ * length as fit under `maxTextureDimension3D`.
  *
  * **Allocation reallocates the texture.** A grow replaces {@link texture}'s `GPUTexture` (the
  * `GPUTextureContext` stays; its views are re-made), and a widen moves every tile. Take the
@@ -40,8 +45,9 @@ import { GPUTextureContext } from "../GPUTextureContext.js";
  *
  * Clients: the volumetrics noise atlas (`r8unorm`, 128³ + 1, sampled) and the per-geometry SDF
  * atlas of `GPUGeometrySDFManager` (`r32float`, 50³ + 0, stored into by its build shader). Built
- * general — format, tile size, border, footprint and usage are all constructor arguments — so a
- * brick SDF atlas can be another instance rather than another class.
+ * general — format, tile size per axis, border, footprint and usage are all constructor arguments —
+ * so a brick SDF atlas or a published wind field can be another instance rather than another
+ * class.
  */
 export class GPUTileAtlas3D {
     /**
@@ -65,7 +71,8 @@ export class GPUTileAtlas3D {
     #bytes_per_texel;
 
     /**
-     * @type {number}
+     * Texels of content along x, y and z.
+     * @type {readonly number[]}
      */
     #content_size;
 
@@ -75,10 +82,27 @@ export class GPUTileAtlas3D {
     #border;
 
     /**
-     * @type {number}
+     * Texels along x, y and z of a whole tile, skirt included.
+     * @type {readonly number[]}
      */
     #tile_size;
 
+    /**
+     * Tiles that fit along x under `maxTextureDimension3D`.
+     * @type {number}
+     */
+    #limit_x;
+
+    /**
+     * @type {number}
+     */
+    #limit_y;
+
+    /**
+     * @type {number}
+     */
+    #limit_z;
+
     /**
      * @type {number}
      */
@@ -124,9 +148,10 @@ export class GPUTileAtlas3D {
      * @param {GPUDevice} options.device
      * @param {GPUTextureFormat} options.format an uncompressed, copyable format — what a 3-D texture
      * allows, and what {@link write} sizes its block by
-     * @param {number} options.content_size texels of content along each axis of a tile
+     * @param {number[]} options.content_size texels of content along x, y and z of a tile, three
+     * positive integers; a cubic tile is `[n, n, n]`. Copied: the array stays the caller's
      * @param {number} options.border texels of skirt on each side of the content, at least 1 for a
-     * linear filter
+     * linear filter, and no more than the shortest axis of the content
      * @param {number} options.slots_x tiles along x to start with; it changes only when the atlas
      * widens
      * @param {number} options.slots_y tiles along y to start with; it changes only when the atlas
@@ -142,10 +167,13 @@ export class GPUTileAtlas3D {
     constructor({ device, format, content_size, border, slots_x, slots_y, capacity, usage, label }) {
         assert.defined(device, 'device');
         assert.isString(format, 'format');
-        assert.isNonNegativeInteger(content_size, 'content_size');
-        assert.greaterThan(content_size, 0, 'content_size');
+        assert.isArrayLike(content_size, 'content_size');
+        assert.equal(content_size.length, 3, 'content_size is texels along x, y and z');
+        assert.isPositiveInteger(content_size[0], 'content_size[0]');
+        assert.isPositiveInteger(content_size[1], 'content_size[1]');
+        assert.isPositiveInteger(content_size[2], 'content_size[2]');
         assert.isNonNegativeInteger(border, 'border');
-        assert.lessThanOrEqual(border, content_size, 'border must not exceed content_size: the skirt is the opposite edge of the content, and there is no more of it');
+        assert.lessThanOrEqual(border, Math.min(content_size[0], content_size[1], content_size[2]), 'border must not exceed the shortest axis of content_size: the skirt is the opposite edge of the content, and there is no more of it');
         assert.isNonNegativeInteger(slots_x, 'slots_x');
         assert.greaterThan(slots_x, 0, 'slots_x');
         assert.isNonNegativeInteger(slots_y, 'slots_y');
@@ -164,9 +192,22 @@ export class GPUTileAtlas3D {
         this.#device = device;
         this.#format = format;
         this.#bytes_per_texel = info.bytes_per_block;
-        this.#content_size = content_size;
+        this.#content_size = Object.freeze([content_size[0], content_size[1], content_size[2]]);
         this.#border = border;
-        this.#tile_size = content_size + 2 * border;
+
+        const tile_x = content_size[0] + 2 * border;
+        const tile_y = content_size[1] + 2 * border;
+        const tile_z = content_size[2] + 2 * border;
+
+        this.#tile_size = Object.freeze([tile_x, tile_y, tile_z]);
+
+        // a 3-D texture has the same limit on all three axes; a tile reaches it at its own length
+        const max_dimension = device.limits.maxTextureDimension3D;
+
+        this.#limit_x = Math.floor(max_dimension / tile_x);
+        this.#limit_y = Math.floor(max_dimension / tile_y);
+        this.#limit_z = Math.floor(max_dimension / tile_z);
+
         this.#slots_x = slots_x;
         this.#slots_y = slots_y;
         this.#label = label;
@@ -186,15 +227,13 @@ export class GPUTileAtlas3D {
 
         this.#texture = texture;
 
-        const axis_limit = this.#axis_limit();
-
-        assert.lessThanOrEqual(slots_x, axis_limit, `slots_x ${slots_x} of ${this.#tile_size} texels exceed maxTextureDimension3D ${device.limits.maxTextureDimension3D}`);
-        assert.lessThanOrEqual(slots_y, axis_limit, `slots_y ${slots_y} of ${this.#tile_size} texels exceed maxTextureDimension3D ${device.limits.maxTextureDimension3D}`);
+        assert.lessThanOrEqual(slots_x, this.#limit_x, `slots_x ${slots_x} of ${tile_x} texels exceed maxTextureDimension3D ${max_dimension}`);
+        assert.lessThanOrEqual(slots_y, this.#limit_y, `slots_y ${slots_y} of ${tile_y} texels exceed maxTextureDimension3D ${max_dimension}`);
 
         const layers = Math.ceil(capacity / (slots_x * slots_y));
 
         // the footprint was declared, so construction does not widen it
-        assert.lessThanOrEqual(layers, axis_limit, `capacity ${capacity} needs ${layers} layers of ${this.#tile_size} texels; the device allows ${axis_limit} (maxTextureDimension3D ${device.limits.maxTextureDimension3D})`);
+        assert.lessThanOrEqual(layers, this.#limit_z, `capacity ${capacity} needs ${layers} layers of ${tile_z} texels; the device allows ${this.#limit_z} (maxTextureDimension3D ${max_dimension})`);
 
         this.#set_layers(layers);
     }
@@ -221,7 +260,8 @@ export class GPUTileAtlas3D {
     }
 
     /**
-     * @returns {number}
+     * Texels of content along x, y and z of a tile. Frozen: the atlas's own, not a copy.
+     * @returns {readonly number[]}
      */
     get content_size() {
         return this.#content_size;
@@ -235,8 +275,9 @@ export class GPUTileAtlas3D {
     }
 
     /**
-     * Texels along each axis of a tile, skirt included.
-     * @returns {number}
+     * Texels along x, y and z of a tile, skirt included: the stride between slots along each axis.
+     * Frozen: the atlas's own, not a copy.
+     * @returns {readonly number[]}
      */
     get tile_size() {
         return this.#tile_size;
@@ -275,15 +316,13 @@ export class GPUTileAtlas3D {
     }
 
     /**
-     * The most slots this atlas can ever hold on this device: as many tiles along each of x, y and z
-     * as fit under `maxTextureDimension3D`, x and y reached by widening. A limit of texture
-     * dimensions, not of memory — a device may refuse the texture long before.
+     * The most slots this atlas can ever hold on this device: along each of x, y and z, as many
+     * tiles of that axis's length as fit under `maxTextureDimension3D`, x and y reached by widening.
+     * A limit of texture dimensions, not of memory — a device may refuse the texture long before.
      * @returns {number}
      */
     get capacity_limit() {
-        const axis_limit = this.#axis_limit();
-
-        return axis_limit * axis_limit * axis_limit;
+        return this.#limit_x * this.#limit_y * this.#limit_z;
     }
 
     /**
@@ -339,7 +378,8 @@ export class GPUTileAtlas3D {
 
     /**
      * Texel origin of a slot's tile — the corner of its skirt, not of its content — under the
-     * footprint as it is now.
+     * footprint as it is now: the slot's grid cell times {@link tile_size}, per axis.
+     * `chunk_tile_atlas_slot_origin` is the same placement on the device.
      *
      * @param {number} slot
      * @param {number[]|Uint32Array} out receives x, y, z
@@ -349,13 +389,13 @@ export class GPUTileAtlas3D {
         assert.isNonNegativeInteger(slot, 'slot');
         assert.lessThan(slot, this.capacity, 'slot is past the atlas');
 
-        const t = this.#tile_size;
+        const tile = this.#tile_size;
 
         tile_atlas_slot_cell(slot, this.#slots_x, this.#slots_y, out);
 
-        out[0] *= t;
-        out[1] *= t;
-        out[2] *= t;
+        out[0] *= tile[0];
+        out[1] *= tile[1];
+        out[2] *= tile[2];
 
         return out;
     }
@@ -365,7 +405,8 @@ export class GPUTileAtlas3D {
      * one `writeTexture`.
      *
      * @param {number} slot a live slot
-     * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest, then y, then z
+     * @param {Uint8Array} content `content_size[0] · content_size[1] · content_size[2] ·
+     * bytes_per_texel` bytes, x fastest, then y, then z
      */
     write(slot, content) {
         assert.ok(this.is_live(slot), `slot ${slot} is not allocated`);
@@ -374,10 +415,14 @@ export class GPUTileAtlas3D {
         const n = this.#content_size;
         const bpt = this.#bytes_per_texel;
 
-        assert.equal(content.length, n * n * n * bpt, `content holds ${content.length} bytes; a tile's content is ${n}³ texels of ${bpt} bytes`);
+        assert.equal(content.length, n[0] * n[1] * n[2] * bpt, `content holds ${content.length} bytes; a tile's content is ${n[0]}×${n[1]}×${n[2]} texels of ${bpt} bytes`);
+
+        const tile = this.#tile_size;
+        const tx = tile[0];
+        const ty = tile[1];
+        const tz = tile[2];
 
-        const t = this.#tile_size;
-        const block = tile_atlas_bordered_block(content, n, this.#border, bpt, new Uint8Array(t * t * t * bpt));
+        const block = tile_atlas_bordered_block(content, n, this.#border, bpt, new Uint8Array(tx * ty * tz * bpt));
 
         this.#device.queue.writeTexture(
             {
@@ -388,24 +433,24 @@ export class GPUTileAtlas3D {
             block,
             {
                 offset: 0,
-                bytesPerRow: t * bpt,
-                rowsPerImage: t,
+                bytesPerRow: tx * bpt,
+                rowsPerImage: ty,
             },
-            [t, t, t]
+            [tx, ty, tz]
         );
     }
 
     /**
      * Put a whole tile, skirt included, into a slot from a buffer on the device — the way a compute
-     * bake lands: it writes the `tile_size³` block into a storage buffer, rows padded to the copy
+     * bake lands: it writes the `tile_size` block into a storage buffer, rows padded to the copy
      * alignment, and this copies it across in the same command stream.
      *
      * @param {GPUCommandEncoder} encoder
      * @param {number} slot a live slot
      * @param {GPUBuffer} buffer
      * @param {number} byte_offset where the block starts in the buffer
-     * @param {number} bytes_per_row stride of a row of `tile_size` texels, a multiple of
-     * `COPY_BYTES_PER_ROW_ALIGNMENT`; rows per image is the tile size
+     * @param {number} bytes_per_row stride of a row of `tile_size[0]` texels, a multiple of
+     * `COPY_BYTES_PER_ROW_ALIGNMENT`; rows per image is `tile_size[1]`
      */
     copy_from_buffer(encoder, slot, buffer, byte_offset, bytes_per_row) {
         assert.defined(encoder, 'encoder');
@@ -413,23 +458,27 @@ export class GPUTileAtlas3D {
         assert.defined(buffer, 'buffer');
         assert.isNonNegativeInteger(byte_offset, 'byte_offset');
         assert.isNonNegativeInteger(bytes_per_row, 'bytes_per_row');
-        assert.greaterThanOrEqual(bytes_per_row, this.#tile_size * this.#bytes_per_texel, 'bytes_per_row is shorter than a row of the tile');
 
-        const t = this.#tile_size;
+        const tile = this.#tile_size;
+        const tx = tile[0];
+        const ty = tile[1];
+        const tz = tile[2];
+
+        assert.greaterThanOrEqual(bytes_per_row, tx * this.#bytes_per_texel, 'bytes_per_row is shorter than a row of the tile');
 
         encoder.copyBufferToTexture(
             {
                 buffer,
                 offset: byte_offset,
                 bytesPerRow: bytes_per_row,
-                rowsPerImage: t,
+                rowsPerImage: ty,
             },
             {
                 texture: this.#texture.gpu_texture,
                 mipLevel: 0,
                 origin: this.slot_origin(slot, [0, 0, 0]),
             },
-            [t, t, t]
+            [tx, ty, tz]
         );
     }
 
@@ -437,19 +486,11 @@ export class GPUTileAtlas3D {
         this.#texture.destroy();
     }
 
-    /**
-     * Tiles that fit along any one axis: a 3-D texture has the same limit on all three.
-     * @returns {number}
-     */
-    #axis_limit() {
-        return Math.floor(this.#device.limits.maxTextureDimension3D / this.#tile_size);
-    }
-
     /**
      * Room for one more slot: a layer while z has room for one, a widen once it does not.
      */
     #grow() {
-        if (this.#slots_z < this.#axis_limit()) {
+        if (this.#slots_z < this.#limit_z) {
             this.#set_layers(this.#slots_z + 1);
         } else {
             this.#widen();
@@ -462,13 +503,13 @@ export class GPUTileAtlas3D {
      * @param {number} layers
      */
     #set_layers(layers) {
-        const t = this.#tile_size;
+        const tile = this.#tile_size;
 
         this.#slots_z = layers;
         this.#resize_live();
 
         // preserve: a new layer keeps every tile where it was, because x and y do not change
-        this.#texture.resize(this.#slots_x * t, this.#slots_y * t, layers * t, true);
+        this.#texture.resize(this.#slots_x * tile[0], this.#slots_y * tile[1], layers * tile[2], true);
     }
 
     /**
@@ -480,9 +521,14 @@ export class GPUTileAtlas3D {
         const sy = this.#slots_y;
         const footprint = [sx, sy];
 
-        const widened = tile_atlas_widened_footprint(sx, sy, this.#axis_limit(), footprint);
+        const tile = this.#tile_size;
+        const tx = tile[0];
+        const ty = tile[1];
+        const tz = tile[2];
 
-        assert.ok(widened, `${this.#label}: full at ${this.capacity} slots — ${sx}×${sy}×${this.#slots_z} tiles of ${this.#tile_size} texels reach maxTextureDimension3D ${this.#device.limits.maxTextureDimension3D} on every axis`);
+        const widened = tile_atlas_widened_footprint(sx, sy, tx, ty, this.#device.limits.maxTextureDimension3D, footprint);
+
+        assert.ok(widened, `${this.#label}: full at ${this.capacity} slots — ${sx}×${sy}×${this.#slots_z} tiles of ${tx}×${ty}×${tz} texels reach maxTextureDimension3D ${this.#device.limits.maxTextureDimension3D} on every axis`);
 
         const nx = footprint[0];
         const ny = footprint[1];
@@ -493,11 +539,10 @@ export class GPUTileAtlas3D {
 
         const device = this.#device;
         const texture = this.#texture;
-        const t = this.#tile_size;
 
         const source = texture.gpu_texture;
 
-        texture.descriptor.size = [nx * t, ny * t, layers * t];
+        texture.descriptor.size = [nx * tx, ny * ty, layers * tz];
 
         const destination = device.createTexture(texture.descriptor);
 
@@ -521,14 +566,14 @@ export class GPUTileAtlas3D {
                 {
                     texture: source,
                     mipLevel: 0,
-                    origin: [from[0] * t, from[1] * t, from[2] * t],
+                    origin: [from[0] * tx, from[1] * ty, from[2] * tz],
                 },
                 {
                     texture: destination,
                     mipLevel: 0,
-                    origin: [to[0] * t, to[1] * t, to[2] * t],
+                    origin: [to[0] * tx, to[1] * ty, to[2] * tz],
                 },
-                [run * t, t, t]
+                [run * tx, ty, tz]
             );
 
             slot += run;
@@ -583,82 +628,113 @@ export function tile_atlas_slot_cell(slot, slots_x, slots_y, out) {
 }
 
 /**
- * The footprint a full atlas widens to: the smaller of x and y doubles, x on a tie, capped at
- * `axis_limit`. The smaller side reaches the limit only when both have, which is when the atlas is
- * full.
+ * The footprint a full atlas widens to: the side narrower in texels doubles, x on a tie, each side
+ * capped at as many tiles of its own length as fit under `max_dimension`. A side already at its
+ * limit leaves the doubling to the other, and the footprint is full only when both are.
+ *
+ * Texels, not tiles, decide which side is narrower: the device's limit is in texels on every axis,
+ * so keeping the layer near square in texels keeps both sides short of it for longer. With a cubic
+ * tile the two counts agree.
  *
  * @param {number} slots_x
  * @param {number} slots_y
- * @param {number} axis_limit tiles that fit along an axis
+ * @param {number} tile_size_x texels along x of a tile
+ * @param {number} tile_size_y texels along y of a tile
+ * @param {number} max_dimension the device's `maxTextureDimension3D`
  * @param {number[]} out receives the new slots_x, slots_y
- * @returns {boolean} false when both sides are at the limit, and nothing can widen
+ * @returns {boolean} false when both sides are at their limits, and nothing can widen
  */
-export function tile_atlas_widened_footprint(slots_x, slots_y, axis_limit, out) {
+export function tile_atlas_widened_footprint(slots_x, slots_y, tile_size_x, tile_size_y, max_dimension, out) {
     assert.isNonNegativeInteger(slots_x, 'slots_x');
     assert.isNonNegativeInteger(slots_y, 'slots_y');
-    assert.isNonNegativeInteger(axis_limit, 'axis_limit');
-    assert.lessThanOrEqual(slots_x, axis_limit, 'slots_x');
-    assert.lessThanOrEqual(slots_y, axis_limit, 'slots_y');
+    assert.isPositiveInteger(tile_size_x, 'tile_size_x');
+    assert.isPositiveInteger(tile_size_y, 'tile_size_y');
+    assert.isNonNegativeInteger(max_dimension, 'max_dimension');
+
+    const limit_x = Math.floor(max_dimension / tile_size_x);
+    const limit_y = Math.floor(max_dimension / tile_size_y);
+
+    assert.lessThanOrEqual(slots_x, limit_x, 'slots_x');
+    assert.lessThanOrEqual(slots_y, limit_y, 'slots_y');
 
     out[0] = slots_x;
     out[1] = slots_y;
 
-    if (slots_x <= slots_y) {
-        if (slots_x === axis_limit) {
-            return false;
-        }
+    const x_has_room = slots_x < limit_x;
+    const y_has_room = slots_y < limit_y;
+
+    const x_is_narrower = slots_x * tile_size_x <= slots_y * tile_size_y;
+
+    if (x_has_room && (x_is_narrower || !y_has_room)) {
+        out[0] = Math.min(2 * slots_x, limit_x);
 
-        out[0] = Math.min(2 * slots_x, axis_limit);
-    } else {
-        out[1] = Math.min(2 * slots_y, axis_limit);
+        return true;
     }
 
-    return true;
+    if (y_has_room) {
+        out[1] = Math.min(2 * slots_y, limit_y);
+
+        return true;
+    }
+
+    return false;
 }
 
 /**
  * A tile's full block from its content: the content in the middle, and around it a skirt of
- * `border` texels holding the content's opposite edge, so the block tiles with itself under a
- * linear filter.
+ * `border` texels holding the content's opposite edge along each axis, so the block tiles with
+ * itself under a linear filter.
  *
  * Pure, and the one place the wrap is defined — a device-side producer has to agree with it.
  *
- * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest
- * @param {number} content_size
- * @param {number} border at most `content_size`
+ * @param {Uint8Array} content `content_size[0] · content_size[1] · content_size[2] ·
+ * bytes_per_texel` bytes, x fastest
+ * @param {ArrayLike<number>} content_size texels of content along x, y and z
+ * @param {number} border at most the shortest axis of `content_size`
  * @param {number} bytes_per_texel
- * @param {Uint8Array} out `(content_size + 2·border)³ · bytes_per_texel` bytes, x fastest
+ * @param {Uint8Array} out `(content_size[0] + 2·border) · (content_size[1] + 2·border) ·
+ * (content_size[2] + 2·border) · bytes_per_texel` bytes, x fastest
  * @returns {Uint8Array} out
  */
 export function tile_atlas_bordered_block(content, content_size, border, bytes_per_texel, out) {
     assert.isInstanceOf(content, Uint8Array, 'content');
     assert.isInstanceOf(out, Uint8Array, 'out');
-    assert.isNonNegativeInteger(content_size, 'content_size');
+    assert.isArrayLike(content_size, 'content_size');
+    assert.equal(content_size.length, 3, 'content_size is texels along x, y and z');
     assert.isNonNegativeInteger(border, 'border');
-    assert.lessThanOrEqual(border, content_size, 'border');
     assert.isNonNegativeInteger(bytes_per_texel, 'bytes_per_texel');
 
-    const n = content_size;
-    const t = n + 2 * border;
+    const nx = content_size[0];
+    const ny = content_size[1];
+    const nz = content_size[2];
+
+    assert.isPositiveInteger(nx, 'content_size[0]');
+    assert.isPositiveInteger(ny, 'content_size[1]');
+    assert.isPositiveInteger(nz, 'content_size[2]');
+    assert.lessThanOrEqual(border, Math.min(nx, ny, nz), 'border');
+
+    const tx = nx + 2 * border;
+    const ty = ny + 2 * border;
+    const tz = nz + 2 * border;
 
-    assert.equal(content.length, n * n * n * bytes_per_texel, 'content length');
-    assert.equal(out.length, t * t * t * bytes_per_texel, 'out length');
+    assert.equal(content.length, nx * ny * nz * bytes_per_texel, 'content length');
+    assert.equal(out.length, tx * ty * tz * bytes_per_texel, 'out length');
 
-    for (let tz = 0; tz < t; tz++) {
-        // (tz - border) mod n, kept non-negative: border <= n, so one n is enough
-        const cz = (tz - border + n) % n;
+    for (let bz = 0; bz < tz; bz++) {
+        // (bz - border) mod nz, kept non-negative: border <= nz, so one nz is enough
+        const cz = (bz - border + nz) % nz;
 
-        for (let ty = 0; ty < t; ty++) {
-            const cy = (ty - border + n) % n;
+        for (let by = 0; by < ty; by++) {
+            const cy = (by - border + ny) % ny;
 
-            const row_out = (tz * t + ty) * t;
-            const row_in = (cz * n + cy) * n;
+            const row_out = (bz * ty + by) * tx;
+            const row_in = (cz * ny + cy) * nx;
 
-            for (let tx = 0; tx < t; tx++) {
-                const cx = (tx - border + n) % n;
+            for (let bx = 0; bx < tx; bx++) {
+                const cx = (bx - border + nx) % nx;
 
                 const src = (row_in + cx) * bytes_per_texel;
-                const dst = (row_out + tx) * bytes_per_texel;
+                const dst = (row_out + bx) * bytes_per_texel;
 
                 for (let b = 0; b < bytes_per_texel; b++) {
                     out[dst + b] = content[src + b];

package/src/shade/renderer/texture/atlas/chunk_tile_atlas_slot_origin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Texel origin of a slot's tile in a {@link GPUTileAtlas3D} — the corner of its skirt, not of its
+ * content — on the device: the WGSL twin of `GPUTileAtlas3D.slot_origin`, and the one place a
+ * shader finds a slot.
+ *
+ * Slot `s` sits at grid cell `index_to_grid3d(s, slots)`, x fastest and z slowest, and a cell is one
+ * tile along each axis, so the origin is the cell times `tile_size`, per axis.
+ *
+ * The footprint is the caller's to supply, as tiles along x and y: a shader that knows the tile
+ * size takes it from the texture itself, `textureDimensions(atlas).xy / tile_size.xy`, which is
+ * always the footprint the bound texture was built with; one that does not takes the atlas's
+ * `slots_x` and `slots_y` from a uniform the host refreshes after its last `allocate`. z is not an
+ * argument: the layer is whatever the slot index reaches.
+ *
+ * @see GPUTileAtlas3D
+ * @type {CodeChunk}
+ */
+export const chunk_tile_atlas_slot_origin: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_tile_atlas_slot_origin.d.ts.map

package/src/shade/renderer/texture/atlas/chunk_tile_atlas_slot_origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_tile_atlas_slot_origin.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/chunk_tile_atlas_slot_origin.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,2CAFU,SAAS,CAWjB;0BA5BwB,oCAAoC"}

package/src/shade/renderer/texture/atlas/chunk_tile_atlas_slot_origin.js

@@ -0,0 +1,30 @@
+import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Texel origin of a slot's tile in a {@link GPUTileAtlas3D} — the corner of its skirt, not of its
+ * content — on the device: the WGSL twin of `GPUTileAtlas3D.slot_origin`, and the one place a
+ * shader finds a slot.
+ *
+ * Slot `s` sits at grid cell `index_to_grid3d(s, slots)`, x fastest and z slowest, and a cell is one
+ * tile along each axis, so the origin is the cell times `tile_size`, per axis.
+ *
+ * The footprint is the caller's to supply, as tiles along x and y: a shader that knows the tile
+ * size takes it from the texture itself, `textureDimensions(atlas).xy / tile_size.xy`, which is
+ * always the footprint the bound texture was built with; one that does not takes the atlas's
+ * `slots_x` and `slots_y` from a uniform the host refreshes after its last `allocate`. z is not an
+ * argument: the layer is whatever the slot index reaches.
+ *
+ * @see GPUTileAtlas3D
+ * @type {CodeChunk}
+ */
+export const chunk_tile_atlas_slot_origin = CodeChunk.from(
+    //language=WGSL
+    `
+fn tile_atlas_slot_origin(slot: u32, slots: vec2<u32>, tile_size: vec3<u32>) -> vec3<u32> {
+    return index_to_grid3d(slot, slots) * tile_size;
+}
+`, [
+        chunk_index_to_grid3d,
+    ]
+);

package/src/shade/renderer/texture/draw_texture_as_rgba.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Draw a 2-D texture as RGBA. One slice of a 3-D texture is drawn by
+ * {@link graph_draw_texture_3d_slice_as_rgba} instead.
  *
  * @param {Object} options
  * @param {FrameGraph} options.graph

package/src/shade/renderer/texture/draw_texture_as_rgba.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"draw_texture_as_rgba.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/draw_texture_as_rgba.js"],"names":[],"mappings":"AAkFA;;;;;;;;;GASG;AACH;IAP+B,KAAK;IACS,MAAM,EAAxC,MAAM,oBAAkB;IACN,UAAU,EAA5B,MAAM,EAAE;IACS,cAAc,GAA/B,MAAM;IACoB,YAAY;IACpC,MAAM,CA4DlB;AAGD;;;;;;;;GAQG;AACH;IANsC,OAAO;IACd,MAAM;IACT,cAAc,GAA/B,MAAM;IACc,MAAM;IACD,QAAQ;SAyJ3C"}
+{"version":3,"file":"draw_texture_as_rgba.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/draw_texture_as_rgba.js"],"names":[],"mappings":"AAkFA;;;;;;;;;;;GAWG;AACH;IAP+B,KAAK;IACS,MAAM,EAAxC,MAAM,oBAAkB;IACN,UAAU,EAA5B,MAAM,EAAE;IACS,cAAc,GAA/B,MAAM;IACoB,YAAY;IACpC,MAAM,CA4DlB;AAGD;;;;;;;;GAQG;AACH;IANsC,OAAO;IACd,MAAM;IACT,cAAc,GAA/B,MAAM;IACc,MAAM;IACD,QAAQ;SAyJ3C"}