@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,228 @@
+/**
+ * The VRAM tier: which pages are on the device, what they cost, and what goes when the budget says
+ * so.
+ *
+ * `VGeoRuntimeTables` is the layout and `VGeoResidencyManager` is the RAM tier's budget; this is
+ * the one in between, and it is the only object in the runtime that holds a `GPUDevice`. The split
+ * is the same one the format made between `format/read/` and `residency/`: a page's *shape* is a
+ * fact about the container, and what may be resident is a question about a scene.
+ *
+ * **Two tiers, two budgets, and the inner one is a subset.** A page is in VRAM only if it is in
+ * RAM, and every question this tier asks about its own residency it answers out of its own tables —
+ * eviction's child rule, the bytes an eviction refunds, and above all *selectability*, which was
+ * being taken from the RAM tier and is what REVIEW_LEDGER C1 is. The reader is consulted for
+ * exactly one thing: the decoded bytes of a page being installed.
+ *
+ * Eviction is design §6's rule: LRU on **last-touched**, under a protect window no shorter than
+ * feedback latency. Not last-*wanted* — that freezes a stamp at fetch time and evicts exactly what
+ * is on screen, which is the fallback-chain bug `VTPhysicalCache` already keys on touch to avoid.
+ *
+ * **Two budgets, and both of them bind.** Slots are fixed and finite, so a full table is as real a
+ * reason to evict as a full byte budget; `#make_room` loops on whichever of the two is short.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUVirtualGeometryPool {
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUMeshletManager} options.meshlets the pool VG shares with static geometry, so a VG
+     *     draw record is read downstream by the same shader that reads a static one
+     * @param {number} [options.budget_bytes] decoded page bytes this tier may hold; defaults to
+     *     what its slots hold at the page size it was built for, so the two agree by construction
+     * @param {number} [options.protect_window] frames a touched page is safe for; no shorter than
+     *     feedback latency, which is at least one frame of `mapAsync` and in practice several
+     * @param {Object} [options.table_options] passed to {@link VGeoRuntimeTables}
+     * @param {number} [options.page_size] the page size every container registered here must have
+     *     been built at, and the one this tier's slots are sized from
+     */
+    constructor({ device, meshlets, budget_bytes, protect_window, table_options, page_size, }: {
+        device: GPUDevice;
+        meshlets: GPUMeshletManager;
+        budget_bytes?: number;
+        protect_window?: number;
+        table_options?: any;
+        page_size?: number;
+    });
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_lookup(): GPUBuffer;
+    /**
+     * The arena, which is also the page table: a page's header is the first words of its slot.
+     * @returns {GPUBuffer}
+     */
+    get buffer_arena(): GPUBuffer;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_geometries(): GPUBuffer;
+    /**
+     * @returns {VGeoRuntimeTables}
+     */
+    get tables(): VGeoRuntimeTables;
+    /**
+     * @returns {number}
+     */
+    get resident_bytes(): number;
+    /**
+     * @returns {number}
+     */
+    get budget_bytes(): number;
+    /**
+     * The page size every container registered here is required to have been built at.
+     * @returns {number}
+     */
+    get page_size(): number;
+    /**
+     * @returns {number}
+     */
+    get page_slot_words(): number;
+    /**
+     * @returns {number}
+     */
+    get resident_page_count(): number;
+    /**
+     * @returns {number}
+     */
+    get evicted_page_count(): number;
+    /**
+     * Installs that could not be made — no slot could be freed, or the page did not fit one.
+     * @returns {number}
+     */
+    get refused_install_count(): number;
+    /**
+     * @returns {number}
+     */
+    get frame(): number;
+    /**
+     * One past the highest page row handed out — what sizes the feedback buffer's touch stamps.
+     * @returns {number}
+     */
+    get page_row_capacity(): number;
+    /**
+     * @returns {number}
+     */
+    get lookup_word_count(): number;
+    /**
+     * Give a container a geometry row, and make its root page resident and pinned.
+     *
+     * The root is not an optimization: every traversal is seeded with it, invariant §11.7 puts
+     * exactly one root cluster in the file, and a measured root page is one cluster of under two
+     * kilobytes. A geometry whose root is not here draws nothing.
+     *
+     * This is also the door the page-size guarantee is checked at, because it is the last moment a
+     * refusal is still cheap: past it, this container's pages are laid into the tier's storage on
+     * the strength of the size it was built at. The two ways that can be wrong are refused rather
+     * than reconciled — deliberately, and naming both numbers, because reconciling them means a
+     * table of slot-size classes and that is a later change than this one.
+     *
+     * @param {VGeoContainerReader} reader with its root page installed
+     * @returns {number} geometry row
+     * @throws {Error} when the container does not guarantee its page size, guarantees a different
+     *     one than this pool holds, or cannot get its root page onto the device
+     */
+    register(reader: VGeoContainerReader): number;
+    /**
+     * Drop a container: its pages, its meshlet batches, its lookup and its row.
+     *
+     * A registered geometry pins a root page, holds a meshlet batch per resident page and a block
+     * of the page lookup, and none of it used to have a way out (REVIEW_LEDGER M15). A scene that
+     * swaps assets leaks every one of those.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean} whether it was registered
+     */
+    unregister(reader: VGeoContainerReader): boolean;
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {number} geometry row, or -1
+     */
+    geometry_row_of(reader: VGeoContainerReader): number;
+    /**
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {boolean}
+     */
+    is_resident(reader: VGeoContainerReader, page_index: number): boolean;
+    /**
+     * Where this page's clusters actually are in the shared metadata pool, asked of the pool rather
+     * than of the page row — so a caller can check that the row agrees.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {number} metadata row, or -1
+     */
+    meshlet_base_of(reader: VGeoContainerReader, page_index: number): number;
+    /**
+     * Make a RAM-resident page VRAM-resident.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {number} page row, or -1 when the tier could not make room
+     */
+    install(reader: VGeoContainerReader, page_index: number): number;
+    /**
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    evict(page_row: number): boolean;
+    /**
+     * Which geometry owns a page row, and therefore which reader answers questions about it.
+     *
+     * A page row is the only handle the feedback loop gets back from the device — a touch is a row
+     * and a want names the row it was discovered through — so this is how a readback lands back on
+     * a container. It returns `undefined` for a row that has been evicted since the cut ran, which
+     * is ordinary rather than exceptional: feedback is at least a frame behind by construction.
+     *
+     * A row that has been evicted *and re-used* is the harder case, and it is not this method's:
+     * the caller compares {@link VGeoRuntimeTables.generation_of} against the generation it
+     * snapshotted when it built the graph.
+     *
+     * @param {number} page_row
+     * @returns {{reader: VGeoContainerReader, row: number}|undefined}
+     */
+    entry_of(page_row: number): {
+        reader: VGeoContainerReader;
+        row: number;
+    } | undefined;
+    /**
+     * A page the cut reported drawing from, this frame.
+     *
+     * @param {number} page_row
+     * @returns {void}
+     */
+    touch(page_row: number): void;
+    /**
+     * @returns {void}
+     */
+    advance_frame(): void;
+    /**
+     * Whether a page may go: not pinned, not touched inside the protect window, and with no VRAM
+     * child.
+     *
+     * The child rule is this tier's own, out of this tier's tables. Dropping a parent while its
+     * children stay leaves those children unreachable — nothing refines into them any more — so
+     * they would sit in VRAM, selectable, and never drawn.
+     *
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    evictable(page_row: number): boolean;
+    /**
+     * Push everything that changed since the last call to the device.
+     *
+     * Ranges rather than whole buffers, because the arena is the size of the resident set and a
+     * frame changes a page or two of it. Coalesced by sorting rather than by an interval tree: a
+     * frame's worth of installs is tens of ranges, and a structure that beat a sort at that size
+     * would be a structure to maintain.
+     *
+     * @returns {void}
+     */
+    flush(): void;
+    destroy(): void;
+    #private;
+}
+import { VGeoRuntimeTables } from "./VGeoRuntimeTables.js";
+//# sourceMappingURL=GPUVirtualGeometryPool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUVirtualGeometryPool.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IA4FI;;;;;;;;;;;;OAYG;IACH;QAX8B,MAAM;QACE,QAAQ;QAElB,YAAY,GAA7B,MAAM;QAEW,cAAc,GAA/B,MAAM;QAEW,aAAa;QACb,SAAS,GAA1B,MAAM;OAsChB;IAkCD;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;OAGG;IACH,oCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,uCAJa,MAAM,CAkDlB;IAED;;;;;;;;;OASG;IACH,yCAFa,OAAO,CAuCnB;IAqCD;;;OAGG;IACH,8CAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,qDAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,yDAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,iDAHW,MAAM,GACJ,MAAM,CAsElB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CA8CnB;IAED;;;;;;;;;;;;;;OAcG;IACH,mBAHW,MAAM,GACJ;QAAC,MAAM,sBAAsB;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAIhE;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH,iBAFa,IAAI,CAIhB;IAED;;;;;;;;;;OAUG;IACH,oBAHW,MAAM,GACJ,OAAO,CAgBnB;IAkID;;;;;;;;;OASG;IACH,SAFa,IAAI,CAMhB;IAwDD,gBAcC;;CACJ;kCA55BiC,wBAAwB"}