@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,287 @@
+/**
+ * What a VRAM-resident page **is**, with no device anywhere near it.
+ *
+ * Two word arrays: the arena of fixed-stride page slots, and the per-geometry page lookup.
+ * {@link GPUVirtualGeometryPool} owns the buffers, the budget and the meshlet-pool allocation; this
+ * owns the layout, and the split is the same one `format/read/` and `residency/` already make —
+ * mechanics below, policy and devices above.
+ *
+ * It is worth having as its own object for a reason beyond tidiness: the cut kernel's agreement
+ * against `vgeo_select_cut` is the single most important test in this campaign, and it can run in
+ * node against these arrays. A mirror written for the spec would prove the mirror.
+ *
+ * ## Slots, not allocations
+ *
+ * A page's rows live at `page_row × slot_words`, and everything that used to make that address a
+ * question is gone with the question: no `OffsetAllocator`, no growth, no ceiling, no shadow that
+ * can grow before the buffer it mirrors. `VIRTUAL_GEOMETRY_DESIGN.md` §6 asked for this from the
+ * start and format §11.14 is what finally permits it — `nominal_page_size` is a bound every page is
+ * within, `GPUVirtualGeometryPool.register` refuses a container that does not promise it, and
+ * {@link vgeo_runtime_page_slot_words} turns that promise into a stride. A page whose rows do not
+ * fit the stride is refused; see that function for why the stride is a choice and what it was
+ * measured against.
+ *
+ * The page's own header is the first {@link VGEO_PAGE_ROW_WORDS} words of its slot rather than a
+ * row of a second table, which saves the traversal a storage binding it does not have to spare
+ * (RUNTIME_PLAN §4.9) and makes an install one contiguous range.
+ *
+ * ## This tier answers its own activation question
+ *
+ * {@link refresh_selectable} computes selectability from the arena and the lookup — this tier's
+ * residency — and consults no reader. It used to publish `VGeoContainerReader.is_selectable`, which
+ * is a fact about the **RAM** tier, into the flag the kernel reads while the descent was gated on
+ * the **VRAM** lookup. VRAM is a strict subset, so a group could be flagged selectable while a page
+ * holding one of its parents had no row here, and the parent's own ancestor then drew a coarse
+ * stand-in over the surface the group was drawing. That is REVIEW_LEDGER C1, and what closes it is
+ * the group row carrying its parent count (VGEO_GROUP_ROW_OFFSET.PARENT_COUNT) so that the rule
+ * can be evaluated where the residency it is about lives.
+ *
+ * **Nothing here decides anything.** What to install, what to evict — all of that is the pool's.
+ * What this refuses is only what it cannot represent.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoRuntimeTables {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.page_capacity] slots
+     * @param {number} [options.page_size] bytes a page of every container held here is bounded by;
+     *     what the slot stride is derived from
+     * @param {number} [options.slot_words] the stride itself, overriding the derivation
+     * @param {number} [options.lookup_words]
+     * @param {number} [options.geometry_capacity] rows
+     */
+    constructor({ page_capacity, page_size, slot_words, lookup_words, geometry_capacity, }?: {
+        page_capacity?: number;
+        page_size?: number;
+        slot_words?: number;
+        lookup_words?: number;
+        geometry_capacity?: number;
+    });
+    /**
+     * @returns {Uint32Array}
+     */
+    get lookup_words(): Uint32Array;
+    /**
+     * @returns {Uint32Array}
+     */
+    get arena_words(): Uint32Array;
+    /**
+     * @returns {Uint32Array}
+     */
+    get geometry_words(): Uint32Array;
+    /**
+     * @returns {number}
+     */
+    get broken_child_refs(): number;
+    /**
+     * @returns {number}
+     */
+    get slot_words(): number;
+    /**
+     * @returns {number}
+     */
+    get page_capacity(): number;
+    /**
+     * One past the highest page row ever handed out — what sizes a per-page-row stamp region.
+     * @returns {number}
+     */
+    get page_row_high_water(): number;
+    /**
+     * @returns {number}
+     */
+    get resident_page_count(): number;
+    /**
+     * Whether a row could take a page without anything being evicted first.
+     * @returns {boolean}
+     */
+    get has_free_page_row(): boolean;
+    /**
+     * How many times this row has been freed — the token that tells a feedback record about the
+     * page that *was* here from one about the page that is.
+     *
+     * @param {number} page_row
+     * @returns {number}
+     */
+    generation_of(page_row: number): number;
+    /**
+     * Give a container a geometry row and a page lookup of its own.
+     *
+     * The lookup is `total_pages` words and starts entirely absent, which is the correct state for
+     * a container nothing has been installed from: every cluster that refers into it clamps, draws
+     * coarse, and wants.
+     *
+     * @param {number} page_count the container's `total_pages`
+     * @param {number} [ordinal_capacity] initial claim width; grown by installs
+     * @returns {number} geometry row
+     * @throws {Error} when the lookup does not fit
+     */
+    register_geometry(page_count: number, ordinal_capacity?: number): number;
+    /**
+     * Drop a geometry: every page it has here, then its lookup and its row.
+     *
+     * @param {number} geometry_row
+     * @returns {number[]} the page rows that were evicted, so a caller holding per-row state can
+     *     drop it too
+     */
+    unregister_geometry(geometry_row: number): number[];
+    /**
+     * @param {number} geometry_row
+     * @param {number} field one of {@link VGEO_GEOMETRY_ROW_OFFSET}
+     * @returns {number}
+     */
+    geometry_field(geometry_row: number, field: number): number;
+    /**
+     * @param {number} geometry_row
+     * @param {number} page_index container page index
+     * @returns {number} page row, or {@link VGEO_PAGE_ROW_NONE}
+     */
+    page_row_of(geometry_row: number, page_index: number): number;
+    /**
+     * @param {number} page_row
+     * @param {number} field one of {@link VGEO_PAGE_ROW_OFFSET}
+     * @returns {number}
+     */
+    page_field(page_row: number, field: number): number;
+    /**
+     * Word offset of a page's node rows — the slot, past its header.
+     *
+     * @param {number} page_row
+     * @returns {number}
+     */
+    node_base(page_row: number): number;
+    /**
+     * @param {number} page_row
+     * @returns {number}
+     */
+    group_base(page_row: number): number;
+    /**
+     * @param {number} page_row
+     * @returns {number}
+     */
+    cluster_base(page_row: number): number;
+    /**
+     * Make a decoded page resident: one slot, one lookup word.
+     *
+     * The page installs **not selectable** — every group's flag is clear — because a page that
+     * arrives drawing is a page that draws before the ancestors it hangs off have. Activation is
+     * {@link refresh_selectable}.
+     *
+     * @param {number} geometry_row
+     * @param {VGeoPage} page as `vgeo_read_page` decoded it
+     * @param {number} meshlet_base row of this page's cluster 0 in the meshlet metadata pool
+     * @returns {number} page row
+     * @throws {Error} when no slot is free — the caller's cue to evict, since what to drop is a
+     *     budget question and this object holds no budget — or when the page's rows do not fit one
+     * @see broken_child_refs for what the last install reported about the page it wrote
+     */
+    install(geometry_row: number, page: VGeoPage, meshlet_base: number): number;
+    /**
+     * How many words of a slot an install of this page would take, header included.
+     *
+     * @param {VGeoPage} page
+     * @returns {number}
+     */
+    slot_words_for(page: VGeoPage): number;
+    /**
+     * Drop a resident page.
+     *
+     * The lookup word goes back to {@link VGEO_PAGE_ROW_NONE} first, and that single word is the
+     * whole of what makes the eviction safe: every cluster anywhere that refines into this page
+     * reads it, finds nothing, and clamps — drawing the coarser surface it was already drawing
+     * before the page arrived. Nothing is patched and nothing is scanned.
+     *
+     * The slot's **header** is zeroed and its rows are not. A row nothing points at is unreachable
+     * — the lookup is the only way in and no queue item survives a frame — and leaving the rows
+     * costs nothing while zeroing them would dirty a slot's worth of words per eviction.
+     *
+     * @param {number} page_row
+     * @returns {boolean} whether the row was resident
+     */
+    evict(page_row: number): boolean;
+    /**
+     * The page rows this geometry holds, which is also what an eviction candidate's children are
+     * looked for among.
+     *
+     * @param {number} geometry_row
+     * @returns {Set<number>}
+     */
+    pages_of(geometry_row: number): Set<number>;
+    /**
+     * Whether any page resident **in this tier** refines out of this one.
+     *
+     * Design §6's eviction rule reads "no child page resident in this tier", and this answers it out
+     * of the arena rather than out of the RAM reader's child table — which returned "no children"
+     * the moment the RAM tier dropped the page, orphaning every VRAM-resident child under it
+     * (REVIEW_LEDGER M9).
+     *
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    has_resident_child(page_row: number): boolean;
+    /**
+     * Recompute one geometry's group selectability over **this tier's** residency.
+     *
+     * `VIRTUAL_GEOMETRY_DESIGN.md` §6: a group is selectable iff every one of its parent-cluster
+     * references is live — the referencing cluster's page resident here, and that cluster's own
+     * group selectable here. Groups with no parents at all are the top of the DAG and are selectable
+     * the moment their page is. That is a closure over the resident set, so it is computed as one:
+     * seed the parentless groups and cascade down, counting a reference only when the group making
+     * it is already selectable.
+     *
+     * Recomputed whole rather than propagated incrementally, because an install can turn groups on
+     * several pages away and an eviction can turn them off again, and because the cost is the same
+     * order as the install that provoked it — one pass over the geometry's resident clusters. The
+     * incremental form is a later optimization with a counter to keep correct; the one thing it
+     * must not be is a *second* implementation of the rule.
+     *
+     * @param {number} geometry_row
+     * @returns {number[]} page rows whose group flags changed, for the caller to upload
+     */
+    refresh_selectable(geometry_row: number): number[];
+    /**
+     * Publish one group's selectability directly.
+     *
+     * {@link refresh_selectable} is what a runtime calls; this is for a spec that needs a state the
+     * rule happens not to produce on the assets measured so far — the cut's own-group term is
+     * correctness for exactly such a state, and a guard nothing can construct is a guard nothing can
+     * test. The next {@link refresh_selectable} overwrites it.
+     *
+     * @param {number} page_row
+     * @param {number} group
+     * @param {boolean} selectable
+     * @returns {void}
+     */
+    set_group_selectable(page_row: number, group: number, selectable: boolean): void;
+    /**
+     * @param {number} page_row
+     * @param {number} group
+     * @returns {boolean}
+     */
+    is_group_selectable(page_row: number, group: number): boolean;
+    /**
+     * Word range of one page's slot, as `[start, count]` — what an install dirties.
+     *
+     * @param {number} page_row
+     * @returns {number[]}
+     */
+    slot_range(page_row: number): number[];
+    /**
+     * Word range of one page's group rows — what an activation pass dirties.
+     *
+     * @param {number} page_row
+     * @returns {number[]}
+     */
+    group_range(page_row: number): number[];
+    /**
+     * Republish one page's meshlet base, after the shared meshlet pool relocated its batch.
+     *
+     * @param {number} page_row
+     * @param {number} meshlet_base
+     * @returns {boolean} whether it moved
+     */
+    set_meshlet_base(page_row: number, meshlet_base: number): boolean;
+    #private;
+}
+//# sourceMappingURL=VGeoRuntimeTables.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoRuntimeTables.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IA+II;;;;;;;;OAQG;IACH;QAP4B,aAAa,GAA9B,MAAM;QACW,SAAS,GAA1B,MAAM;QAEW,UAAU,GAA3B,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,iBAAiB,GAAlC,MAAM;OA4BhB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,8BALW,MAAM,qBACN,MAAM,GACJ,MAAM,CAgDlB;IAED;;;;;;OAMG;IACH,kCAJW,MAAM,GACJ,MAAM,EAAE,CA8CpB;IAED;;;;OAIG;IACH,6BAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,0BAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,qBAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;;;;;;;OAcG;IACH,sBARW,MAAM,gCAEN,MAAM,GACJ,MAAM,CAkElB;IAED;;;;;OAKG;IACH,gCAFa,MAAM,CAMlB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAHW,MAAM,GACJ,OAAO,CAmCnB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,IAAI,MAAM,CAAC,CAIvB;IAED;;;;;;;;;;OAUG;IACH,6BAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,iCAHW,MAAM,GACJ,MAAM,EAAE,CAgIpB;IAED;;;;;;;;;;;;OAYG;IACH,+BALW,MAAM,SACN,MAAM,cACN,OAAO,GACL,IAAI,CAQhB;IAED;;;;OAIG;IACH,8BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,GACJ,MAAM,EAAE,CAYpB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;IAED;;;;;;OAMG;IACH,2BAJW,MAAM,gBACN,MAAM,GACJ,OAAO,CAYnB;;CA4DJ"}