@woosh/meep-engine 3.28.0 → 3.29.0

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts

@@ -1,3 +1,41 @@
+/**
+ * The most records one {@link GPUMeshletManager#sweep} moves. A move is an O(1) slide in the
+ * allocator, four copy encodes, `meshlet_count` pairs in a patch table and one `changed`
+ * dispatch, so this bounds the main-thread cost of a sweep per frame by a count that does not
+ * grow with the resident set (COMPACTION_PLAN_2026_09_16 §3, §4.3).
+ * @type {number}
+ */
+export const MESHLET_SWEEP_MOVE_BUDGET: number;
+/**
+ * The most words one sweep copies, data and rows together — 4 MB of GPU copy through the staging
+ * buffer. Whichever of the two budgets is met first ends the call, but never before one move
+ * when one is possible: a single record larger than this still moves, once.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_WORD_BUDGET: number;
+/**
+ * The most cursor steps one sweep takes, moves or not. A step that moves nothing — a hole the
+ * cursor was stepped back for that an allocation has since filled — is a link walk.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_STEP_BUDGET: number;
+/**
+ * A removal that leaves at least this much of an arena free *in pieces* — free space less the
+ * largest free run — and at least an eighth of the arena that way, arms the sweep by itself.
+ *
+ * A sweep armed only by a refusal reclaims the space after the growth it could have prevented,
+ * and the next fill carves that tail before the next large arrival. Armed on scatter, the tail
+ * is clear by the time something needs it, at a cost bounded per frame as ever and proportional
+ * to the churn in total. Under a churn of one class the holes are recycled as fast as they are
+ * made and the scatter stays below the eighth; this is for a pool that thins.
+ * In words for the data arena; the row arena's floor is {@link MESHLET_SWEEP_SCATTER_MINIMUM_ROWS}.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_SCATTER_MINIMUM_WORDS: number;
+/**
+ * @type {number}
+ */
+export const MESHLET_SWEEP_SCATTER_MINIMUM_ROWS: number;
 export class GPUMeshletManager {
     /**
      *
@@ -5,14 +43,21 @@ export class GPUMeshletManager {
      * @param {GPUDevice} options.device
      * @param {number} [options.initial_data_capacity] in bytes
      * @param {number} [options.initial_metadata_capacity] in meshlets
+     * @param {number} [options.allocation_limit] node budget of each arena — the most ranges, live
+     *        and free together, either can describe. Growth never raises it; a rebuild re-picks it.
      */
-    constructor({ device, initial_data_capacity, initial_metadata_capacity, }: {
+    constructor({ device, initial_data_capacity, initial_metadata_capacity, allocation_limit, }: {
         device: GPUDevice;
         initial_data_capacity?: number;
         initial_metadata_capacity?: number;
+        allocation_limit?: number;
     });
     get buffer_data(): GPUBuffer;
     get buffer_metadata(): GPUBuffer;
+    /**
+     * @returns {Readonly<GPUMeshletManagerStats>}
+     */
+    get stats(): Readonly<GPUMeshletManagerStats>;
     compact(): void;
     /**
      * Enlarge the data and metadata arenas, leaving every batch exactly where it is.
@@ -23,8 +68,8 @@ export class GPUMeshletManager {
      * re-patching, and no {@link MeshletBatchAllocationRecord#changed} fires. Compare {@link compact},
      * which makes room by re-packing instead, and pays all three of those for every record it moves.
      *
-     * Growing closes no holes, which is why it leaves {@link #deallocations_since_last_rebuild}
-     * alone: the holes it did not close are still there for a later {@link compact} to close.
+     * Growing closes no holes: the holes it did not close are still there for the sweep, or a
+     * later {@link compact}, to close.
      *
      * The arena an allocator is asked for is {@link OffsetAllocator#grow_target_for}, not the
      * shortfall: room for exactly `extra_data_size` can still be refused the allocation that asked
@@ -39,8 +84,7 @@ export class GPUMeshletManager {
     grow(extra_data_size: number, extra_metadata_size: number): void;
     /**
      * Release a batch allocation back to the data and metadata allocators. The GPU bytes are
-     * not cleared — the freed slices are reclaimed lazily by the next {@link compact} (a
-     * deallocation bumps the compaction counter the allocator consults under pressure).
+     * not cleared — the freed slices are handed to whoever asks next, or closed by a sweep.
      * Other batches' allocations are unaffected (the OffsetAllocator frees disjoint slices),
      * so callers only need to ensure nothing still references this batch's metadata rows
      * (the geometry table rebuild in {@link GPUGeometryManager} handles that).
@@ -50,6 +94,36 @@ export class GPUMeshletManager {
      * @returns {boolean} true if the record was owned and freed
      */
     remove_batch(record: MeshletBatchAllocationRecord): boolean;
+    /**
+     * One budgeted step of the compaction of both arenas, recorded into `cmd_ctx`.
+     *
+     * Nothing happens unless a fragmentation refusal has armed a sweep (see
+     * {@link #allocate_data_and_metadata}). Then, in each arena, the cursor walks up the used
+     * ranges sliding each down over the free space before it — which gathers every hole passed
+     * into one run just behind the cursor — until {@link MESHLET_SWEEP_MOVE_BUDGET} records or
+     * {@link MESHLET_SWEEP_WORD_BUDGET} words have moved (never fewer than one when one can) or
+     * {@link MESHLET_SWEEP_STEP_BUDGET} steps have been taken, across both arenas. The sweep is
+     * done when the cursor reaches the arena's end: all free space is one run at the tail, and
+     * the episode is over.
+     *
+     * A moved record's bytes — data and rows alike — go through a transient staging buffer in
+     * two `copyBufferToBuffer`s: WebGPU refuses a same-buffer copy, the intra-copy shader the
+     * clone flush uses is not overlap-safe, and a slide by less than a record's size overlaps.
+     * Rows are copied rather than re-derived from the batch's bytes because the skinning bounds
+     * chain writes into clone rows on the device every frame. A data move then patches the
+     * moved rows' `address` with the clone flush's shader. Every move is recorded in cursor
+     * order, so a record sliding into space another vacated earlier in the same call reads what
+     * that record's copy already wrote out. `changed` fires once per moved record after the
+     * whole batch is recorded, with the new offsets on the record.
+     *
+     * The renderer calls this once per frame, at the head of the frame, before
+     * {@link update}, so the clone flush reads post-sweep offsets and every pass reads rows and
+     * data that agree. Until `cmd_ctx` finishes the manager refuses to allocate, free, grow or
+     * rebuild — a recorded copy names ranges that must stay what they are until it runs.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    sweep(cmd_ctx: ShadeGPUCommandContext): void;
     /**
      * Allocate a fresh (data, metadata) pair sized to mirror `source`,
      * and queue a GPU-side clone: the source's data and metadata are
@@ -99,12 +173,33 @@ export class GPUMeshletManager {
     add_batch(batch: MeshletBatch): MeshletBatchAllocationRecord;
     debug_dump_metadata(): Promise<[]>;
     get gpu_memory_usage_occupied(): number;
+    /**
+     * Bytes the arenas have handed out: every batch's range rounded to its bin, data and metadata
+     * both. Above {@link gpu_memory_usage_occupied} by the quantization overhead — 3.4 % of data
+     * and 3.9 % of rows on page-shaped batches, at most 12.5 % on any.
+     *
+     * @returns {number}
+     */
+    get gpu_memory_usage_reserved(): number;
     get gpu_memory_usage(): number;
     #private;
 }
 export type Allocation = import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
 export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
 export type MeshletBatch = import("./MeshletBatch.js").MeshletBatch;
+/**
+ * What the manager has done to its arenas, for a bench, a tour or an overlay to read without
+ * reaching inside. A rebuild is the O(all batches) event the compaction plan is about; a growth
+ * is the bounded alternative; the sweep counters are COMPACTION_PLAN_2026_09_16 §4.7's.
+ */
+declare class GPUMeshletManagerStats {
+    growths: number;
+    rebuilds: number;
+    moves: number;
+    sweeps_armed: number;
+    sweeps_completed: number;
+    moves_last_sweep: number;
+}
 declare class MeshletBatchAllocationRecord {
     /**
      * @type {Allocation}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAuFA;IA4EI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAkChB;IAhGD,6BAEC;IAOD,iCAEC;IAuFD,gBAKC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QAuHhB;IAoRD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAkBnB;IAgCD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBAp5BY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6BrD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}
+{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAwDA;;;;;;GAMG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,wCAFU,MAAM,CAEqC;AAErD;;;;GAIG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;GAWG;AACH,kDAFU,MAAM,CAE6C;AAE7D;;GAEG;AACH,iDAFU,MAAM,CAEsC;AAqGtD;IA8II;;;;;;;;OAQG;IACH;QAN8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;QACW,gBAAgB,GAAjC,MAAM;OAuChB;IAxKD,6BAEC;IAOD,iCAEC;IAwED;;OAEG;IACH,8CAEC;IAkFD,gBAOC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QA2HhB;IA8WD;;;;;;;;;;OAUG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,eAFW,sBAAsB,QAqChC;IAiND;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CAiCxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED;;;;;;OAMG;IACH,wCAMC;IAED,+BAYC;;CACJ;yBAv/CY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AAiFrD;;;;GAIG;AACH;IACI,gBAAY;IACZ,iBAAa;IACb,cAAU;IACV,qBAAiB;IACjB,yBAAqB;IACrB,yBAAqB;CACxB;AAmDD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}