@woosh/meep-engine 3.60.4 → 3.60.6

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);
@@ -265,6 +272,14 @@ export class GPUMeshCardSets {
      */
     #frame_material_contexts = null;
 
+    /**
+     * What a frame's capture traces with: set by {@link graph_capture}. Only what is traced is made
+     * resident, each run's material as its run is taken, so a frame that traces nothing leaves the
+     * resident materials as they were.
+     * @type {GPUResidentMaterialContext|null}
+     */
+    #frame_materials = null;
+
     // the frame's shelves in the scratch
     #shelf_x = 0;
     #shelf_y = 0;
@@ -471,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
      */
@@ -479,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);
@@ -627,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.
      *
@@ -787,6 +859,9 @@ export class GPUMeshCardSets {
                 // a template that cannot be drawn this way is traced
             }
 
+            // its row as the material stands now, repacked if it has moved since
+            this.#frame_materials.obtain_material(this.#material[id]);
+
             const first = this.#next_page[id];
             const count = Math.min(pages - first, this.#frame_left);
 
@@ -930,7 +1005,8 @@ export class GPUMeshCardSets {
      * @param {number} options.budget pages captured at most, `card_capture_budget`
      * @param {number} options.arena graph handle of the arena, as the frame's bake left it
      * @param {GPUBuffer} options.headers
-     * @param {GPUResidentMaterialContext} options.materials what the trace shades with
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each traced
+     *        material is made resident, and the rows committed, before the trace is recorded
      * @param {GPUMaterialManager} options.material_contexts what the raster draws with: each
      *        material's template and bind group
      * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads, whose
@@ -947,10 +1023,12 @@ export class GPUMeshCardSets {
         }
 
         this.#frame_material_contexts = material_contexts;
+        this.#frame_materials = materials;
 
         this.#take(budget);
 
         this.#frame_material_contexts = null;
+        this.#frame_materials = null;
 
         const completed = this.#completed;
 
@@ -961,6 +1039,9 @@ export class GPUMeshCardSets {
             let emissive = graph_import_texture(graph, this.#atlas.texture_at(1), "mesh_card_emissive");
 
             if (this.#frame_runs > 0) {
+                // what the runs' materials made resident, written before the trace reads it
+                materials.commit();
+
                 this.#ensure_runs(this.#frame_runs);
 
                 this.#device.queue.writeBuffer(this.#runs, 0, this.#run_scratch, 0, 4 * this.#frame_runs);

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/proxy/vgeo_to_proxy_mesh.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Turn a virtual geometry into an ordinary meshlet geometry of at most `triangle_limit` triangles: a
+ * proxy, for whatever wants a plain mesh of an asset that is only clusters.
+ *
+ * **No simplification happens here.** The DAG already holds the asset at every level of detail; the
+ * proxy is a cut through it, and the cut's clusters are meshlets already (`VGEO_FORMAT.md` §8). The
+ * cut starts at the roots and refines, one group at a time, the group whose parents carry the largest
+ * `self_error`, and stops at the first refinement that would take it over the limit — so the error is
+ * as uniform as the DAG allows.
+ *
+ * A group is refined only once every one of its parents is in the cut (`group_parent_count`, §6), and
+ * then all of them are replaced together, so the cut is watertight at every step, as a view's cut is.
+ *
+ * Pages are installed as the descent reaches them, down to one band below the cut: a small proxy of a
+ * large asset reads the coarse prefix of the file and nothing else.
+ *
+ * The DAG's roots are as coarse as it goes: a limit below the roots' triangle count gets the roots.
+ *
+ * @param {VGeoContainerReader} reader an open container, which is one material's geometry; the pages the
+ *     descent reaches are installed into it and left there
+ * @param {number} triangle_limit
+ * @returns {Promise<MeshletGeometry>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_to_proxy_mesh(reader: VGeoContainerReader, triangle_limit: number): Promise<MeshletGeometry>;
+export type VGeoContainerReader = import("../format/read/VGeoContainerReader.js").VGeoContainerReader;
+export type VGeoPage = import("../format/read/VGeoPage.js").VGeoPage;
+import { MeshletGeometry } from "../../MeshletGeometry.js";
+//# sourceMappingURL=vgeo_to_proxy_mesh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_to_proxy_mesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/proxy/vgeo_to_proxy_mesh.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CARW,mBAAmB,kBAEnB,MAAM,GACJ,QAAQ,eAAe,CAAC,CAcpC;kCA7CY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;gCAP1B,0BAA0B"}

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

@@ -0,0 +1,343 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
+import { IndexedFloatMaxHeap } from "../../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { aabb3_array_combine } from "../../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { blas_from_meshlets } from "../../blas_from_meshlets.js";
+import { MESHLET_METADATA_STRUCT } from "../../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { MeshletGeometry } from "../../MeshletGeometry.js";
+import { VGEO_NO_CHILD } from "../format/cluster/VGEO_NO_CHILD.js";
+import { VGEO_SAME_PAGE } from "../format/cluster/VGEO_SAME_PAGE.js";
+import { vgeo_meshlet_metadata_write } from "../runtime/vgeo_meshlet_metadata_write.js";
+
+/**
+ * @typedef {import("../format/read/VGeoContainerReader.js").VGeoContainerReader} VGeoContainerReader
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
+
+/**
+ * A page not yet given its groups' ids.
+ * @type {number}
+ */
+const NO_BASE = -1;
+
+/**
+ * Turn a virtual geometry into an ordinary meshlet geometry of at most `triangle_limit` triangles: a
+ * proxy, for whatever wants a plain mesh of an asset that is only clusters.
+ *
+ * **No simplification happens here.** The DAG already holds the asset at every level of detail; the
+ * proxy is a cut through it, and the cut's clusters are meshlets already (`VGEO_FORMAT.md` §8). The
+ * cut starts at the roots and refines, one group at a time, the group whose parents carry the largest
+ * `self_error`, and stops at the first refinement that would take it over the limit — so the error is
+ * as uniform as the DAG allows.
+ *
+ * A group is refined only once every one of its parents is in the cut (`group_parent_count`, §6), and
+ * then all of them are replaced together, so the cut is watertight at every step, as a view's cut is.
+ *
+ * Pages are installed as the descent reaches them, down to one band below the cut: a small proxy of a
+ * large asset reads the coarse prefix of the file and nothing else.
+ *
+ * The DAG's roots are as coarse as it goes: a limit below the roots' triangle count gets the roots.
+ *
+ * @param {VGeoContainerReader} reader an open container, which is one material's geometry; the pages the
+ *     descent reaches are installed into it and left there
+ * @param {number} triangle_limit
+ * @returns {Promise<MeshletGeometry>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function vgeo_to_proxy_mesh(reader, triangle_limit) {
+    assert.defined(reader.root, 'reader.root — the container must be open');
+    assert.isNonNegativeInteger(triangle_limit, 'triangle_limit');
+
+    const cut = new ProxyCut(reader);
+
+    await cut.descend(triangle_limit);
+
+    return cut.build();
+}
+
+/**
+ * The cut, and the bookkeeping of its descent.
+ *
+ * Groups are given dense ids as their page is installed, so the per-group state is typed arrays sized
+ * once from the header's `total_groups`.
+ */
+class ProxyCut {
+    /**
+     * @param {VGeoContainerReader} reader
+     */
+    constructor(reader) {
+        this.reader = reader;
+
+        const capacity = reader.header.total_groups;
+
+        /**
+         * First group id of each page; {@link NO_BASE} until the page is installed.
+         */
+        this.page_base = new Int32Array(reader.header.total_pages).fill(NO_BASE);
+
+        this.next_base = 0;
+
+        this.group_page = new Uint32Array(capacity);
+        this.group_index = new Uint16Array(capacity);
+
+        /**
+         * Parents of the group in the cut so far.
+         */
+        this.arrived = new Uint16Array(capacity);
+
+        /**
+         * Their triangles: what refining the group takes out of the cut.
+         */
+        this.parent_triangles = new Uint32Array(capacity);
+
+        this.refined = new Uint8Array(capacity);
+
+        /**
+         * Groups whose every parent is in the cut, by the error those parents carry.
+         */
+        this.refinable = new IndexedFloatMaxHeap(capacity);
+
+        /**
+         * Every cluster that entered the cut, as the id of its group, its index in its page and the id
+         * of its child group (-1 for a leaf). One leaves the cut when its child group is refined.
+         * @type {number[]}
+         */
+        this.entered_group = [];
+        this.entered_cluster = [];
+        this.entered_child = [];
+
+        this.triangle_count = 0;
+    }
+
+    /**
+     * @param {number} limit
+     * @returns {Promise<void>}
+     */
+    async descend(limit) {
+        const root = this.reader.root;
+
+        this.#register(root);
+
+        for (let group = 0; group < root.group_parent_count.length; group++) {
+            // no cluster refines into it: the top of the DAG
+            if (root.group_parent_count[group] === 0) {
+                await this.#enter(this.page_base[root.index] + group);
+            }
+        }
+
+        const refinable = this.refinable;
+
+        while (refinable.size > 0) {
+            const id = refinable.pop_max();
+
+            if (this.triangle_count - this.parent_triangles[id] + this.#group_triangles(id) > limit) {
+                // the largest error left does not fit: refining anywhere finer would make it less uniform
+                break;
+            }
+
+            this.refined[id] = 1;
+            this.triangle_count -= this.parent_triangles[id];
+
+            await this.#enter(id);
+        }
+    }
+
+    /**
+     * The cut's clusters as a meshlet geometry: their payloads gathered as they are stored, a metadata
+     * row each, and the BVH the mesh path builds.
+     *
+     * @returns {MeshletGeometry}
+     */
+    build() {
+        /** @type {VGeoPage[]} */
+        const pages = [];
+        /** @type {number[]} */
+        const clusters = [];
+
+        let data_size = 0;
+
+        for (let i = 0; i < this.entered_group.length; i++) {
+            const child = this.entered_child[i];
+
+            if (child !== -1 && this.refined[child] === 1) {
+                continue;
+            }
+
+            const page = this.reader.page(this.group_page[this.entered_group[i]]);
+            const cluster = this.entered_cluster[i];
+
+            pages.push(page);
+            clusters.push(cluster);
+
+            data_size += page.cluster_payload_size[cluster];
+        }
+
+        const count = clusters.length;
+
+        const data = new Uint8Array(data_size);
+
+        const metadata = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+        metadata.setCapacity(count * MESHLET_METADATA_STRUCT.size);
+
+        const result = new MeshletGeometry();
+
+        const box = result.bounding_box;
+
+        box.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+
+        let address = 0;
+
+        for (let i = 0; i < count; i++) {
+            const page = pages[i];
+            const cluster = clusters[i];
+
+            const start = page.payload_offset + page.cluster_payload_offset[cluster];
+            const size = page.cluster_payload_size[cluster];
+
+            data.set(page.bytes.subarray(start, start + size), address);
+
+            // §11.8: every payload size is a multiple of four, so each cluster starts on a word
+            vgeo_meshlet_metadata_write(metadata, page, cluster, address >>> 2);
+
+            // `aabb` is the cluster's tight fit, so their union is the proxy's
+            aabb3_array_combine(box, 0, box, 0, page.aabb, cluster * 6);
+
+            address += size;
+        }
+
+        const batch = result.meshlets;
+
+        batch.count = count;
+        batch.data_buffer = data.buffer;
+        batch.metadata_buffer = metadata.data.slice(0, count * MESHLET_METADATA_STRUCT.size);
+
+        // the box-diagonal sphere `meshlet_geometry_build_from_geometry` gives a mesh
+        const sphere = result.bounding_sphere;
+
+        sphere[0] = (box[0] + box[3]) * 0.5;
+        sphere[1] = (box[1] + box[4]) * 0.5;
+        sphere[2] = (box[2] + box[5]) * 0.5;
+        sphere[3] = 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+
+        result.name = this.reader.source.name;
+        result.primitive_count = this.triangle_count;
+        result.bvh = blas_from_meshlets(batch, result.primitive_count, box);
+
+        return result;
+    }
+
+    /**
+     * @param {number} id
+     * @returns {number}
+     */
+    #group_triangles(id) {
+        const page = this.reader.page(this.group_page[id]);
+        const group = this.group_index[id];
+
+        const first = page.group_cluster_first[group];
+        const end = first + page.group_cluster_count[group];
+
+        let triangles = 0;
+
+        for (let cluster = first; cluster < end; cluster++) {
+            triangles += page.triangle_count[cluster];
+        }
+
+        return triangles;
+    }
+
+    /**
+     * Give an installed page's groups their ids.
+     *
+     * @param {VGeoPage} page
+     */
+    #register(page) {
+        if (this.page_base[page.index] !== NO_BASE) {
+            return;
+        }
+
+        const base = this.next_base;
+        const group_count = page.group_cluster_count.length;
+
+        this.page_base[page.index] = base;
+
+        for (let group = 0; group < group_count; group++) {
+            this.group_page[base + group] = page.index;
+            this.group_index[base + group] = group;
+        }
+
+        this.next_base = base + group_count;
+    }
+
+    /**
+     * Put a group's clusters in the cut, and count each in at its child group, which becomes
+     * refinable once its last parent arrives.
+     *
+     * @param {number} id
+     * @returns {Promise<void>}
+     */
+    async #enter(id) {
+        const reader = this.reader;
+        const page = reader.page(this.group_page[id]);
+        const group = this.group_index[id];
+
+        const first = page.group_cluster_first[group];
+        const end = first + page.group_cluster_count[group];
+
+        // the child pages first: a child group's parent count lives in its own page
+        const installs = [];
+
+        for (let cluster = first; cluster < end; cluster++) {
+            const child_ref = page.child_ref[cluster];
+
+            if (child_ref === VGEO_NO_CHILD || child_ref === VGEO_SAME_PAGE) {
+                continue;
+            }
+
+            const child_page = page.child_page_index[child_ref];
+
+            if (!reader.is_resident(child_page)) {
+                installs.push(reader.install(
+                    child_page, page.child_frame_offset[child_ref], page.child_fetch_size[child_ref]
+                ));
+            }
+        }
+
+        for (const child_page of await Promise.all(installs)) {
+            this.#register(child_page);
+        }
+
+        for (let cluster = first; cluster < end; cluster++) {
+            const triangles = page.triangle_count[cluster];
+
+            this.triangle_count += triangles;
+
+            this.entered_group.push(id);
+            this.entered_cluster.push(cluster);
+
+            const child_ref = page.child_ref[cluster];
+
+            if (child_ref === VGEO_NO_CHILD) {
+                this.entered_child.push(-1);
+                continue;
+            }
+
+            const child_page = reader.page(child_ref === VGEO_SAME_PAGE ? page.index : page.child_page_index[child_ref]);
+            const child_group = page.child_group[cluster];
+            const child = this.page_base[child_page.index] + child_group;
+
+            this.entered_child.push(child);
+
+            this.arrived[child]++;
+            this.parent_triangles[child] += triangles;
+
+            if (this.arrived[child] === child_page.group_parent_count[child_group]) {
+                this.refinable.insert(child, page.self_error[cluster]);
+            }
+        }
+    }
+}

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.
      *