@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/shadow/vsm/graph_vsm_feedback.d.ts

@@ -2,12 +2,11 @@
  * Record a frame's virtual shadow map feedback into the `Shading` graph, once the main view's depth
  * exists, and read it back.
  *
- * 1. **Movers**, once for the scene: every mesh row against the box it had last frame, and every
- *    skinned mesh against the pose it had, into one list ({@link shader_vsm_movers},
- *    {@link shader_vsm_skinned_movers}).
- * 2. **Stale**, every frame for every map: the slots under a mover flagged in the map's persistent
- *    flags ({@link shader_vsm_stale}, sized indirectly to the movers).
- * 3. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
+ * 1. **Stale**, every frame for every map: the slots under a mover of the scene's mover list
+ *    ({@link GPUSceneContext#graph_movers}) flagged in the map's persistent flags
+ *    ({@link shader_vsm_stale}, sized indirectly to the movers). A box only animation moved is a mover
+ *    here like any other: a shadow follows the pose.
+ * 2. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
  *    ({@link shader_vsm_demand}) with their pixel counts ({@link shader_vsm_gather_counts}), and the
  *    flagged slots listed and cleared ({@link shader_vsm_stale_compact}) — read back and handed to
  *    the map's {@link VSMPageManager#apply_reading} with the frame they were recorded in.
@@ -17,15 +16,15 @@
  * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the view whose depth asks for pages
  * @param {number} options.depth graph handle of the view's depth
  * @param {VirtualShadowMap[]} options.maps
- * @param {VSMMoverTracker} options.tracker the scene's casters as last seen
+ * @param {number} options.movers graph handle of the scene's mover list this frame
  * @param {GPUDatabase} options.light_database
  */
-export function graph_vsm_feedback({ graph, view, depth, maps, tracker, light_database, }: {
+export function graph_vsm_feedback({ graph, view, depth, maps, movers, light_database, }: {
     graph: FrameGraph;
     view: import("../../view/GPUViewContext.js").GPUViewContext;
     depth: number;
     maps: VirtualShadowMap[];
-    tracker: VSMMoverTracker;
+    movers: number;
     light_database: GPUDatabase;
 }): void;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"graph_vsm_feedback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/graph_vsm_feedback.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAP+B,KAAK;IACsC,IAAI,EAAnE,OAAO,8BAA8B,EAAE,cAAc;IACrC,KAAK,EAArB,MAAM;IACsB,IAAI,EAAhC,kBAAkB;IACO,OAAO;IACX,cAAc;SAsG7C;AAnID;;;;;;GAMG;AACH,sCAFU,MAAM,CAEyB"}
+{"version":3,"file":"graph_vsm_feedback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/graph_vsm_feedback.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAP+B,KAAK;IACsC,IAAI,EAAnE,OAAO,8BAA8B,EAAE,cAAc;IACrC,KAAK,EAArB,MAAM;IACsB,IAAI,EAAhC,kBAAkB;IACF,MAAM,EAAtB,MAAM;IACe,cAAc;SAwB7C;AApDD;;;;;;GAMG;AACH,sCAFU,MAAM,CAEyB"}

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

@@ -1,14 +1,10 @@
 import { assert } from "../../../../core/assert.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
 import { graph_read_buffer } from "../../buffer/graph_read_buffer.js";
-import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
 import { shader_vsm_demand, VSM_DEMAND_WORKGROUP_SIZE } from "./shader/shader_vsm_demand.js";
 import { shader_vsm_gather_counts, VSM_GATHER_WORKGROUP_SIZE } from "./shader/shader_vsm_gather_counts.js";
-import { shader_vsm_movers, VSM_MOVERS_WORKGROUP_SIZE } from "./shader/shader_vsm_movers.js";
-import { shader_vsm_skinned_movers } from "./shader/shader_vsm_skinned_movers.js";
 import { shader_vsm_stale, shader_vsm_stale_args, shader_vsm_stale_compact } from "./shader/shader_vsm_stale.js";
 import { vsm_feedback_word_count } from "./VSM_FEEDBACK_LAYOUT.js";
-import { VSM_MOVER_CAPACITY, VSM_MOVERS_BYTE_SIZE } from "./VSM_MOVER_LAYOUT.js";
 
 /**
  * Readbacks of one map's feedback in flight at most: VT's cap. A frame that would go past it skips
@@ -23,12 +19,11 @@ export const VSM_READBACKS_IN_FLIGHT = 3;
  * Record a frame's virtual shadow map feedback into the `Shading` graph, once the main view's depth
  * exists, and read it back.
  *
- * 1. **Movers**, once for the scene: every mesh row against the box it had last frame, and every
- *    skinned mesh against the pose it had, into one list ({@link shader_vsm_movers},
- *    {@link shader_vsm_skinned_movers}).
- * 2. **Stale**, every frame for every map: the slots under a mover flagged in the map's persistent
- *    flags ({@link shader_vsm_stale}, sized indirectly to the movers).
- * 3. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
+ * 1. **Stale**, every frame for every map: the slots under a mover of the scene's mover list
+ *    ({@link GPUSceneContext#graph_movers}) flagged in the map's persistent flags
+ *    ({@link shader_vsm_stale}, sized indirectly to the movers). A box only animation moved is a mover
+ *    here like any other: a shadow follows the pose.
+ * 2. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
  *    ({@link shader_vsm_demand}) with their pixel counts ({@link shader_vsm_gather_counts}), and the
  *    flagged slots listed and cleared ({@link shader_vsm_stale_compact}) — read back and handed to
  *    the map's {@link VSMPageManager#apply_reading} with the frame they were recorded in.
@@ -38,7 +33,7 @@ export const VSM_READBACKS_IN_FLIGHT = 3;
  * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the view whose depth asks for pages
  * @param {number} options.depth graph handle of the view's depth
  * @param {VirtualShadowMap[]} options.maps
- * @param {VSMMoverTracker} options.tracker the scene's casters as last seen
+ * @param {number} options.movers graph handle of the scene's mover list this frame
  * @param {GPUDatabase} options.light_database
  */
 export function graph_vsm_feedback({
@@ -46,100 +41,22 @@ export function graph_vsm_feedback({
                                        view,
                                        depth,
                                        maps,
-                                       tracker,
+                                       movers,
                                        light_database,
                                    }) {
     assert.defined(graph, 'graph');
     assert.defined(view, 'view');
     assert.isNonNegativeInteger(depth, 'depth');
     assert.isArray(maps, 'maps');
-    assert.defined(tracker, 'tracker');
+    assert.isNonNegativeInteger(movers, 'movers');
 
     if (maps.length === 0) {
         return;
     }
 
-    const scene_ctx = view.scene;
-    const meshes = scene_ctx.scene_database.get('meshes');
-    const elements_per_page = meshes.descriptor.elements_per_page;
-
-    // every row the table has ever had, in whole pages
-    const pages = Math.ceil(Math.max(meshes.element_capacity, tracker.row_count) / elements_per_page);
-
-    tracker.ensure(pages * elements_per_page);
-
-    const row_count = tracker.row_count;
-    const groups_per_page = Math.ceil(elements_per_page / VSM_MOVERS_WORKGROUP_SIZE);
-    const mover_groups = Math.ceil(row_count / elements_per_page) * groups_per_page;
-
-    // folded into rows a dispatch dimension can hold
-    const mover_groups_x = Math.min(mover_groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
-    const mover_groups_y = mover_groups > 0 ? Math.ceil(mover_groups / mover_groups_x) : 0;
-
-    const movers_data = {};
-
-    const movers_pass = graph.add("VSM Movers", movers_data, (data, resources, context) => {
-        const encoder = context.encoder;
-        const movers = resources.get(data.movers);
-
-        // only the count needs to start at zero: an entry is read only below it
-        encoder.clearBuffer(movers, 0, 16);
-
-        tracker.encode_growth(encoder);
-
-        if (mover_groups > 0) {
-            shader_vsm_movers.dispatch({
-                encoder,
-                group_count_x: mover_groups_x,
-                group_count_y: mover_groups_y,
-                bindings: {
-                    settings: {
-                        row_count,
-                        capacity: VSM_MOVER_CAPACITY,
-                        groups_x: mover_groups_x,
-                        group_count: mover_groups,
-                    },
-                    scene_database: scene_ctx.scene_database_buffer,
-                    last_seen: tracker.buffer,
-                    movers,
-                },
-            });
-        }
-
-        const skinning = scene_ctx.skinning;
-        const animation = scene_ctx.animation_manager;
-
-        if (skinning.binding_count > 0 && skinning.bindings_buffer !== null) {
-            // a workgroup per skinned mesh
-            assert.lessThanOrEqual(skinning.binding_count, 65535, 'skinning bindings beyond one dispatch row');
-
-            shader_vsm_skinned_movers.dispatch({
-                encoder,
-                group_count_x: skinning.binding_count,
-                bindings: {
-                    settings: { binding_count: skinning.binding_count, capacity: VSM_MOVER_CAPACITY },
-                    scene_database: scene_ctx.scene_database_buffer,
-                    bindings: skinning.bindings_buffer,
-                    // this frame's pose and last frame's, as the matrix prep left them
-                    skin_matrices: animation.skin_matrices_buffer,
-                    prev_skin_matrices: animation.prev_skin_matrices_buffer,
-                    movers,
-                },
-            });
-        }
-    });
-
-    movers_data.movers = movers_pass.create("vsm_movers", BufferResourceDescriptor.from(
-        VSM_MOVERS_BYTE_SIZE,
-        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-    ));
-
-    // the bounds it remembers have to move on every frame, whatever reads its list
-    movers_pass.make_side_effect();
-
     for (let i = 0; i < maps.length; i++) {
         // stamped with the map's own count, which its update advanced this frame
-        graph_vsm_map_feedback(graph, view, depth, maps[i], movers_data.movers, light_database, maps[i].frame_index);
+        graph_vsm_map_feedback(graph, view, depth, maps[i], movers, light_database, maps[i].frame_index);
     }
 }
 

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

@@ -6,7 +6,7 @@ import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPE
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import { VSM_FEEDBACK_LAYOUT } from "../VSM_FEEDBACK_LAYOUT.js";
-import { VSM_MOVER_CAPACITY, VSM_MOVERS_READ_STRUCT } from "../VSM_MOVER_LAYOUT.js";
+import { SCENE_MOVER_CAPACITY, SCENE_MOVERS_READ_STRUCT } from "../../../scene/movers/SCENE_MOVER_LAYOUT.js";
 import { VSM_SLOT_EMPTY } from "../VSM_SLOT_STRUCT.js";
 import { chunk_vsm_addressing } from "./chunk_vsm_addressing.js";
 
@@ -32,7 +32,7 @@ const args_resources = new ShaderResourceSetDescriptor();
 args_resources.setImmediate('settings', VSM_STALE_ARGS_SETTINGS_STRUCT);
 
 args_resources.createGroup()
-    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    .addStorageBuffer('movers', SCENE_MOVERS_READ_STRUCT, false)
     .addStorageBuffer('command', WebGPUArray.from(u32), true);
 
 /**
@@ -54,7 +54,7 @@ fn main() {
     let count = movers.count;
 
     command[0] = (settings.slot_count + ${VSM_STALE_WORKGROUP_SIZE - 1}u) / ${VSM_STALE_WORKGROUP_SIZE}u;
-    command[1] = select(count, 1u, count > ${VSM_MOVER_CAPACITY}u);
+    command[1] = select(count, 1u, count > ${SCENE_MOVER_CAPACITY}u);
     command[2] = 1u;
 }
 `),
@@ -74,7 +74,7 @@ stale_resources.setImmediate('settings', VSM_STALE_SETTINGS_STRUCT);
 
 stale_resources.createGroup()
     .addStorageBuffer('light_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    .addStorageBuffer('movers', SCENE_MOVERS_READ_STRUCT, false)
     // persistent, one word per slot: 1 when a mover crossed the slot since the flags were last read
     .addStorageBuffer('stale_flags', WebGPUArray.from(atomic_u32), true);
 
@@ -120,7 +120,7 @@ fn main(
 
     var hit = false;
 
-    if (movers.count > ${VSM_MOVER_CAPACITY}u) {
+    if (movers.count > ${SCENE_MOVER_CAPACITY}u) {
         // the list overflowed: every occupied slot may hold a stale shadow
         hit = wg_id.y == 0u;
     } else {
@@ -168,7 +168,7 @@ const compact_resources = new ShaderResourceSetDescriptor();
 compact_resources.setImmediate('settings', VSM_STALE_COMPACT_SETTINGS_STRUCT);
 
 compact_resources.createGroup()
-    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    .addStorageBuffer('movers', SCENE_MOVERS_READ_STRUCT, false)
     .addStorageBuffer('stale_flags', WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer('feedback', WebGPUArray.from(atomic_u32), true);
 

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

@@ -0,0 +1,90 @@
+/**
+ * Tiles of one size in rows across 2-D textures as wide as the device allows, one texture per format
+ * and every texture laid out alike: GPUProbeAtlas's placement, extracted for whatever else keeps tiles
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §4.1).
+ *
+ * Tile `i` sits at column `i % tiles_per_row` and row `⌊i / tiles_per_row⌋`, x fastest, which is
+ * `index_to_grid2d(i, tiles_per_row)` on the device. The textures are {@link tiles_per_row} tiles
+ * wide from the start, `⌊maxTextureDimension2D / tile_width⌋`, so a tile's column never changes; they
+ * grow in whole rows, keeping every tile's texels, until the device's height is reached.
+ *
+ * A reader that knows the tile size takes the row width from the texture itself,
+ * `textureDimensions(t).x / tile_width`. The tiles are the caller's to hand out; this only keeps
+ * room for them.
+ */
+export class GPUTileAtlas2D {
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUTextureFormat[]} options.formats one texture each
+     * @param {number[]} options.tile_size texels of a tile along x and y, its skirt included if it has one
+     * @param {GPUTextureUsageFlags} options.usage how the clients use the textures; copying for growth is added
+     * @param {string} options.label
+     * @param {number} [options.capacity] tiles to make room for up front
+     */
+    constructor({ device, formats, tile_size, usage, label, capacity }: {
+        device: GPUDevice;
+        formats: GPUTextureFormat[];
+        tile_size: number[];
+        usage: GPUTextureUsageFlags;
+        label: string;
+        capacity?: number;
+    });
+    /**
+     * Tiles a row holds: the textures' width in tiles, fixed.
+     * @returns {number}
+     */
+    get tiles_per_row(): number;
+    /**
+     * @returns {number}
+     */
+    get rows(): number;
+    /**
+     * Tiles the textures hold now.
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     * Tiles the textures can ever hold, at the device's height.
+     * @returns {number}
+     */
+    get capacity_limit(): number;
+    /**
+     * @returns {number[]} x, y
+     */
+    get tile_size(): number[];
+    /**
+     * @returns {number}
+     */
+    get texture_count(): number;
+    /**
+     * The texture of the `index`-th format. Replaced when the atlas grows; take a view each frame.
+     *
+     * @param {number} index
+     * @returns {GPUTextureContext}
+     */
+    texture_at(index: number): GPUTextureContext;
+    /**
+     * Room for `tile_count` tiles: rows are added, each tile keeping its texels. Past the device's
+     * height the atlas stops at it and says so, and the tiles past it have no home.
+     *
+     * @param {number} tile_count
+     */
+    ensure_capacity(tile_count: number): void;
+    /**
+     * The texel origin of a tile: its corner, skirt included.
+     *
+     * @param {number} index
+     * @param {number[]|Uint32Array} out receives x, y
+     * @returns {number[]|Uint32Array} out
+     */
+    tile_origin(index: number, out: number[] | Uint32Array): number[] | Uint32Array;
+    /**
+     * @returns {number} bytes
+     */
+    get gpu_memory_usage(): number;
+    destroy(): void;
+    #private;
+}
+import { GPUTextureContext } from "../GPUTextureContext.js";
+//# sourceMappingURL=GPUTileAtlas2D.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUTileAtlas2D.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/GPUTileAtlas2D.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IAqBI;;;;;;;;OAQG;IACH;QAP8B,MAAM;QACG,OAAO,EAAnC,kBAAkB;QACA,SAAS,EAA3B,MAAM,EAAE;QACsB,KAAK;QACnB,KAAK,EAArB,MAAM;QACW,QAAQ,GAAzB,MAAM;OA+BhB;IAED;;;OAGG;IACH,4BAEC;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;OAEG;IACH,0BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,4BAFW,MAAM,QAkBhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAShC;IAiBD;;OAEG;IACH,+BAQC;IAED,gBAIC;;CACJ;kCA7MiC,yBAAyB"}

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

@@ -0,0 +1,208 @@
+import { assert } from "../../../../core/assert.js";
+import { warn_limited } from "../../../util/warn_limited.js";
+import { GPUTextureContext } from "../GPUTextureContext.js";
+
+/**
+ * Tiles of one size in rows across 2-D textures as wide as the device allows, one texture per format
+ * and every texture laid out alike: GPUProbeAtlas's placement, extracted for whatever else keeps tiles
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §4.1).
+ *
+ * Tile `i` sits at column `i % tiles_per_row` and row `⌊i / tiles_per_row⌋`, x fastest, which is
+ * `index_to_grid2d(i, tiles_per_row)` on the device. The textures are {@link tiles_per_row} tiles
+ * wide from the start, `⌊maxTextureDimension2D / tile_width⌋`, so a tile's column never changes; they
+ * grow in whole rows, keeping every tile's texels, until the device's height is reached.
+ *
+ * A reader that knows the tile size takes the row width from the texture itself,
+ * `textureDimensions(t).x / tile_width`. The tiles are the caller's to hand out; this only keeps
+ * room for them.
+ */
+export class GPUTileAtlas2D {
+
+    /**
+     * @type {GPUTextureContext[]}
+     */
+    #textures = [];
+
+    /**
+     * @type {number[]}
+     */
+    #tile_size;
+
+    #tiles_per_row = 0;
+    #rows = 0;
+    #row_limit = 0;
+
+    /**
+     * @type {string}
+     */
+    #label;
+
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUTextureFormat[]} options.formats one texture each
+     * @param {number[]} options.tile_size texels of a tile along x and y, its skirt included if it has one
+     * @param {GPUTextureUsageFlags} options.usage how the clients use the textures; copying for growth is added
+     * @param {string} options.label
+     * @param {number} [options.capacity] tiles to make room for up front
+     */
+    constructor({ device, formats, tile_size, usage, label, capacity = 1 }) {
+        assert.defined(device, 'device');
+        assert.isArray(formats, 'formats');
+        assert.greaterThan(formats.length, 0, 'formats.length');
+        assert.isPositiveInteger(tile_size[0], 'tile_size[0]');
+        assert.isPositiveInteger(tile_size[1], 'tile_size[1]');
+        assert.isString(label, 'label');
+
+        const max_dimension = device.limits.maxTextureDimension2D;
+
+        this.#tile_size = [tile_size[0], tile_size[1]];
+        this.#tiles_per_row = Math.floor(max_dimension / tile_size[0]);
+        this.#row_limit = Math.floor(max_dimension / tile_size[1]);
+        this.#label = label;
+
+        assert.greaterThan(this.#tiles_per_row, 0, `tile width ${tile_size[0]} past maxTextureDimension2D ${max_dimension}`);
+        assert.greaterThan(this.#row_limit, 0, `tile height ${tile_size[1]} past maxTextureDimension2D ${max_dimension}`);
+
+        for (let i = 0; i < formats.length; i++) {
+            const texture = new GPUTextureContext(device);
+
+            texture.descriptor.format = formats[i];
+            texture.descriptor.usage |= usage | GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST;
+            texture.descriptor.label = formats.length > 1 ? `${label} / ${formats[i]}` : label;
+
+            this.#textures.push(texture);
+        }
+
+        this.#set_rows(Math.max(1, Math.ceil(capacity / this.#tiles_per_row)), false);
+    }
+
+    /**
+     * Tiles a row holds: the textures' width in tiles, fixed.
+     * @returns {number}
+     */
+    get tiles_per_row() {
+        return this.#tiles_per_row;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get rows() {
+        return this.#rows;
+    }
+
+    /**
+     * Tiles the textures hold now.
+     * @returns {number}
+     */
+    get capacity() {
+        return this.#tiles_per_row * this.#rows;
+    }
+
+    /**
+     * Tiles the textures can ever hold, at the device's height.
+     * @returns {number}
+     */
+    get capacity_limit() {
+        return this.#tiles_per_row * this.#row_limit;
+    }
+
+    /**
+     * @returns {number[]} x, y
+     */
+    get tile_size() {
+        return this.#tile_size;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get texture_count() {
+        return this.#textures.length;
+    }
+
+    /**
+     * The texture of the `index`-th format. Replaced when the atlas grows; take a view each frame.
+     *
+     * @param {number} index
+     * @returns {GPUTextureContext}
+     */
+    texture_at(index) {
+        return this.#textures[index];
+    }
+
+    /**
+     * Room for `tile_count` tiles: rows are added, each tile keeping its texels. Past the device's
+     * height the atlas stops at it and says so, and the tiles past it have no home.
+     *
+     * @param {number} tile_count
+     */
+    ensure_capacity(tile_count) {
+        assert.isNonNegativeInteger(tile_count, 'tile_count');
+
+        if (tile_count <= this.capacity) {
+            return;
+        }
+
+        let rows = Math.ceil(tile_count / this.#tiles_per_row);
+
+        if (rows > this.#row_limit) {
+            warn_limited(`${this.#label}: can't hold ${tile_count} tiles, past ${this.capacity_limit} at the device's height`);
+
+            rows = this.#row_limit;
+        }
+
+        this.#set_rows(rows, true);
+    }
+
+    /**
+     * The texel origin of a tile: its corner, skirt included.
+     *
+     * @param {number} index
+     * @param {number[]|Uint32Array} out receives x, y
+     * @returns {number[]|Uint32Array} out
+     */
+    tile_origin(index, out) {
+        assert.isNonNegativeInteger(index, 'index');
+
+        out[0] = (index % this.#tiles_per_row) * this.#tile_size[0];
+        out[1] = Math.floor(index / this.#tiles_per_row) * this.#tile_size[1];
+
+        return out;
+    }
+
+    /**
+     * @param {number} rows
+     * @param {boolean} preserve
+     */
+    #set_rows(rows, preserve) {
+        this.#rows = rows;
+
+        const width = this.#tiles_per_row * this.#tile_size[0];
+        const height = rows * this.#tile_size[1];
+
+        for (let i = 0; i < this.#textures.length; i++) {
+            this.#textures[i].resize(width, height, 1, preserve);
+        }
+    }
+
+    /**
+     * @returns {number} bytes
+     */
+    get gpu_memory_usage() {
+        let bytes = 0;
+
+        for (let i = 0; i < this.#textures.length; i++) {
+            bytes += this.#textures[i].gpu_memory_usage;
+        }
+
+        return bytes;
+    }
+
+    destroy() {
+        for (let i = 0; i < this.#textures.length; i++) {
+            this.#textures[i].destroy();
+        }
+    }
+}

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

@@ -84,11 +84,15 @@ export function tile_atlas_bordered_block(content: Uint8Array, content_size: Arr
  * Free slots are reused most-recently-freed first; a freed slot's texels are left as they were, and
  * move with it.
  *
- * 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
+ * **Or the device owns the slots.** A client that hands its slots out on the device (from a slot
+ * stack, `chunk_slot_stack`) {@link reserve}s a capacity instead, and never calls {@link allocate}:
+ * the host then never learns which slots are live, and every reserved slot keeps its texels through a
+ * grow or a widen, used or not.
+ *
+ * Clients: the volumetrics noise atlas (`r8unorm`, 128³ + 1, sampled) and the mesh brick atlas of
+ * `GPUGeometrySDFManager` (`r8unorm`, 8³ + 0, reserved: its slots are a slot stack's). Built
  * 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.
+ * so a published wind field can be another instance rather than another class.
  */
 export class GPUTileAtlas3D {
     /**
@@ -227,6 +231,21 @@ export class GPUTileAtlas3D {
      * @returns {number} the slot
      */
     allocate(): number;
+    /**
+     * Hold at least `capacity` slots, growing as {@link allocate} grows, without handing any out —
+     * for a client that owns its slots on the device. Every slot below `capacity` keeps its texels
+     * through every later grow and widen. Such a client calls this and never {@link allocate}, and
+     * the texture, the footprint and every {@link slot_origin} are to be taken after it, as after an
+     * allocation.
+     *
+     * @param {number} capacity
+     */
+    reserve(capacity: number): void;
+    /**
+     * Slots reserved for the device to hand out, 0 for an atlas the host allocates from.
+     * @returns {number}
+     */
+    get reserved(): number;
     /**
      * @param {number} slot
      */

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":"AAssBA;;;;;;;;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;AA90BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IA4FI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH;QArB8B,MAAM;QACE,MAAM;QAEJ,OAAO,GAApC,kBAAkB;QAEA,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;OAiGhB;IAED;;OAEG;IACH,iCAEC;IAED;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,kBAHW,MAAM,GACJ,iBAAiB,CAO7B;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,2CAEC;IAED;;;OAGG;IACH,iBAHW,MAAM,oBAQhB;IAED;;OAEG;IACH,8BAEC;IAED;;;OAGG;IACH,0BAHW,MAAM,GACJ,MAAM,CAOlB;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;;;;;;;;OAQG;IACH,YALW,MAAM,WACN,UAAU,kBAEV,MAAM,QAkChB;IAED;;;;;;;;;;;;OAYG;IACH,mDAPW,MAAM,kCAEN,MAAM,iBACN,MAAM,kBAEN,MAAM,QAgChB;IAED,gBAIC;;CAqIJ;kCAlsBiC,yBAAyB"}
+{"version":3,"file":"GPUTileAtlas3D.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/atlas/GPUTileAtlas3D.js"],"names":[],"mappings":"AAyvBA;;;;;;;;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;AAj4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH;IAmGI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH;QArB8B,MAAM;QACE,MAAM;QAEJ,OAAO,GAApC,kBAAkB;QAEA,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;OAiGhB;IAED;;OAEG;IACH,iCAEC;IAED;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,kBAHW,MAAM,GACJ,iBAAiB,CAO7B;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,2CAEC;IAED;;;OAGG;IACH,iBAHW,MAAM,oBAQhB;IAED;;OAEG;IACH,8BAEC;IAED;;;OAGG;IACH,0BAHW,MAAM,GACJ,MAAM,CAOlB;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,CAoBlB;IAED;;;;;;;;OAQG;IACH,kBAFW,MAAM,QAoBhB;IAED;;;OAGG;IACH,uBAEC;IAED;;OAEG;IACH,WAFW,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,kBAJW,MAAM,OACN,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,EAAE,GAAC,WAAW,CAehC;IAED;;;;;;;;OAQG;IACH,YALW,MAAM,WACN,UAAU,kBAEV,MAAM,QAkChB;IAED;;;;;;;;;;;;OAYG;IACH,mDAPW,MAAM,kCAEN,MAAM,iBACN,MAAM,kBAEN,MAAM,QAgChB;IAED,gBAIC;;CAsIJ;kCArvBiC,yBAAyB"}