@woosh/meep-engine 3.33.0 → 3.34.0

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

@@ -1,7 +1,3 @@
-/**
- * @typedef {import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool} GPUVirtualGeometryPool
- * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- */
 /**
  * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
  * every view writes into, and the parameters every pass reads.
@@ -12,9 +8,16 @@
  * virtual geometry is view-dependent by construction — but everything here is shared between them,
  * which is exactly what §4 means by "the setup is shared rather than the result".
  *
- * **The feedback buffer is per frame and not per invocation**, and that is what dedups a touch
- * across the buckets and passes a frame is split into. Each expansion site gets its own claim
- * bitmask (different instance sets) and writes into this one buffer.
+ * **A frame spans every graph of a render.** The renderer opens it before the shadow maps are drawn
+ * and closes it after the main view's graph is recorded, and each shadow map records into a
+ * `FrameGraph` of its own (SHADOW_PLAN_2026_09_28 §2.1). So the feedback buffer is not a transient of
+ * any one graph: it is a buffer this runtime owns, **imported** into each graph that cuts, and the
+ * first graph of a frame to import it clears it. Graphs are encoded in the order they are recorded
+ * into one encoder, which is the only ordering the frame needs between them.
+ *
+ * **Every view that cuts takes a slot** (§2.4): its own counters, its own want slice and its own
+ * stamp tag, so one view's list running out cannot silence another's, and a reading can say which
+ * view needed more wavefronts. The view the frame is opened for is slot 0.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -30,7 +33,7 @@ export class GPUVirtualGeometryRuntime {
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
      * @param {number} [options.max_iterations] wavefronts before the descent is abandoned, to start
-     *     with; the runtime raises it from what the cut reports
+     *     with; each view raises its own from what its cut reports
      * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
      *     before handing back what it still holds; see the traversal kernel for why it cannot
@@ -48,6 +51,7 @@ export class GPUVirtualGeometryRuntime {
     });
     /**
      * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
+     * A view cuts at this times its own {@link VGeoViewCut#tau_scale}.
      * @type {number}
      */
     tau: number;
@@ -74,60 +78,22 @@ export class GPUVirtualGeometryRuntime {
      */
     get claim_word_capacity(): number;
     /**
-     * Wavefronts the descent may run, as the runtime currently understands this scene.
-     *
-     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
-     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
-     * reads it while it is recording passes, so a rise lands on the next frame.
+     * Wavefronts a view's descent starts with — each view raises its own from what its cut reports
+     * (`VGeoViewCut.note_incomplete_descent`), and cuts at the larger of the two.
      *
      * @returns {number}
      */
     get max_iterations(): number;
     /**
-     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
-     * number, once, for one that needed more than it was given.
+     * As far as a view's wavefront bound may be raised.
      *
      * @returns {number}
      */
-    get iteration_escalations(): number;
-    /**
-     * @returns {number}
-     */
     get iteration_ceiling(): number;
-    /**
-     * A reading saying the descent stopped with work still queued — raise the bound and keep it
-     * raised.
-     *
-     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
-     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
-     * render target together; the kernel cannot know it before it runs and the host cannot know it
-     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
-     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
-     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
-     * before the expansion runs either and are grown from what the frame reported.
-     *
-     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
-     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
-     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
-     * most three steps from 8 to the ceiling.
-     *
-     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
-     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
-     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
-     * which is the cheap side of that trade.
-     *
-     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
-     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
-     * between the first truncated descent and the reading that reports it — and then never again.
-     *
-     * @param {number} remaining items the descent still held when it was abandoned
-     * @returns {boolean} whether the bound moved
-     */
-    note_incomplete_descent(remaining: number): boolean;
     /**
      * Settable, like tau, and for the same reason: it is a quality-of-schedule dial whose right
      * value is a property of the asset's depth and the scene's breadth together rather than of the
-     * engine. `begin_frame` re-writes the params every frame, so a change lands on the next one.
+     * engine. Every view writes its params at record time, so a change lands on the next frame.
      *
      * @param {number} value
      */
@@ -139,47 +105,43 @@ export class GPUVirtualGeometryRuntime {
      */
     get descent_steps(): number;
     /**
-     * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
-     * @returns {number}
+     * Whether a frame is open — whether a rasterization path recording now may cut.
+     *
+     * @returns {boolean}
      */
-    get feedback(): number;
+    get frame_open(): boolean;
     /**
-     * Hand back the version of the feedback resource that an expansion left behind.
-     *
-     * A frame is cut once per bucket per HZB pass per view, and every one of those writes into the
-     * *same* feedback buffer — which is exactly what dedups a touch across them. But a FrameGraph
-     * resource is versioned: the handle `begin_frame` created is version 0, and a second expansion
-     * that wrote version 0 again after the first had produced version 65 would be reading stale
-     * contents while claiming not to. The graph says so, loudly, and it is right to.
+     * The view the last frame was opened for, which is slot 0 of that frame's feedback.
      *
-     * So the runtime carries the *current* version and each expansion publishes what it produced.
-     * The readback then reads the last one, which is the only version that has seen every view.
+     * @returns {VGeoViewCut|undefined}
+     */
+    get frame_view(): import("./VGeoViewCut.js").VGeoViewCut;
+    /**
+     * The feedback buffer every view of a frame writes into, or null before the first frame and
+     * after {@link destroy}.
      *
-     * @param {number} handle
-     * @returns {void}
+     * @returns {GPUBuffer|null}
      */
-    publish_feedback(handle: number): void;
+    get feedback_buffer(): any;
     /**
      * @returns {ReturnType<vgeo_cut_feedback_layout>}
      */
     get feedback_layout(): {
+        slot_count: number;
         touch_bits_base: number;
-        /**
-         * @type {number}
-         */
         touch_word_count: number;
         want_base: number;
-        word_count: number; /**
-         * @type {number}
-         */
+        slot_want_capacity: number;
+        clear_word_count: number;
+        word_count: number;
     };
     /**
-     * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
-     * write the parameters every pass of every view will read.
+     * Open a frame: publish the page tables, lay the feedback buffer out for the views the frame is
+     * expected to have, and take slot 0 for the view it is rendered for.
      *
-     * The sizing happens here rather than at construction because one of its terms moves with
-     * residency — one touch bit per page-table row — and a frame is the coarsest granularity at
-     * which it holds still.
+     * The sizing happens here rather than at construction because two of its terms move — one
+     * touch bit per page-table row follows residency, and the slot count follows the most views any
+     * frame has cut in — and a frame is the coarsest granularity at which they hold still.
      *
      * **The pool's frame advances here, before the flush**, and not at `end_frame`. The frame
      * number is what stamps a page row's `visible_from` — the frame whose flush publishes the
@@ -188,18 +150,72 @@ export class GPUVirtualGeometryRuntime {
      * frame's reading, exactly (RUNTIME_PLAN_2026_09_14 §2.4). It is also the clock both tiers'
      * protect windows read, and it moves whether or not a readback is scheduled this frame.
      *
-     * **A frame has no projection.** It used to take one, and wrote it into a params buffer
-     * every view then shared — so a shadow cascade cut against whichever view opened the
-     * frame. `projection_k` is a property of a render target and a camera, which is to say of
-     * a view, and it lives on {@link VGeoViewCut} with the rest of what a view owns alone.
+     * **A frame has no projection and no graph.** Each view writes its own projection
+     * ({@link VGeoViewCut}), and each graph that cuts imports the feedback buffer itself
+     * ({@link feedback_in}).
+     *
+     * Opening a frame that is already open starts it again: a render that threw before closing its
+     * frame leaves nothing behind that the next one can be confused by.
      *
      * @param {Object} options
-     * @param {FrameGraph} options.graph
-     * @returns {number} the feedback resource
+     * @param {VGeoViewCut} options.view the view the frame is rendered for
+     * @returns {void}
      */
-    begin_frame({ graph }: {
-        graph: FrameGraph;
-    }): number;
+    begin_frame({ view }: {
+        view: VGeoViewCut;
+    }): void;
+    /**
+     * This frame's slot for a view, taking the next one the first time the view cuts in the frame.
+     *
+     * A view past the slots the frame was laid out for shares the last one — never slot 0, which is
+     * the frame's own view's — and the next frame is laid out with room for it. A shared slot's
+     * counters are the sum of its views', so its reading lands on each of them but escalates none
+     * (see `VGeoFeedbackLoop`).
+     *
+     * @param {VGeoViewCut} view
+     * @returns {number}
+     */
+    slot_of(view: VGeoViewCut): number;
+    /**
+     * The tag a slot's view writes into the want stamps, unique to that view in this frame and never
+     * zero — see `VGEO_CUT_PARAMS_STRUCT.frame_tag`.
+     *
+     * @param {number} slot
+     * @returns {number}
+     */
+    frame_tag_of(slot: number): number;
+    /**
+     * This frame's views, by slot — what a reading of this frame's feedback is about. A copy, since
+     * the reading lands frames later and the table is rebuilt every frame.
+     *
+     * @returns {VGeoViewCut[][]}
+     */
+    frame_slots(): VGeoViewCut[][];
+    /**
+     * The feedback buffer as a resource of `graph`, at the version that graph last wrote.
+     *
+     * The first call for a graph imports the buffer into it; if no graph of this frame has yet, it
+     * also records the clear — the counters and the touch bits, which is everything a kernel adds
+     * to — so the first graph encoded is the one that clears, before anything of this frame writes.
+     *
+     * @param {FrameGraph} graph
+     * @returns {number} resource handle
+     */
+    feedback_in(graph: FrameGraph): number;
+    /**
+     * Hand back the version of the feedback resource a graph's expansion left behind.
+     *
+     * A FrameGraph resource is versioned: the handle an import produced is its first version, and a
+     * second expansion that wrote that version again after the first had produced a later one would
+     * be reading stale contents while claiming not to. The graph says so, loudly, and it is right to.
+     * So the runtime carries each graph's current version and each expansion publishes what it
+     * produced; the readback then reads the last one.
+     *
+     * @param {FrameGraph} graph
+     * @param {number} handle
+     * @returns {void}
+     */
+    publish_feedback(graph: FrameGraph, handle: number): void;
     /**
      * What one expansion site was handed, folded into the parameters every pass of the frame reads.
      *
@@ -208,10 +224,9 @@ export class GPUVirtualGeometryRuntime {
      * defaulted to 1 << 20 against a meshlet collection whose engine default is 2e5, so `vg_draw`
      * bounds-checked against a number five times the buffer it was writing into (REVIEW_LEDGER M6).
      *
-     * One params buffer serves the whole frame, so a frame with sites of different sizes takes the
-     * **minimum** — conservative, and the direction every other bound in the cut fails in. Written
-     * at record time, like everything else here, so the last value published before submit is what
-     * every pass of the frame executes against.
+     * A frame with sites of different sizes takes the **minimum** — conservative, and the direction
+     * every other bound in the cut fails in. Each view writes its params at record time from what
+     * has been declared so far, which is never more than its own site was handed.
      *
      * @param {Object} options
      * @param {number} options.instance_capacity records the VG instance buffer holds
@@ -231,26 +246,25 @@ export class GPUVirtualGeometryRuntime {
      */
     get meshlet_capacity(): number;
     /**
-     * The graph this frame was opened on.
-     *
-     * A cut writes into the feedback resource `begin_frame` created, and a resource handle belongs
-     * to one graph — so a rasterization path running on a *different* graph inside the same frame
-     * (a shadow view builds its own) would be naming a resource that graph has never heard of. The
-     * seam checks this and skips, which is also design §9's position: one cut per view, and shadow
-     * cuts are out of scope for v1.
+     * Close a frame. Nothing may cut until the next opens; reading it is {@link VGeoFeedbackLoop}'s,
+     * which schedules the readback while the last graph is still being recorded.
      *
-     * @returns {FrameGraph|undefined}
+     * @returns {void}
      */
-    get frame_graph(): import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    end_frame(): void;
     /**
-     * Close a frame. The feedback resource stops being valid; reading it is
-     * {@link VGeoFeedbackLoop}'s, which schedules the readback while the graph is still being built.
+     * Release the feedback buffer, which is the one device resource this makes, and close whatever
+     * frame is open so that nothing cuts into the buffer afterwards.
+     *
+     * The pool is not this runtime's to release: it was handed one, and whoever made it tears it
+     * down — after this, since a frame of this runtime writes into the pool's tables.
      *
      * @returns {void}
      */
-    end_frame(): void;
+    destroy(): void;
     #private;
 }
 export type GPUVirtualGeometryPool = import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
+export type VGeoViewCut = import("./VGeoViewCut.js").VGeoViewCut;
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 //# sourceMappingURL=GPUVirtualGeometryRuntime.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAkFI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAkFhB;IApID;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IA6HpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;OAQG;IACH,6BAEC;IAED;;;;;OAKG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,mCAHW,MAAM,GACJ,OAAO,CAanB;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvUA;;WAEG;;;4BAIH;;WAEG;MAiUF;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;QAH+B,KAAK,EAAzB,UAAU;QACR,MAAM,CA+BlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,wGAEC;IAGD;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;;CACJ;qCAteY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAiHI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAgFhB;IAzKD;;;;OAIG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAiKpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;;OAIG;IACH,gCAEC;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,yDAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;OAEG;IACH;;;;;;;;MAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH;QAHgC,IAAI,EAAzB,WAAW;QACT,IAAI,CAoChB;IAwBD;;;;;;;;;;OAUG;IACH,cAHW,WAAW,GACT,MAAM,CA0BlB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,eAFa,WAAW,EAAE,EAAE,CAI3B;IAED;;;;;;;;;OASG;IACH,mBAHW,UAAU,GACR,MAAM,CAkClB;IAED;;;;;;;;;;;;OAYG;IACH,wBAJW,UAAU,UACV,MAAM,GACJ,IAAI,CAOhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;IAED;;;;;;;;OAQG;IACH,WAFa,IAAI,CAOhB;;CACJ;qCArnBY,OAAO,6BAA6B,EAAE,sBAAsB;0BAC5D,OAAO,kBAAkB,EAAE,WAAW;yBACtC,OAAO,iEAAiE,EAAE,UAAU"}