@woosh/meep-engine 3.60.5 → 3.60.7

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts

@@ -14,7 +14,8 @@ export const MESH_SDF_BAKE_BUDGET_MAX: number;
  * queues a bake; the last one going leaves the cache in place until {@link trim}, which only a user of
  * the caches calls, so a cache outlives a mode that stops using it and is there when the mode comes
  * back (D28). {@link forget} drops a geometry the geometry manager has let go of, whatever holds it.
- * {@link alias} points a skinned clone's id at its source's cache, which readers follow.
+ * {@link alias} points a geometry's id at another's cache, which readers follow, and whose holders and card sets
+ * the aliased geometry's become: a skinned clone's at its source's, a virtual geometry's at its proxy's.
  *
  * **Side.** A holder says whether it draws both sides of the geometry. A field is baked two-sided
  * while any of its holders does: its vote then counts no back face, so nothing is inside it.
@@ -36,11 +37,11 @@ export const MESH_SDF_BAKE_BUDGET_MAX: number;
  * {@link cards}, whose card sets — one per (geometry, material) pair — are captured after the bake,
  * `capture_budget` pages a frame.
  *
- * **Sources** ({@link add_source}) make the caches of geometries with no tree of their own to bake from,
- * a virtual geometry's: such a geometry waits queued, as one whose tree is not resident yet does. A
- * source hears of each geometry queued ({@link onRequested}), records its own work each frame ahead of
- * the bake, and bakes a proxy of it here as any geometry, whose resident cache it then gives the
- * geometry ({@link adopt}).
+ * **A geometry with no tree of its own** to bake from, a virtual geometry's, waits queued, as one whose
+ * tree is not resident yet does, until it is pointed at a stand-in ({@link alias}): an ordinary geometry
+ * in the same local space, baked, placed and captured here as any is. Whoever makes stand-ins hears of
+ * each geometry queued ({@link onRequested}) and let go ({@link onForgotten}), and aliases between
+ * frames, its stand-in added to the geometry manager as any geometry is.
  *
  * **Readers** bind {@link headers}, {@link indirection}, {@link texture} and {@link MESH_SDF_SAMPLER}
  * (see {@link write_bindings}) and sample through `mesh_sdf_sample`, which only a resident header
@@ -55,15 +56,23 @@ export class GPUGeometrySDFManager {
      */
     constructor(device: GPUDevice, geometries: GPUGeometryManager);
     /**
-     * Sent with a geometry id when its cache turns resident, on the frame its completion is read back.
+     * Sent with a geometry id when its cache turns resident, on the frame its completion is read back, and with each
+     * geometry aliased to it, whose readers read that cache: also when the alias is made to a cache resident already.
      * @type {Signal<number>}
      */
     onBaked: any;
     /**
-     * Sent with a geometry's record each time its cache is queued for a bake: what a source listens to.
+     * Sent with a geometry's record each time its cache is queued for a bake: what a maker of stand-ins
+     * listens to.
      * @type {Signal<GPUGeometryMetadata>}
      */
     onRequested: any;
+    /**
+     * Sent with a geometry's record when {@link forget} lets it go: what a maker of stand-ins that made one for it
+     * listens to.
+     * @type {Signal<GPUGeometryMetadata>}
+     */
+    onForgotten: any;
     /**
      * The card sets: one capture of a geometry's layout per (geometry, material) pair, which their
      * user acquires and releases. Layouts reach it as they are placed.
@@ -87,14 +96,14 @@ export class GPUGeometrySDFManager {
      */
     get max_bricks(): number;
     /**
-     * One more holder of a geometry's cache; the first queues its bake.
+     * One more holder of a geometry's cache; the first queues its bake. A holder of an alias holds its source.
      *
      * @param {GPUGeometryMetadata} record
      * @param {boolean} two_sided whether the holder draws both sides of the geometry
      */
     acquire(record: GPUGeometryMetadata, two_sided: boolean): void;
     /**
-     * One holder fewer. The cache stays until {@link trim}.
+     * One holder fewer. The cache stays until {@link trim}. A holder of an alias holds its source.
      *
      * @param {GPUGeometryMetadata} record
      * @param {boolean} two_sided as the holder acquired it
@@ -113,7 +122,13 @@ export class GPUGeometrySDFManager {
     forget(record: GPUGeometryMetadata): void;
     /**
      * Readers of `clone` read `source`'s cache: the hook for a skinned clone, whose unskinned shape is
-     * its source's (§6.3). Written once; it follows the source through its bake.
+     * its source's (§6.3), and for a virtual geometry, whose proxy is its stand-in (§17). Written once; it
+     * follows the source through its bake.
+     *
+     * Whatever held `clone`'s own cache holds `source`'s from here on, its side included, as does every holder of
+     * `clone` after; and `clone`'s card sets capture `source`'s layout through `source`'s meshlets
+     * ({@link GPUMeshCardSets#alias}). So a source whose stand-in arrives after `clone` was asked for needs
+     * nothing moved by its holders.
      *
      * @param {GPUGeometryMetadata} clone
      * @param {GPUGeometryMetadata} source
@@ -141,27 +156,6 @@ export class GPUGeometrySDFManager {
      * @returns {boolean}
      */
     holds_two_sided(record: GPUGeometryMetadata): boolean;
-    /**
-     * @param {MeshSDFSource} source run first in each {@link graph_bake} from here on
-     */
-    add_source(source: MeshSDFSource): void;
-    /**
-     * @param {MeshSDFSource} source
-     */
-    remove_source(source: MeshSDFSource): void;
-    /**
-     * Give `target` the resident cache baked for `proxy`: a source's hand-in, for a geometry with no tree of its own,
-     * of a proxy in the same local space baked as any geometry is. Nothing is copied. The target's header takes the
-     * proxy's layout, entries and side, and the proxy's reads None, as dropped; {@link onBaked} is sent with the
-     * target. The cache has no cards, the target having no tree to capture them with. Held for another side than the
-     * proxy was baked for, it is queued again at the next bake, as any cache is.
-     *
-     * @param {GPUGeometryMetadata} target waiting for its bake ({@link is_requested})
-     * @param {GPUGeometryMetadata} proxy whose cache is resident
-     * @returns {boolean} whether it was adopted: false, changing nothing, when `target` no longer waits or `proxy`'s
-     *   cache is not resident
-     */
-    adopt(target: GPUGeometryMetadata, proxy: GPUGeometryMetadata): boolean;
     /**
      * Geometries whose layout was coarsened by the cap, of those baked: coarser than asked.
      * @returns {number}
@@ -265,17 +259,6 @@ export type GPUGeometryManager = import("../GPUGeometryManager.js").GPUGeometryM
 export type GPUGeometryMetadata = import("../GPUGeometryMetadata.js").GPUGeometryMetadata;
 export type GPUResidentMaterialContext = import("../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext;
 export type GPUMaterialManager = import("../../material/GPUMaterialManager.js").GPUMaterialManager;
-/**
- * What makes caches for geometries the bake cannot bake from a tree of their own
- * ({@link GPUGeometrySDFManageradd_source }): it learns what is asked for from `onRequested`, records its own work in
- * each frame's graph ahead of the bake, and hands each cache in through `adopt`.
- */
-export type MeshSDFSource = {
-    /**
-     * records the source's work for the frame, ahead of the bake
-     */
-    graph_update: (arg0: FrameGraph) => void;
-};
 import { GPUMeshCardSets } from "./cards/GPUMeshCardSets.js";
 import { MeshSDFState } from "./MESH_SDF.js";
 //# sourceMappingURL=GPUGeometrySDFManager.d.ts.map

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AA+IA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAgDvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAsQI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IArQD;;;OAGG;IACH,aAAuB;IAEvB;;;OAGG;IACH,iBAA2B;IA6P3B;;;;OAIG;IACH,6BAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAe7B;IAED;;;;;;OAMG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QA0B7B;IAQD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAaxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;OAEG;IACH,mBAFW,aAAa,QAOvB;IAED;;OAEG;IACH,sBAFW,aAAa,QAQvB;IAED;;;;;;;;;;;OAWG;IACH,cALW,mBAAmB,SACnB,mBAAmB,GACjB,OAAO,CA4CnB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;QAEG,iBAAiB,GAAnD,kBAAkB,GAAC,IAAI;aA8EjC;IAwiCD,gBAsBC;;CACJ;yBAljEY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;iCAC1F,OAAO,sCAAsC,EAAE,kBAAkB;;;;;;;;;;yBASvD,UAAU,KAAG,IAAI;;gCA3BsB,4BAA4B;6BAQf,eAAe"}
+{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAuIA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAgDvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAyQI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IAxQD;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAE3B;;;;OAIG;IACH,iBAA2B;IAuP3B;;;;OAIG;IACH,6BAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAajB;IAiCD;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAiB7B;IAED;;;;;;;;;;;;OAYG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QAwD7B;IAcD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAaxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;QAEG,iBAAiB,GAAnD,kBAAkB,GAAC,IAAI;aAuEjC;IAojCD,gBAsBC;;CACJ;yBAziEY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;iCAC1F,OAAO,sCAAsC,EAAE,kBAAkB;gCAnBhB,4BAA4B;6BAQf,eAAe"}

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js

@@ -47,6 +47,7 @@ import { MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_VOXELS, MeshSDFState } from "./ME
 import { MESH_SDF_SAMPLER } from "./MESH_SDF_RESOURCES.js";
 import { MESH_SDF_STRUCT } from "./MESH_SDF_STRUCT.js";
 import { MeshSDFLayout } from "./MeshSDFLayout.js";
+import { ceilPowerOfTwo } from "../../../../core/binary/operations/ceilPowerOfTwo.js";
 
 /**
  * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
@@ -56,15 +57,6 @@ import { MeshSDFLayout } from "./MeshSDFLayout.js";
  * @typedef {import("../../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
  */
 
-/**
- * What makes caches for geometries the bake cannot bake from a tree of their own
- * ({@link GPUGeometrySDFManager#add_source}): it learns what is asked for from `onRequested`, records its own work in
- * each frame's graph ahead of the bake, and hands each cache in through `adopt`.
- *
- * @typedef {Object} MeshSDFSource
- * @property {function(FrameGraph): void} graph_update records the source's work for the frame, ahead of the bake
- */
-
 /*
  What the host knows of a geometry id. `Queued` is the host's alone: the header reads None until the
  bake is admitted and the indirection range is the geometry's.
@@ -204,7 +196,8 @@ function grow_typed(array, length) {
  * queues a bake; the last one going leaves the cache in place until {@link trim}, which only a user of
  * the caches calls, so a cache outlives a mode that stops using it and is there when the mode comes
  * back (D28). {@link forget} drops a geometry the geometry manager has let go of, whatever holds it.
- * {@link alias} points a skinned clone's id at its source's cache, which readers follow.
+ * {@link alias} points a geometry's id at another's cache, which readers follow, and whose holders and card sets
+ * the aliased geometry's become: a skinned clone's at its source's, a virtual geometry's at its proxy's.
  *
  * **Side.** A holder says whether it draws both sides of the geometry. A field is baked two-sided
  * while any of its holders does: its vote then counts no back face, so nothing is inside it.
@@ -226,11 +219,11 @@ function grow_typed(array, length) {
  * {@link cards}, whose card sets — one per (geometry, material) pair — are captured after the bake,
  * `capture_budget` pages a frame.
  *
- * **Sources** ({@link add_source}) make the caches of geometries with no tree of their own to bake from,
- * a virtual geometry's: such a geometry waits queued, as one whose tree is not resident yet does. A
- * source hears of each geometry queued ({@link onRequested}), records its own work each frame ahead of
- * the bake, and bakes a proxy of it here as any geometry, whose resident cache it then gives the
- * geometry ({@link adopt}).
+ * **A geometry with no tree of its own** to bake from, a virtual geometry's, waits queued, as one whose
+ * tree is not resident yet does, until it is pointed at a stand-in ({@link alias}): an ordinary geometry
+ * in the same local space, baked, placed and captured here as any is. Whoever makes stand-ins hears of
+ * each geometry queued ({@link onRequested}) and let go ({@link onForgotten}), and aliases between
+ * frames, its stand-in added to the geometry manager as any geometry is.
  *
  * **Readers** bind {@link headers}, {@link indirection}, {@link texture} and {@link MESH_SDF_SAMPLER}
  * (see {@link write_bindings}) and sample through `mesh_sdf_sample`, which only a resident header
@@ -251,22 +244,25 @@ export class GPUGeometrySDFManager {
     #geometries;
 
     /**
-     * Sent with a geometry id when its cache turns resident, on the frame its completion is read back.
+     * Sent with a geometry id when its cache turns resident, on the frame its completion is read back, and with each
+     * geometry aliased to it, whose readers read that cache: also when the alias is made to a cache resident already.
      * @type {Signal<number>}
      */
     onBaked = new Signal();
 
     /**
-     * Sent with a geometry's record each time its cache is queued for a bake: what a source listens to.
+     * Sent with a geometry's record each time its cache is queued for a bake: what a maker of stand-ins
+     * listens to.
      * @type {Signal<GPUGeometryMetadata>}
      */
     onRequested = new Signal();
 
     /**
-     * Run first in each {@link graph_bake}.
-     * @type {MeshSDFSource[]}
+     * Sent with a geometry's record when {@link forget} lets it go: what a maker of stand-ins that made one for it
+     * listens to.
+     * @type {Signal<GPUGeometryMetadata>}
      */
-    #sources = [];
+    onForgotten = new Signal();
 
     #voxel_size = 0.125;
     #max_bricks = 18;
@@ -578,7 +574,7 @@ export class GPUGeometrySDFManager {
     }
 
     /**
-     * One more holder of a geometry's cache; the first queues its bake.
+     * One more holder of a geometry's cache; the first queues its bake. A holder of an alias holds its source.
      *
      * @param {GPUGeometryMetadata} record
      * @param {boolean} two_sided whether the holder draws both sides of the geometry
@@ -587,17 +583,40 @@ export class GPUGeometrySDFManager {
         assert.defined(record, 'record');
         assert.isBoolean(two_sided, 'two_sided');
 
-        const id = record.index;
+        this.#ensure_id(record.index);
 
-        this.#ensure_id(id);
+        if (this.#state[record.index] !== HOST_ALIAS) {
+            this.#records[record.index] = record;
+        }
 
-        this.#records[id] = record;
+        this.#hold(this.#holder_id(record.index), 1, two_sided ? 1 : 0);
+    }
 
-        if (two_sided) {
-            this.#two_sided_references[id]++;
-        }
+    /**
+     * The id a holder of `id` holds: its source's, for an alias.
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    #holder_id(id) {
+        return this.#state[id] === HOST_ALIAS ? this.#aliases.get(id) : id;
+    }
+
+    /**
+     * `count` more holders of `id`, `two_sided` of them drawing both sides; the first queues its bake.
+     *
+     * @param {number} id
+     * @param {number} count
+     * @param {number} two_sided
+     */
+    #hold(id, count, two_sided) {
+        this.#two_sided_references[id] += two_sided;
+
+        const before = this.#references[id];
 
-        if (++this.#references[id] === 1 && this.#state[id] === HOST_NONE) {
+        this.#references[id] = before + count;
+
+        if (before === 0 && this.#state[id] === HOST_NONE) {
             this.#request(id);
         }
 
@@ -605,7 +624,7 @@ export class GPUGeometrySDFManager {
     }
 
     /**
-     * One holder fewer. The cache stays until {@link trim}.
+     * One holder fewer. The cache stays until {@link trim}. A holder of an alias holds its source.
      *
      * @param {GPUGeometryMetadata} record
      * @param {boolean} two_sided as the holder acquired it
@@ -614,7 +633,7 @@ export class GPUGeometrySDFManager {
         assert.defined(record, 'record');
         assert.isBoolean(two_sided, 'two_sided');
 
-        const id = record.index;
+        const id = this.#holder_id(record.index);
 
         assert.greaterThan(this.#references[id] ?? 0, 0, `geometry ${id} released more often than acquired`);
 
@@ -667,11 +686,19 @@ export class GPUGeometrySDFManager {
         this.#two_sided_references[id] = 0;
         this.#drop(id);
         this.#records[id] = undefined;
+
+        this.onForgotten.send1(record);
     }
 
     /**
      * Readers of `clone` read `source`'s cache: the hook for a skinned clone, whose unskinned shape is
-     * its source's (§6.3). Written once; it follows the source through its bake.
+     * its source's (§6.3), and for a virtual geometry, whose proxy is its stand-in (§17). Written once; it
+     * follows the source through its bake.
+     *
+     * Whatever held `clone`'s own cache holds `source`'s from here on, its side included, as does every holder of
+     * `clone` after; and `clone`'s card sets capture `source`'s layout through `source`'s meshlets
+     * ({@link GPUMeshCardSets#alias}). So a source whose stand-in arrives after `clone` was asked for needs
+     * nothing moved by its holders.
      *
      * @param {GPUGeometryMetadata} clone
      * @param {GPUGeometryMetadata} source
@@ -693,6 +720,20 @@ export class GPUGeometrySDFManager {
 
         this.#state[id] = HOST_ALIAS;
 
+        const held = this.#references[id];
+        const held_two_sided = this.#two_sided_references[id];
+
+        this.#references[id] = 0;
+        this.#two_sided_references[id] = 0;
+
+        if (this.#state[source.index] !== HOST_ALIAS) {
+            this.#records[source.index] = source;
+        }
+
+        if (held > 0) {
+            this.#hold(source.index, held, held_two_sided);
+        }
+
         if (this.#headers !== null) {
             this.#ensure_headers(id + 1);
             this.#write_header_alias(id, source.index);
@@ -700,6 +741,22 @@ export class GPUGeometrySDFManager {
 
         this.#records[id] = clone;
         this.#aliases.set(id, source.index);
+
+        let clones = this.#clones_of.get(source.index);
+
+        if (clones === undefined) {
+            clones = [];
+            this.#clones_of.set(source.index, clones);
+        }
+
+        clones.push(id);
+
+        this.#cards.alias(id, source.index);
+
+        if (this.#state[source.index] === HOST_RESIDENT) {
+            // its readers read a resident cache from here on
+            this.onBaked.send1(id);
+        }
     }
 
     /**
@@ -708,6 +765,12 @@ export class GPUGeometrySDFManager {
      */
     #aliases = new Map();
 
+    /**
+     * The ids aliased to each source id: the readers {@link onBaked} tells of the source's bake too.
+     * @type {Map<number, number[]>}
+     */
+    #clones_of = new Map();
+
     /**
      * What a reader finds in the geometry's header.
      *
@@ -748,82 +811,6 @@ export class GPUGeometrySDFManager {
         return (this.#two_sided_references[record.index] ?? 0) > 0;
     }
 
-    /**
-     * @param {MeshSDFSource} source run first in each {@link graph_bake} from here on
-     */
-    add_source(source) {
-        assert.defined(source, 'source');
-        assert.equal(this.#sources.includes(source), false, 'source added already');
-
-        this.#sources.push(source);
-    }
-
-    /**
-     * @param {MeshSDFSource} source
-     */
-    remove_source(source) {
-        const index = this.#sources.indexOf(source);
-
-        if (index !== -1) {
-            this.#sources.splice(index, 1);
-        }
-    }
-
-    /**
-     * Give `target` the resident cache baked for `proxy`: a source's hand-in, for a geometry with no tree of its own,
-     * of a proxy in the same local space baked as any geometry is. Nothing is copied. The target's header takes the
-     * proxy's layout, entries and side, and the proxy's reads None, as dropped; {@link onBaked} is sent with the
-     * target. The cache has no cards, the target having no tree to capture them with. Held for another side than the
-     * proxy was baked for, it is queued again at the next bake, as any cache is.
-     *
-     * @param {GPUGeometryMetadata} target waiting for its bake ({@link is_requested})
-     * @param {GPUGeometryMetadata} proxy whose cache is resident
-     * @returns {boolean} whether it was adopted: false, changing nothing, when `target` no longer waits or `proxy`'s
-     *   cache is not resident
-     */
-    adopt(target, proxy) {
-        assert.defined(target, 'target');
-        assert.defined(proxy, 'proxy');
-        assert.notEqual(target.index, proxy.index, 'a geometry cannot adopt its own cache');
-
-        const id = target.index;
-        const from = proxy.index;
-
-        if (!this.is_requested(target) || this.#state[from] !== HOST_RESIDENT) {
-            return false;
-        }
-
-        this.#drop_cards(from);
-
-        const range = this.#ranges[from];
-
-        this.#ranges[id] = range;
-        this.#ranges[from] = null;
-        this.#brick_count[id] = this.#brick_count[from];
-        this.#two_sided[id] = this.#two_sided[from];
-        this.#generation[id]++;
-
-        this.#state[from] = HOST_NONE;
-        this.#state[id] = HOST_RESIDENT;
-
-        // the layout the proxy was admitted with: a configure since would have dropped its cache
-        const layout = this.#layout;
-
-        layout.compute(proxy.geometry.bounding_box, this.#voxel_size, this.#max_bricks);
-
-        this.#write_header(id, layout, range.offset + 1, MeshSDFState.Resident);
-
-        this.#word_scratch[0] = MeshSDFState.None;
-        this.#device.queue.writeBuffer(this.#headers, from * HEADER_BYTES + HEADER_STATE, this.#word_scratch, 0, 1);
-
-        // the side its holders draw is checked at the next bake
-        this.#holders_changed.push(id);
-
-        this.onBaked.send1(id);
-
-        return true;
-    }
-
     /**
      * Geometries whose layout was coarsened by the cap, of those baked: coarser than asked.
      * @returns {number}
@@ -994,13 +981,6 @@ export class GPUGeometrySDFManager {
 
         this.#frame++;
 
-        // the sources first: a cache adopted here is not admitted to a bake of its own below
-        const sources = this.#sources;
-
-        for (let i = 0; i < sources.length; i++) {
-            sources[i].graph_update(graph);
-        }
-
         this.#follow_sides();
 
         // the last bake's commands were submitted before this call: what they read may be handed out
@@ -1233,7 +1213,7 @@ export class GPUGeometrySDFManager {
     /**
      * Whether a queued geometry's tree is traceable, so that a bake could admit it. A geometry that
      * waits for its tree, or for a source's cache, records no bake while it waits. Drops from the queue
-     * what was dropped, or adopted, since it was queued.
+     * what was dropped, or aliased, since it was queued.
      *
      * @returns {boolean}
      */
@@ -1264,8 +1244,8 @@ export class GPUGeometrySDFManager {
     }
 
     /**
-     * Whether a resident geometry's cards wait for placement. Drops from the queue what was dropped, or
-     * adopted away, since it was queued.
+     * Whether a resident geometry's cards wait for placement. Drops from the queue what was dropped
+     * since it was queued.
      *
      * @returns {boolean}
      */
@@ -1693,6 +1673,14 @@ export class GPUGeometrySDFManager {
             this.#place_queue.push(id);
 
             this.onBaked.send1(id);
+
+            const clones = this.#clones_of.get(id);
+
+            if (clones !== undefined) {
+                for (let i = 0; i < clones.length; i++) {
+                    this.onBaked.send1(clones[i]);
+                }
+            }
         }
     }
 
@@ -1779,7 +1767,12 @@ export class GPUGeometrySDFManager {
         }
 
         if (state === HOST_ALIAS) {
+            const clones = this.#clones_of.get(this.#aliases.get(id));
+
+            clones.splice(clones.indexOf(id), 1);
+
             this.#aliases.delete(id);
+            this.#cards.unalias(id);
         } else {
             if (state === HOST_BAKING) {
                 this.#baking--;
@@ -1940,7 +1933,7 @@ export class GPUGeometrySDFManager {
      * A ring for twice the bricks of the largest geometry the cap allows, emptied.
      */
     #reset_ring() {
-        const capacity = 2 ** Math.ceil(Math.log2(2 * max_bricks_of_a_geometry(this.#max_bricks)));
+        const capacity = ceilPowerOfTwo(2 * max_bricks_of_a_geometry(this.#max_bricks));
 
         if (this.#ring === null || this.#ring_capacity !== capacity) {
             this.#ring?.destroy();
@@ -2077,11 +2070,7 @@ export class GPUGeometrySDFManager {
 
         buffer?.destroy();
 
-        let capacity = 64;
-
-        while (8 * capacity < size) {
-            capacity *= 2;
-        }
+        const capacity = Math.max(64, ceilPowerOfTwo(runs));
 
         return this.#create_buffer(name, 8 * capacity, GPUBufferUsage.COPY_DST);
     }
@@ -2093,6 +2082,9 @@ export class GPUGeometrySDFManager {
      * @returns {GPUBuffer}
      */
     #create_buffer(name, size, usage) {
+        // bound whole, as storage
+        assert.lessThanOrEqual(size, this.#device.limits.maxStorageBufferBindingSize, `${name} past maxStorageBufferBindingSize`);
+
         return this.#device.createBuffer(BufferDescriptor.fromJSON({
             label: `GPUGeometrySDFManager/${name}`,
             size,

package/src/shade/renderer/geometry/sdf/MeshSDFLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshSDFLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/MeshSDFLayout.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IACI;;;OAGG;IACH,QAFU,YAAY,CAEO;IAE7B;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,UAAU,CAEO;IAE3B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;OAGG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,gBALW,UAAU,MAAM,CAAC,cACjB,MAAM,cACN,MAAM,GACJ,aAAa,CAuDzB;CACJ"}
+{"version":3,"file":"MeshSDFLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/MeshSDFLayout.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IACI;;;OAGG;IACH,QAFU,YAAY,CAEO;IAE7B;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,UAAU,CAEO;IAE3B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;OAGG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,gBALW,UAAU,MAAM,CAAC,cACjB,MAAM,cACN,MAAM,GACJ,aAAa,CAuDzB;CACJ"}

package/src/shade/renderer/geometry/sdf/MeshSDFLayout.js

@@ -1,5 +1,6 @@
 import { assert } from "../../../../core/assert.js";
 import { MESH_SDF_BAND_VOXELS, MESH_SDF_BRICK_VOXELS } from "./MESH_SDF.js";
+import { ceil_log2 } from "../../../../core/binary/operations/ceil_log2.js";
 
 /**
  * Where a geometry's sparse distance field sits and how it is cut (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md
@@ -142,7 +143,7 @@ export class MeshSDFLayout {
             longest = Math.max(longest, bricks);
         }
 
-        this.level_count = 1 + Math.ceil(Math.log2(longest));
+        this.level_count = 1 + ceil_log2(longest);
 
         let total = 0;
 

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts

@@ -24,7 +24,8 @@ export const MESH_CARD_CAPTURE_BUDGET_MAX: number;
  * - Its record (`MESH_CARD_SET_STRUCT`) is written when a capture starts.
  *
  * **Lifetime.** {@link acquire} makes a card set for a pair and {@link release} gives it back; the
- * caller keeps one per pair. A card set waits until its geometry's layout is placed
+ * caller keeps one per pair. A card set of an aliased geometry ({@link alias}) is its source's: it
+ * captures the source's layout through the source's meshlets. A card set waits until its geometry's layout is placed
  * ({@link set_layout}), is then captured, and turns resident ({@link onResident}) on the frame its
  * last page is recorded: the capture's writes come before any later pass reads it. A layout that
  * goes ({@link drop_layout}) withdraws its card sets ({@link onWithdrawn}) back to waiting.
@@ -121,7 +122,8 @@ export class GPUMeshCardSets {
     /**
      * A card set for a pair. The caller keeps one per pair.
      *
-     * @param {number} geometry the geometry id whose layout it captures: the source's, for a skinned row
+     * @param {number} geometry the geometry id the pair draws; an aliased one's card set captures its source's
+     *     layout ({@link alias})
      * @param {ShadeMaterial} material
      * @returns {number} card set id
      */
@@ -152,6 +154,22 @@ export class GPUMeshCardSets {
      * @param {number} geometry
      */
     drop_layout(geometry: number): void;
+    /**
+     * The geometry `clone` is drawn as `source` from here on: its card sets, and those acquired for it after, capture
+     * `source`'s layout through `source`'s meshlets, the two being in one local space. A card set of `clone` waits
+     * for `source`'s layout, as one acquired for `source` does.
+     *
+     * @param {number} clone
+     * @param {number} source
+     */
+    alias(clone: number, source: number): void;
+    /**
+     * `clone` is no longer aliased: card sets acquired for it from here on capture its own layout. Those it has keep
+     * capturing its source's until they are given back.
+     *
+     * @param {number} clone
+     */
+    unalias(clone: number): void;
     /**
      * Record the frame's capture: at most `budget` pages. Records nothing when nothing waits. Card
      * sets whose first capture this completes are resident from here, and {@link onResident} is sent

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AAyEA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AApCD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA0DnG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IA2LI;;OAEG;IACH,+BAIC;IA3LD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IAmL3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IASD;;;;;OAKG;IACH,+BAgBC;IA7BD;;OAEG;IACH,2BAEC;IA0BD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CA+BlB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,SACN,MAAM,QACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA+BhB;IA0SD;;;;;;;;;;;;;;;;OAgBG;IACH;QAX+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QAEE,iBAAiB,EAA7C,kBAAkB;QAEF,IAAI;aAsG9B;IAiTD;;OAEG;IACH,+BAuBC;IAED,gBAoBC;;CACJ;yBA91CY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;iCAC7F,OAAO,yCAAyC,EAAE,kBAAkB;iCACpE,OAAO,yCAAyC,EAAE,kBAAkB;yBACpE,OAAO,yDAAyD,EAAE,UAAU;+BAxB1D,0CAA0C"}
+{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AAyEA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AApCD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA0DnG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAiMI;;OAEG;IACH,+BAIC;IAjMD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IAyL3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IASD;;;;;OAKG;IACH,+BAgBC;IA7BD;;OAEG;IACH,2BAEC;IA0BD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,YAEN,aAAa,GACX,MAAM,CAiClB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,SACN,MAAM,QACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA+BhB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,UACN,MAAM,QAoChB;IAED;;;;;OAKG;IACH,eAFW,MAAM,QAIhB;IA0SD;;;;;;;;;;;;;;;;OAgBG;IACH;QAX+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QAEE,iBAAiB,EAA7C,kBAAkB;QAEF,IAAI;aAsG9B;IAiTD;;OAEG;IACH,+BAuBC;IAED,gBAoBC;;CACJ;yBA95CY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;iCAC7F,OAAO,yCAAyC,EAAE,kBAAkB;iCACpE,OAAO,yCAAyC,EAAE,kBAAkB;yBACpE,OAAO,yDAAyD,EAAE,UAAU;+BAxB1D,0CAA0C"}