@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/shadow/vsm/VSMPageManager.js

@@ -1,5 +1,7 @@
 import { assert } from "../../../../core/assert.js";
 import { IndexedFloatMaxHeap } from "../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { ClipmapWindowSet } from "../../../../core/geom/clipmap/ClipmapWindowSet.js";
+import { window_scroll_regions } from "../../../../core/geom/clipmap/window_scroll_regions.js";
 import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 import { VT_ENTRY_INVALID, VT_ENTRY_PHYS_MASK, vt_entry_pack } from "../../texture/virtual/VT_CONSTANTS.js";
 import { VTPhysicalSlots } from "../../texture/virtual/VTPhysicalSlots.js";
@@ -105,7 +107,8 @@ function candidate_score(kind, importance, waited) {
  * world units on a side, anchored to the world in light space. Each level keeps a window of
  * `pages_per_level²` pages around the camera ({@link update_windows}), and a page of the window sits
  * in cell `(x mod N, y mod N)` of the level — so a window that scrolls keeps every page still inside
- * it where it was, and gives back only the pages it left behind.
+ * it where it was, and gives back only the pages it left behind. The windows are a 2-D
+ * {@link ClipmapWindowSet}, and what a scroll leaves behind is {@link window_scroll_regions}'.
  *
  * **The pool** is a {@link VTPhysicalSlots}: VT's slot grid, least-recently-touched eviction outside
  * a protection window, and the finest page shed first on a tie.
@@ -231,21 +234,18 @@ export class VSMPageManager {
     #select_index = 0;
 
     /**
-     * Per level, the window's corner in world pages.
-     * @type {Int32Array}
-     */
-    #origin_x;
-
-    /**
-     * @type {Int32Array}
+     * Per level, the window: its corner in world pages, and whether {@link update_windows} has
+     * placed it yet.
+     * @type {ClipmapWindowSet}
      */
-    #origin_y;
+    #windows;
 
     /**
-     * Whether {@link update_windows} has placed the windows yet.
-     * @type {boolean}
+     * A scrolling window's corners, before and after, and the boxes of pages it leaves behind.
      */
-    #windows_placed = false;
+    #scroll_old = new Int32Array(2);
+    #scroll_new = new Int32Array(2);
+    #scroll_boxes = new Int32Array(8);
 
     /**
      * The want set: the latest reading's requests, in its order.
@@ -401,8 +401,14 @@ export class VSMPageManager {
         this.#slot_rendered = new Float64Array(capacity).fill(-1);
         this.#slot_stale_since = new Float64Array(capacity);
 
-        this.#origin_x = new Int32Array(level_count);
-        this.#origin_y = new Int32Array(level_count);
+        // moved a whole page at a time, and only when the camera crosses into another page
+        this.#windows = new ClipmapWindowSet({
+            level_count,
+            dimensions: 2,
+            size: [pages_per_level, pages_per_level],
+            step: 1,
+            hysteresis: 0,
+        });
 
         this.#want_level = new Uint8Array(request_capacity);
         this.#want_x = new Int32Array(request_capacity);
@@ -449,7 +455,8 @@ export class VSMPageManager {
     }
 
     /**
-     * The page-table row, from the map's first, of a world page's cell.
+     * The page-table row, from the map's first, of a world page's cell: the window set's
+     * {@link ClipmapWindowSet#storage_cell}, with the window's power-of-two side taken as a mask.
      *
      * @param {number} level
      * @param {number} x world page
@@ -468,7 +475,7 @@ export class VSMPageManager {
      * @returns {number} the level's window corner, world pages
      */
     origin_x(level) {
-        return this.#origin_x[level];
+        return this.#windows.corner(level, 0);
     }
 
     /**
@@ -476,21 +483,17 @@ export class VSMPageManager {
      * @returns {number}
      */
     origin_y(level) {
-        return this.#origin_y[level];
+        return this.#windows.corner(level, 1);
     }
 
     /**
      * @param {number} level
      * @param {number} x
      * @param {number} y
-     * @returns {boolean}
+     * @returns {boolean} whether the level's window is placed and holds the world page
      */
     window_contains(level, x, y) {
-        const n = this.pages_per_level;
-        const rx = x - this.#origin_x[level];
-        const ry = y - this.#origin_y[level];
-
-        return this.#windows_placed && rx >= 0 && ry >= 0 && rx < n && ry < n;
+        return this.#windows.contains(level, x, y);
     }
 
     /**
@@ -519,97 +522,93 @@ export class VSMPageManager {
         assert.isFinite(light_x, 'light_x');
         assert.isFinite(light_y, 'light_y');
 
-        const half = this.pages_per_level >> 1;
+        const windows = this.#windows;
+        const old_corner = this.#scroll_old;
 
         for (let level = 0; level < this.level_count; level++) {
             const size = this.page_world_size(level);
+            const placed = windows.placed(level);
 
-            const x = Math.floor(light_x / size) - half;
-            const y = Math.floor(light_y / size) - half;
+            old_corner[0] = windows.corner(level, 0);
+            old_corner[1] = windows.corner(level, 1);
 
-            const old_x = this.#origin_x[level];
-            const old_y = this.#origin_y[level];
-
-            if (this.#windows_placed) {
-                if (x === old_x && y === old_y) {
-                    continue;
-                }
+            // the camera's page, which the window keeps in its middle cell: a whole page, so the
+            // window moves exactly when the camera crosses into another page
+            if (!windows.place(level, Math.floor(light_x / size), Math.floor(light_y / size))) {
+                continue;
+            }
 
-                this.#evict_vacated(level, old_x, old_y, x, y);
+            if (placed) {
+                this.#evict_vacated(level, old_corner);
             }
 
-            this.#origin_x[level] = x;
-            this.#origin_y[level] = y;
             this.#levels_dirty = true;
         }
-
-        this.#windows_placed = true;
     }
 
     /**
-     * Give back every resident page of a level that its window, moving from one corner to the other,
-     * leaves behind. Walks the strips it vacates, or the whole level when it jumps a window or more.
+     * Give back every resident page of a level that its window, having moved from `old_corner`,
+     * left behind: the strips it vacated, or the whole level when it jumped a window or more.
+     *
+     * The order is part of the behaviour: the pool takes back first the slot it was given back last,
+     * so the order pages go back in decides the slots later pages land in. The columns left go a
+     * column at a time, then the rows left a row at a time, and a jump goes in page-table order.
      *
      * @param {number} level
-     * @param {number} old_x
-     * @param {number} old_y
-     * @param {number} new_x
-     * @param {number} new_y
+     * @param {Int32Array} old_corner
      */
-    #evict_vacated(level, old_x, old_y, new_x, new_y) {
+    #evict_vacated(level, old_corner) {
+        const windows = this.#windows;
+        const new_corner = this.#scroll_new;
+        const boxes = this.#scroll_boxes;
         const n = this.pages_per_level;
 
-        if (Math.abs(new_x - old_x) >= n || Math.abs(new_y - old_y) >= n) {
-            const first = level * n * n;
-
-            for (let cell = first; cell < first + n * n; cell++) {
-                const slot = this.#cell_slot[cell];
-
-                if (slot !== -1) {
-                    this.#evict(slot);
-                    this.stats.scroll_evictions++;
-                }
-            }
-
-            return;
-        }
+        new_corner[0] = windows.corner(level, 0);
+        new_corner[1] = windows.corner(level, 1);
 
-        // the columns of the old window outside the new one, all rows
-        const keep_x0 = Math.max(old_x, new_x);
-        const keep_x1 = Math.min(old_x, new_x) + n;
+        // the pages the window left are the ones a move the other way would expose: a box of the
+        // columns left over every row, then one of the rows left over the columns kept, or the
+        // whole old window
+        const count = window_scroll_regions(new_corner, old_corner, windows.size, 2, boxes);
 
-        for (let x = old_x; x < old_x + n; x++) {
-            if (x >= keep_x0 && x < keep_x1) {
-                continue;
-            }
+        for (let b = 0; b < count; b++) {
+            const box = b * 4;
 
-            for (let y = old_y; y < old_y + n; y++) {
-                this.#evict_page_for_scroll(level, x, y);
-            }
-        }
-
-        // then the rows outside it, over the columns both windows share
-        const keep_y0 = Math.max(old_y, new_y);
-        const keep_y1 = Math.min(old_y, new_y) + n;
+            const x0 = boxes[box];
+            const y0 = boxes[box + 1];
+            const x1 = boxes[box + 2];
+            const y1 = boxes[box + 3];
 
-        for (let y = old_y; y < old_y + n; y++) {
-            if (y >= keep_y0 && y < keep_y1) {
-                continue;
-            }
+            if (x1 - x0 === n && y1 - y0 === n) {
+                // the whole level, in page-table order
+                const first = level * n * n;
 
-            for (let x = keep_x0; x < keep_x1; x++) {
-                this.#evict_page_for_scroll(level, x, y);
+                for (let cell = first; cell < first + n * n; cell++) {
+                    this.#evict_cell_for_scroll(cell);
+                }
+            } else if (y1 - y0 === n) {
+                // the columns left, every row of each
+                for (let x = x0; x < x1; x++) {
+                    for (let y = y0; y < y1; y++) {
+                        this.#evict_cell_for_scroll(this.cell_of(level, x, y));
+                    }
+                }
+            } else {
+                // the rows left, over the columns kept
+                for (let y = y0; y < y1; y++) {
+                    for (let x = x0; x < x1; x++) {
+                        this.#evict_cell_for_scroll(this.cell_of(level, x, y));
+                    }
+                }
             }
         }
     }
 
     /**
-     * @param {number} level
-     * @param {number} x
-     * @param {number} y
+     * @param {number} cell
      */
-    #evict_page_for_scroll(level, x, y) {
-        const slot = this.#cell_slot[this.cell_of(level, x, y)];
+    #evict_cell_for_scroll(cell) {
+        const slot = this.#cell_slot[cell];
 
         if (slot === -1) {
             return;
@@ -1081,10 +1080,8 @@ export class VSMPageManager {
             const cell_y = (local / n) | 0;
 
             // the window's page in that cell
-            const origin_x = this.#origin_x[level];
-            const origin_y = this.#origin_y[level];
-            const x = origin_x + ((cell_x - origin_x) & mask);
-            const y = origin_y + ((cell_y - origin_y) & mask);
+            const x = this.#windows.decode(level, 0, cell_x);
+            const y = this.#windows.decode(level, 1, cell_y);
 
             const claimed = pool_exhausted ? -1 : this.#claim_slot(frame, level);
 

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAuHI;;;;;;;;;;;OAWG;IACH;QAV2B,WAAW,EAA3B,MAAM;QACU,eAAe,EAA/B,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,cAAc,EAA9B,MAAM;QACU,YAAY,EAA5B,MAAM;OA8BhB;IA7JD;;;OAGG;IACH,kBAHU,cAAc,CAGhB;IAER;;;;OAIG;IACH,uBAHU,MAAM,CAGH;IAEb;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IACjB,mBAAgB;IAChB,mBAAgB;IAEhB;;;;;;OAMG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,oBAAgB;IAChB,iBAAa;IACb,oBAAgB;IAEhB;;;;;OAKG;IACH,aAFU,YAAU,IAAI,CAEL;IAEnB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,cAFU,kBAAkB,CAEY;IAExC;;;OAGG;IACH,MAFU,MAAM,CAEP;IACT,YAAQ;IAmFR;;;OAGG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,8DA2DC;IAED;;;OAGG;IACH,eAFa;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAM/E;IAED;;;OAGG;IACH,uBAFa,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,wBALW,kBAAkB,SAClB,MAAM,KACN,MAAM,KACN,MAAM,QAiBhB;IAYL;;;OAGG;IACH,6BAFU,OAAO,CAE4B;;CAN5C;0BArUyB,qBAAqB;+BAChB,qBAAqB;mCAFjB,oCAAoC"}
+{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH;IAwHI;;;;;;;;;;;OAWG;IACH;QAV2B,WAAW,EAA3B,MAAM;QACU,eAAe,EAA/B,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,cAAc,EAA9B,MAAM;QACU,YAAY,EAA5B,MAAM;OA8BhB;IA9JD;;;OAGG;IACH,kBAHU,cAAc,CAGhB;IAER;;;;OAIG;IACH,uBAHU,MAAM,CAGH;IAEb;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IACjB,mBAAgB;IAChB,mBAAgB;IAEhB;;;;;;OAMG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,oBAAgB;IAChB,iBAAa;IACb,oBAAgB;IAEhB;;;;;OAKG;IACH,aAFU,YAAU,IAAI,CAEL;IAEnB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,cAFU,kBAAkB,CAEY;IAExC;;;OAGG;IACH,MAFU,MAAM,CAEP;IACT,YAAQ;IAoFR;;;OAGG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,8DA4DC;IAED;;;OAGG;IACH,eAFa;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAM/E;IAED;;;OAGG;IACH,uBAFa,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,wBALW,kBAAkB,SAClB,MAAM,KACN,MAAM,KACN,MAAM,QAiBhB;IAYL;;;OAGG;IACH,6BAFU,OAAO,CAE4B;;CAN5C;0BAvUyB,qBAAqB;+BAChB,qBAAqB;mCAFjB,oCAAoC"}

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { quantize_hysteretic } from "../../../../core/geom/clipmap/quantize_hysteretic.js";
 import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
 import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
 import { Shadowmap } from "../map/Shadowmap.js";
@@ -99,9 +100,10 @@ export class VirtualShadowMap extends Shadowmap {
     far = 0;
 
     /**
-     * Where the depth range is centred, along the light; set by the first {@link update}.
+     * Where the depth range is centred, along the light, in steps of a quarter of
+     * {@link depth_extent}; set by the first {@link update}.
      */
-    #depth_centre = 0;
+    #depth_index = 0;
     #depth_centred = false;
 
     /**
@@ -219,16 +221,17 @@ export class VirtualShadowMap extends Shadowmap {
 
         // snapped, so the range moves — and every page with it — only when the camera has gone a
         // quarter of it along the light from where the range is centred: a camera standing on the
-        // plane between two snaps does not move it back and forth
+        // plane between two snaps does not move it back and forth. Half a step of hysteresis on
+        // top of the half step makes that threshold a whole step.
         const snap = this.depth_extent / 4;
 
-        if (!this.#depth_centred || Math.abs(light_depth - this.#depth_centre) > snap) {
-            this.#depth_centre = Math.round(light_depth / snap) * snap;
-            this.#depth_centred = true;
-        }
+        this.#depth_index = quantize_hysteretic(light_depth, this.#depth_index, snap, snap * 0.5, this.#depth_centred);
+        this.#depth_centred = true;
+
+        const depth_centre = this.#depth_index * snap;
 
-        this.near = this.#depth_centre - this.depth_extent;
-        this.far = this.#depth_centre + this.depth_extent;
+        this.near = depth_centre - this.depth_extent;
+        this.far = depth_centre + this.depth_extent;
 
         const manager = this.manager;
         const frame = ++this.frame_index;

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.d.ts

@@ -1,7 +1,7 @@
 /**
  * Append a lane's mover to the scene's mover list — `movers`, a `VSMMovers` the including shader
- * binds read-write — one atomic per subgroup: the subgroup counts its movers, its first lane
- * reserves that many entries, and each mover takes its place by its exclusive prefix.
+ * binds read-write — through {@link chunk_subgroup_append_slot}: one atomic per subgroup, and the
+ * mover's box written into the slot it was given.
  *
  * Every lane of the subgroup must call it, mover or not, from uniform control flow. Past `capacity`
  * the count still rises — that is how the stale pass knows the list overflowed — but nothing is

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_vsm_append_mover.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CA8BjB;0BA1CwB,uCAAuC"}
+{"version":3,"file":"chunk_vsm_append_mover.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CAgBjB;0BA3BwB,uCAAuC"}

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.js

@@ -1,10 +1,13 @@
+import {
+    chunk_subgroup_append_slot,
+    SUBGROUP_APPEND_NONE
+} from "../../../shader/chunk/subgroup/chunk_subgroup_append_slot.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
 
 /**
  * Append a lane's mover to the scene's mover list — `movers`, a `VSMMovers` the including shader
- * binds read-write — one atomic per subgroup: the subgroup counts its movers, its first lane
- * reserves that many entries, and each mover takes its place by its exclusive prefix.
+ * binds read-write — through {@link chunk_subgroup_append_slot}: one atomic per subgroup, and the
+ * mover's box written into the slot it was given.
  *
  * Every lane of the subgroup must call it, mover or not, from uniform control flow. Past `capacity`
  * the count still rises — that is how the stale pass knows the list overflowed — but nothing is
@@ -16,30 +19,14 @@ export const chunk_vsm_append_mover = CodeChunk.from(
     //language=WGSL
     `
 fn vsm_append_mover(is_mover: bool, box_min: vec3f, box_max: vec3f, capacity: u32) {
-    let want = select(0u, 1u, is_mover);
+    let slot = subgroup_append_slot(&movers.count, is_mover, capacity);
 
-    let offset = subgroupExclusiveAdd(want);
-    let total = subgroupAdd(want);
-    let elected = subgroupElect();
-
-    var base = 0u;
-
-    if (elected && total > 0u) {
-        base = atomicAdd(&movers.count, total);
-    }
-
-    base = subgroupBroadcastFirst(base);
-
-    if (is_mover) {
-        let index = base + offset;
-
-        if (index < capacity) {
-            movers.boxes[index * 2u] = vec4f(box_min, 0.0);
-            movers.boxes[index * 2u + 1u] = vec4f(box_max, 0.0);
-        }
+    if (slot != ${SUBGROUP_APPEND_NONE}u) {
+        movers.boxes[slot * 2u] = vec4f(box_min, 0.0);
+        movers.boxes[slot * 2u + 1u] = vec4f(box_max, 0.0);
     }
 }
-`
+`, [
+        chunk_subgroup_append_slot,
+    ]
 );
-
-chunk_vsm_append_mover.addExtension(WebGPUExtensionType.Subgroups);

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

@@ -0,0 +1,7 @@
+/**
+ * The linear, clamped sampler most chunks sample through.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SAMPLER_LINEAR_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=SAMPLER_LINEAR_RESOURCE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SAMPLER_LINEAR_RESOURCE.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/SAMPLER_LINEAR_RESOURCE.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,sCAFU,wBAAwB,CAEsF;yCAP/E,gDAAgD"}

package/src/shade/renderer/texture/SAMPLER_LINEAR_RESOURCE.js

@@ -0,0 +1,8 @@
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+import { SAMPLER_LINEAR_UPSCALE } from "./SAMPLER_LINEAR_UPSCALE.js";
+
+/**
+ * The linear, clamped sampler most chunks sample through.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SAMPLER_LINEAR_RESOURCE = ShaderResourceDescriptor.sampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE);

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

@@ -9,58 +9,71 @@
  */
 export function tile_atlas_slot_cell(slot: number, slots_x: number, slots_y: number, out: number[] | Uint32Array): number[] | Uint32Array;
 /**
- * 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: number, slots_y: number, axis_limit: number, out: number[]): boolean;
+export function tile_atlas_widened_footprint(slots_x: number, slots_y: number, tile_size_x: number, tile_size_y: number, max_dimension: number, out: number[]): boolean;
 /**
  * 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: Uint8Array, content_size: number, border: number, bytes_per_texel: number, out: Uint8Array): Uint8Array;
+export function tile_atlas_bordered_block(content: Uint8Array, content_size: ArrayLike<number>, border: number, bytes_per_texel: number, out: Uint8Array): Uint8Array;
 /**
- * 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
@@ -73,8 +86,9 @@ export function tile_atlas_bordered_block(content: Uint8Array, content_size: num
  *
  * 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 {
     /**
@@ -84,9 +98,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
@@ -102,7 +117,7 @@ export class GPUTileAtlas3D {
     constructor({ device, format, content_size, border, slots_x, slots_y, capacity, usage, label }: {
         device: GPUDevice;
         format: GPUTextureFormat;
-        content_size: number;
+        content_size: number[];
         border: number;
         slots_x: number;
         slots_y: number;
@@ -123,18 +138,20 @@ export class GPUTileAtlas3D {
      */
     get bytes_per_texel(): number;
     /**
-     * @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(): number;
+    get content_size(): readonly number[];
     /**
      * @returns {number}
      */
     get border(): number;
     /**
-     * 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(): number;
+    get tile_size(): readonly number[];
     /**
      * Tiles along x now; a widen may double it.
      * @returns {number}
@@ -156,9 +173,9 @@ export class GPUTileAtlas3D {
      */
     get capacity(): number;
     /**
-     * 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(): number;
@@ -184,7 +201,8 @@ export class GPUTileAtlas3D {
     free(slot: number): void;
     /**
      * 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
@@ -196,20 +214,21 @@ 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: number, content: Uint8Array): void;
     /**
      * 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: GPUCommandEncoder, slot: number, buffer: GPUBuffer, byte_offset: number, bytes_per_row: number): void;
     destroy(): void;