@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -0,0 +1,120 @@
+/**
+ * The other half of the loop: what the cut saw, coming back to the host.
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §6 sets the contract and the virtual-texture system is the shipped
+ * precedent for it — a small in-flight cap, multi-frame `mapAsync` latency, and **frames where
+ * feedback is skipped entirely** when saturated. A loop that insisted on a reading every frame
+ * would stall the frame it was reading, which is the failure the cap exists to prevent.
+ *
+ * What comes back is two lists and a counter block:
+ *
+ * - **touches** — page rows the cut drew from. They go to the VRAM pool's LRU and to
+ *   `VGeoResidencyManager`'s, which is design §6's touch-LRU at both tiers. Not last-*wanted*:
+ *   stamping at fetch time freezes the stamp of exactly what is on screen and evicts it.
+ * - **wants** — pages a clamped cluster could not reach, each naming the page it was discovered
+ *   *through*. That second half is what resolves the byte range without a directory, and it is
+ *   also the page format §10 asks to be pinned while its child is in flight.
+ *
+ * A want resolves to one of two very different things, and telling them apart is this class's real
+ * work. A page already in RAM is a **VRAM install** and no fetch at all — the bytes are here and
+ * the cut simply has not been given them. A page not in RAM is a fetch, handed to the residency
+ * manager with its priority so that it competes globally against every other asset's wants rather
+ * than within whichever reader asked first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoFeedbackLoop {
+    /**
+     * @param {Object} options
+     * @param {GPUVirtualGeometryRuntime} options.runtime
+     * @param {VGeoResidencyManager} options.residency the RAM tier's budget owner
+     * @param {number} [options.max_in_flight] readbacks that may be outstanding at once
+     * @param {number} [options.install_budget_bytes] decoded page bytes promoted to VRAM per frame
+     * @param {number} [options.max_wants_per_frame] pages one frame may newly ask to fetch, across
+     *     every reader — see {@link #dispatch_frame}, which is where the "across every reader" is
+     *     enforced; the rest are dropped and asked for again next frame, which is what a want is
+     *     for
+     */
+    constructor({ runtime, residency, max_in_flight, install_budget_bytes, max_wants_per_frame, }: {
+        runtime: GPUVirtualGeometryRuntime;
+        residency: VGeoResidencyManager;
+        max_in_flight?: number;
+        install_budget_bytes?: number;
+        max_wants_per_frame?: number;
+    });
+    /**
+     * Feedback records naming a page row that had been re-used by the time the reading landed.
+     * @returns {number}
+     */
+    get stale_record_count(): number;
+    /**
+     * Wants this loop did not re-submit because the page was already being fetched.
+     * @returns {number}
+     */
+    get deduped_want_count(): number;
+    /**
+     * Wants past this frame's fetch limit. Not a failure — the next cut asks again.
+     * @returns {number}
+     */
+    get dropped_want_count(): number;
+    /**
+     * Batches every page of which the reader quarantined, plus any that rejected outright.
+     *
+     * A reader that has stopped answering is the one streaming failure a host can do something
+     * about, and it is the one thing a per-page quarantine cannot say on its own.
+     *
+     * @returns {number}
+     */
+    get failed_batch_count(): number;
+    /**
+     * @returns {Uint32Array}
+     */
+    get stats(): Uint32Array;
+    /**
+     * Frames whose feedback was dropped because the loop was saturated.
+     *
+     * Not an error and not a leak: the clamped cut keeps a coarse stand-in correct indefinitely, so
+     * a skipped frame costs latency in the streaming and nothing in what is on screen.
+     *
+     * @returns {number}
+     */
+    get skipped_frames(): number;
+    /**
+     * @returns {number}
+     */
+    get read_count(): number;
+    /**
+     * @returns {number}
+     */
+    get last_want_count(): number;
+    /**
+     * @returns {number}
+     */
+    get last_touch_count(): number;
+    /**
+     * Schedule this frame's readback, while the graph is still being built.
+     *
+     * @param {FrameGraph} graph
+     * @returns {boolean} whether a reading was scheduled
+     */
+    read(graph: FrameGraph): boolean;
+    /**
+     * Stop every fetch this loop started.
+     *
+     * @returns {void}
+     */
+    abort(): void;
+    /**
+     * Give up on this loop: the same as {@link abort}, under the name a host tears things down by.
+     *
+     * The loop owns no device resource, so there is nothing else to release — what it owns is
+     * outstanding *work*, and the reason to have this verb at all is that `abort` reads like a
+     * transient control ("stop what is in flight, carry on") while a teardown is final.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=VGeoFeedbackLoop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA+FI;;;;;;;;;;OAUG;IACH;QAT8C,OAAO;QACZ,SAAS;QACtB,aAAa,GAA9B,MAAM;QACW,oBAAoB,GAArC,MAAM;QACW,mBAAmB,GAApC,MAAM;OAoBhB;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,yBAFa,OAAO,CAqEnB;IAqVD;;;;OAIG;IACH,SAFa,IAAI,CAShB;IAED;;;;;;;;OAQG;IACH,WAFa,IAAI,CAIhB;;CACJ"}