@woosh/meep-engine 3.60.5 → 3.60.6

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

@@ -56,15 +56,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 +195,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 +218,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 +243,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 +573,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 +582,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;
 
-        if (++this.#references[id] === 1 && this.#state[id] === HOST_NONE) {
+        const before = this.#references[id];
+
+        this.#references[id] = before + count;
+
+        if (before === 0 && this.#state[id] === HOST_NONE) {
             this.#request(id);
         }
 
@@ -605,7 +623,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 +632,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 +685,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 +719,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 +740,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 +764,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 +810,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 +980,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 +1212,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 +1243,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 +1672,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 +1766,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--;

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"}

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js

@@ -125,7 +125,8 @@ function grow_typed(array, length) {
  * - 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.
@@ -160,6 +161,12 @@ export class GPUMeshCardSets {
 
     #ids = new IdPool();
 
+    /**
+     * The source of each aliased geometry id.
+     * @type {Map<number, number>}
+     */
+    #source_of = new Map();
+
     // ---- per card set id ----
 
     #state = new Uint8Array(64);
@@ -479,7 +486,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
      */
@@ -487,6 +495,8 @@ export class GPUMeshCardSets {
         assert.isNonNegativeInteger(geometry, 'geometry');
         assert.defined(material, 'material');
 
+        geometry = this.#source_of.get(geometry) ?? geometry;
+
         const id = this.#ids.get();
 
         this.#ensure_id(id);
@@ -635,6 +645,60 @@ export class GPUMeshCardSets {
         }
     }
 
+    /**
+     * 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, source) {
+        assert.notEqual(clone, source, 'a geometry cannot alias itself');
+
+        this.#source_of.set(clone, source);
+
+        // its own layout, if it had one, went with its cache: what it has waits
+        this.drop_layout(clone);
+
+        const sets = this.#sets_of_geometry.get(clone);
+
+        if (sets === undefined) {
+            return;
+        }
+
+        this.#sets_of_geometry.delete(clone);
+
+        for (let i = 0; i < sets.length; i++) {
+            const id = sets[i];
+
+            this.#geometry[id] = source;
+
+            let of_source = this.#sets_of_geometry.get(source);
+
+            if (of_source === undefined) {
+                of_source = [];
+                this.#sets_of_geometry.set(source, of_source);
+            }
+
+            of_source.push(id);
+
+            if (this.#layout_pages.has(source)) {
+                this.#start(id);
+            }
+        }
+    }
+
+    /**
+     * `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) {
+        this.#source_of.delete(clone);
+    }
+
     /**
      * Pages from the atlas for a card set whose layout is placed, and its first capture queued.
      *

package/src/shade/renderer/geometry/virtual/proxy/vgeo_proxy_triangle_limit.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The triangles a virtual geometry's proxy is cut to by default: {@link VGEO_PROXY_TRIANGLE_SHARE} of the source's,
+ * at least one cluster's and at most {@link VGEO_PROXY_TRIANGLE_MAX}.
+ *
+ * @param {number} source_triangles
+ * @returns {number}
+ */
+export function vgeo_proxy_triangle_limit(source_triangles: number): number;
+/**
+ * The share of the source's triangles a proxy keeps by default.
+ * @type {number}
+ */
+export const VGEO_PROXY_TRIANGLE_SHARE: number;
+/**
+ * Most triangles a proxy has by default, however large the source.
+ * @type {number}
+ */
+export const VGEO_PROXY_TRIANGLE_MAX: number;
+//# sourceMappingURL=vgeo_proxy_triangle_limit.d.ts.map

package/src/shade/renderer/geometry/virtual/proxy/vgeo_proxy_triangle_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_proxy_triangle_limit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/proxy/vgeo_proxy_triangle_limit.js"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,4DAHW,MAAM,GACJ,MAAM,CAIlB;AArBD;;;GAGG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,sCAFU,MAAM,CAE6B"}

package/src/shade/renderer/geometry/virtual/proxy/vgeo_proxy_triangle_limit.js

@@ -0,0 +1,25 @@
+import { clamp } from "../../../../../core/math/clamp.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+
+/**
+ * The share of the source's triangles a proxy keeps by default.
+ * @type {number}
+ */
+export const VGEO_PROXY_TRIANGLE_SHARE = 0.01;
+
+/**
+ * Most triangles a proxy has by default, however large the source.
+ * @type {number}
+ */
+export const VGEO_PROXY_TRIANGLE_MAX = 64000;
+
+/**
+ * The triangles a virtual geometry's proxy is cut to by default: {@link VGEO_PROXY_TRIANGLE_SHARE} of the source's,
+ * at least one cluster's and at most {@link VGEO_PROXY_TRIANGLE_MAX}.
+ *
+ * @param {number} source_triangles
+ * @returns {number}
+ */
+export function vgeo_proxy_triangle_limit(source_triangles) {
+    return Math.floor(clamp(source_triangles * VGEO_PROXY_TRIANGLE_SHARE, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_PROXY_TRIANGLE_MAX));
+}

package/src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.d.ts

@@ -36,7 +36,22 @@ export class VirtualGeometry extends MeshletGeometry {
      * @type {number}
      */
     vg_row: number;
+    /**
+     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache is baked
+     * from and its cards are drawn from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
+     * {@link vgeo_proxy_triangle_limit} of the source's triangles, in the geometry's own space, with its attributes;
+     * asked for once, and the same proxy every time after.
+     *
+     * TODO: a container is expected to be delivered with its proxy, baked offline, and the proxy loaded here. Until
+     *   then it is cut here, through a reader of its own over the container's bytes: the shared {@link reader}'s pages
+     *   are its residency's, and the cut would install pages behind that residency's budget.
+     *
+     * @returns {Promise<MeshletGeometry>}
+     */
+    get_proxy(): Promise<MeshletGeometry>;
     isVirtualGeometry: boolean;
+    #private;
 }
 import { MeshletGeometry } from "../../MeshletGeometry.js";
+import { VGeoContainerReader } from "../format/read/VGeoContainerReader.js";
 //# sourceMappingURL=VirtualGeometry.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualGeometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAeI;;OAEG;IACH,yCAqBC;IAtCD;;;;OAIG;IACH,4BAAO;IAEP;;;;OAIG;IACH,QAFU,MAAM,CAEgB;IAyDpC,2BAA2C;CAF1C;gCA5F+B,0BAA0B"}
+{"version":3,"file":"VirtualGeometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAqBI;;OAEG;IACH,oBAFW,mBAAmB,EAuB7B;IA5CD;;;;OAIG;IACH,QAFU,mBAAmB,CAEtB;IAEP;;;;OAIG;IACH,QAFU,MAAM,CAEgB;IAkChC;;;;;;;;;;;OAWG;IACH,aAFa,QAAQ,eAAe,CAAC,CAQpC;IAwCL,2BAA2C;;CAF1C;gCAlI+B,0BAA0B;oCACtB,uCAAuC"}

package/src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../../../core/assert.js";
 import { MeshletGeometry } from "../../MeshletGeometry.js";
+import { VGeoContainerReader } from "../format/read/VGeoContainerReader.js";
+import { vgeo_proxy_triangle_limit } from "../proxy/vgeo_proxy_triangle_limit.js";
+import { vgeo_to_proxy_mesh } from "../proxy/vgeo_to_proxy_mesh.js";
 import { VGEO_GEOMETRY_ROW_NONE } from "./layout/VGEO_GEOMETRY_ROW_NONE.js";
 
 /**
@@ -38,6 +41,12 @@ export class VirtualGeometry extends MeshletGeometry {
      */
     vg_row = VGEO_GEOMETRY_ROW_NONE;
 
+    /**
+     * The proxy, once asked for.
+     * @type {Promise<MeshletGeometry>|null}
+     */
+    #proxy = null;
+
     /**
      * @param {VGeoContainerReader} reader an open container
      */
@@ -64,6 +73,35 @@ export class VirtualGeometry extends MeshletGeometry {
         this.primitive_count = Number(header.source_face_count);
     }
 
+    /**
+     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache is baked
+     * from and its cards are drawn from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
+     * {@link vgeo_proxy_triangle_limit} of the source's triangles, in the geometry's own space, with its attributes;
+     * asked for once, and the same proxy every time after.
+     *
+     * TODO: a container is expected to be delivered with its proxy, baked offline, and the proxy loaded here. Until
+     *   then it is cut here, through a reader of its own over the container's bytes: the shared {@link reader}'s pages
+     *   are its residency's, and the cut would install pages behind that residency's budget.
+     *
+     * @returns {Promise<MeshletGeometry>}
+     */
+    get_proxy() {
+        if (this.#proxy === null) {
+            this.#proxy = this.#cut_proxy();
+        }
+
+        return this.#proxy;
+    }
+
+    /**
+     * @returns {Promise<MeshletGeometry>}
+     */
+    async #cut_proxy() {
+        const reader = await VGeoContainerReader.open(this.reader.source);
+
+        return vgeo_to_proxy_mesh(reader, vgeo_proxy_triangle_limit(this.primitive_count));
+    }
+
     /**
      * A virtual geometry's identity is its **container**, not its meshlets.
      *