@woosh/meep-engine 3.31.0 → 3.33.0

package/src/shade/renderer/animation/GPUAnimationManager.js

@@ -200,8 +200,8 @@ export class GPUAnimationManager {
      *
      * Lazily allocated on first {@link add_skin}; both grow together
      * by doubling. After a grow both buffers are zero-initialised and
-     * {@link #first_frame_skin_matrices} is set so the next prep
-     * dispatch seeds the "previous" buffer with a copy of the freshly
+     * {@link #skin_matrix_seed_all} is set so the next prep dispatch
+     * seeds all of the "previous" buffer with a copy of the freshly
      * written "current" — without this, the first velocity readback
      * after a grow would interpolate against zero matrices.
      *
@@ -217,15 +217,31 @@ export class GPUAnimationManager {
     #skin_matrices_current_index = 0;
 
     /**
-     * When true, the next prep dispatch will copy the freshly-written
-     * "current" buffer into the "previous" buffer at the end of the
-     * pass — set when a run of joints is handed out, when a pending
-     * skin's joints are named, and when the buffers grow, so the first
-     * velocity computation over those rows has matching prev/current
-     * matrices (zero velocity).
+     * The runs of matrix rows the next prep dispatch seeds "previous" from "current" over, each
+     * `[first_row, count]`: a run handed out, and a pending skin's run whose joints were just
+     * named. The frame before either is not a pose — "previous" over those rows holds zeros, or
+     * the last pose of a skin that had them — so the first velocity read over them has to see
+     * matching matrices, which is zero velocity.
+     *
+     * Only those rows: a settled skin's rows of "previous" hold its pose last frame, which is what
+     * its motion is measured from.
+     *
+     * A skin given back takes its queued runs with it ({@link unregister_skin}), so every run here
+     * belongs to a skin still registered and not yet seeded — however long no prep runs, as while
+     * a loading screen draws nothing and the game goes on spawning.
+     *
+     * @type {Array<[number, number]>}
+     */
+    #skin_matrix_seed_runs = [];
+
+    /**
+     * When true, the next prep dispatch seeds all of "previous" from "current", whatever
+     * {@link #skin_matrix_seed_runs} holds. Set when the buffers grow: both are made again,
+     * zeroed, so no row has a last frame left to keep.
+     *
      * @type {boolean}
      */
-    #first_frame_skin_matrices = true;
+    #skin_matrix_seed_all = false;
 
     /**
      * Capacity of each of {@link #skin_matrices_buffers} in matrices
@@ -1056,7 +1072,7 @@ export class GPUAnimationManager {
         // The joints' matrices are written from the next prep on, and "previous" over their rows
         // holds whatever was there before — zeros, or the last pose of a skin that had them — so
         // it is seeded, as it is for a run just handed out.
-        this.#first_frame_skin_matrices = true;
+        this.#skin_matrix_seed_runs.push([pending.joints_first, pending.joint_count]);
 
         return true;
     }
@@ -1436,10 +1452,34 @@ export class GPUAnimationManager {
             return;
         }
 
+        // Its rows go back owed no seed. Left queued, a run outlives its skin until the next prep,
+        // and while nothing draws that is every spawn since drawing stopped.
+        this.#drop_seed_runs(skins_table.get_word(skin_id, SKIN_JOINTS_FIRST_WORD));
+
         // The joints go with the skin — a pending skin's too, nodes or not.
         skins_table.remove(skin_id);
     }
 
+    /**
+     * Drop every queued seed run starting at `first_row`: the run of a skin being given back,
+     * queued when it was handed out, and again if its joints have been named since.
+     *
+     * No other skin's run can start there, since a skin's rows are its own until it is given back.
+     *
+     * @param {number} first_row
+     */
+    #drop_seed_runs(first_row) {
+        const runs = this.#skin_matrix_seed_runs;
+
+        // the prep sorts what it finds, so a dropped run's place goes to the last one
+        for (let i = runs.length - 1; i >= 0; i--) {
+            if (runs[i][0] === first_row) {
+                runs[i] = runs[runs.length - 1];
+                runs.pop();
+            }
+        }
+    }
+
     /**
      * Cached wrapper around {@link add_curve}: one upload per distinct curve, where distinct means
      * distinct *content*.
@@ -1541,25 +1581,31 @@ export class GPUAnimationManager {
         // its rows are fresh or some despawned skin's, so the next prep dispatch has to seed
         // "previous" from "current" for it.
         //
-        // This flag used to be set only inside #ensure_skin_matrices_capacity, i.e. only when the
-        // buffer actually grew. Rows given back by another skin never grow the buffer, and fresh
-        // rows below the current capacity hit that helper's early-out - so in both cases the
-        // `previous` buffer over the run still held either all-zero matrices or the last pose of
-        // the skin that had those rows before. The skinning pass reads
-        // `prev_skin_matrices[skin_base + j]` unconditionally, so the new character's first frame
-        // produced motion vectors from someone else's pose - a screen-crossing smear through TAA
-        // and motion blur - on exactly the spawn/despawn loop that reuses rows.
-        this.#first_frame_skin_matrices = true;
+        // Whether or not the buffers grew: rows given back by another skin never grow them, and
+        // neither do fresh rows below the capacity, so "previous" over the run holds all-zero
+        // matrices or the last pose of the skin that had those rows before. The skinning pass
+        // reads `prev_skin_matrices[skin_base + j]` unconditionally, so unseeded, the new
+        // character's first frame would take its motion vectors from someone else's pose — a
+        // screen-crossing smear through TAA and motion blur — on exactly the spawn/despawn loop
+        // that reuses rows.
+        this.#skin_matrix_seed_runs.push([joints_first, joints.length]);
 
         return joints_first;
     }
 
     /**
-     * Grow the skinning-matrix scratch buffer if `required_count`
-     * exceeds current capacity. Doubles on grow until the requirement
-     * fits. The buffer's contents are scratch (rewritten every frame by
-     * the prep pass), so growth doesn't need to copy old data — but it
-     * does invalidate the previous {@link #skin_matrices_buffer}
+     * Grow the skinning-matrix buffers if `required_count` exceeds
+     * current capacity. Doubles on grow until the requirement fits.
+     *
+     * Nothing is copied across. "Current" would be rewritten by the
+     * next prep anyway, but "previous" held every skin's pose last
+     * frame, which its motion is measured from: the grow loses that,
+     * and the next prep seeds all of "previous" from "current" instead
+     * ({@link #skin_matrix_seed_all}), so every skinned character has
+     * zero motion vectors for that one frame. Capacity doubles, so
+     * that is a handful of frames over a session.
+     *
+     * The grow also invalidates the {@link #skin_matrices_buffer}
      * reference, which is why callers re-fetch through the getter.
      *
      * @param {number} required_count number of matrices that must fit
@@ -1578,8 +1624,9 @@ export class GPUAnimationManager {
         // capacity. After grow both are zero-initialised, so the next
         // prep dispatch needs to seed "previous" from "current"
         // (otherwise velocity would interpolate against zero
-        // matrices). The flag below tells dispatch_skin_matrix_prep
-        // to issue that copy.
+        // matrices), and all of it: no row has a last frame left to
+        // keep. The flag below tells dispatch_skin_matrix_prep to
+        // issue that copy.
         for (let i = 0; i < 2; i++) {
             if (this.#skin_matrices_buffers[i] !== null) {
                 this.#skin_matrices_buffers[i].destroy();
@@ -1591,7 +1638,7 @@ export class GPUAnimationManager {
             });
         }
         this.#skin_matrices_capacity = new_capacity;
-        this.#first_frame_skin_matrices = true;
+        this.#skin_matrix_seed_all = true;
     }
 
     /**
@@ -1643,8 +1690,10 @@ export class GPUAnimationManager {
      * correct ping-pong behaviour across frames without leaking the
      * buffer-role bookkeeping into every caller.
      *
-     * No-op when the joints table has no rows to walk
-     * (`group_count_x === 0`).
+     * No-op when the joints table has no page for it to walk
+     * (`group_count_x === 0`), which is never while a skin is
+     * registered: a page emptied of joints goes at the next database
+     * update.
      *
      * Per-frame ordering:
      *  1. Flip {@link #skin_matrices_current_index}: last frame's
@@ -1652,11 +1701,12 @@ export class GPUAnimationManager {
      *     ({@link prev_skin_matrices_buffer}), and the buffer that
      *     held the frame before it becomes the write target.
      *  2. Dispatch the prep shader into the new "current".
-     *  3. If {@link #first_frame_skin_matrices} is set — a run handed
-     *     out, a pending skin's joints named, or the buffers grown
-     *     since the last dispatch — copy all of "current" over
-     *     "previous", so the first velocity read over those rows sees
-     *     matching matrices and produces zero velocity.
+     *  3. Copy "current" over "previous" on the rows that have no last
+     *     frame — every run handed out and every pending skin's run
+     *     named since the last dispatch, or all of it after a grow —
+     *     so the first velocity read over those rows sees matching
+     *     matrices and produces zero velocity. Every other row of
+     *     "previous" keeps last frame's matrices.
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      */
@@ -1665,6 +1715,9 @@ export class GPUAnimationManager {
             .get('animation_skin_joints')
             .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
         if (groups === 0) {
+            // no page to walk means no skin registered, and a skin given back takes its runs
+            assert.equal(this.#skin_matrix_seed_runs.length, 0, 'seed runs queued for skins no longer registered');
+
             return;
         }
 
@@ -1689,20 +1742,69 @@ export class GPUAnimationManager {
             },
         });
 
-        // First-frame init (or post-grow): "previous" buffer is
-        // zero-initialised, which would have the velocity pass
-        // interpolate against the origin and produce huge nonsense
-        // on the first frame the skin appears. Seed prev from
-        // current — first velocity reads then yield zero, which is
-        // the right answer (no motion has happened yet).
-        if (this.#first_frame_skin_matrices) {
+        this.#seed_previous_skin_matrices(cmd_ctx, current, previous);
+    }
+
+    /**
+     * Copy "current" over "previous" on the rows where "previous" holds no pose of the frame
+     * before: all of it after a grow, otherwise the runs queued since the last prep. Zeros there,
+     * or the last pose of a skin that had the rows, would have the velocity pass produce huge
+     * nonsense on the first frame the skin appears; seeded, the first velocity read yields zero,
+     * which is the right answer — no motion has happened yet.
+     *
+     * Every other row is left alone: a settled skin's rows hold its pose last frame, which its
+     * motion is measured from, and the rest are read by no one. Seeded too, every skinned
+     * character on screen would lose its motion vectors for the frame whenever one spawned.
+     *
+     * Runs are coalesced by sorting — a frame's worth of spawns is a handful of runs — and adjacent
+     * or overlapping ones go as one copy.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {GPUBuffer} current
+     * @param {GPUBuffer} previous
+     */
+    #seed_previous_skin_matrices(cmd_ctx, current, previous) {
+        const runs = this.#skin_matrix_seed_runs;
+
+        if (this.#skin_matrix_seed_all) {
+            cmd_ctx.copyBufferToBuffer(current, 0, previous, 0, current.size);
+
+            this.#skin_matrix_seed_all = false;
+            runs.length = 0;
+
+            return;
+        }
+
+        if (runs.length === 0) {
+            // a settled frame: every row of "previous" is last frame's
+            return;
+        }
+
+        runs.sort((a, b) => a[0] - b[0]);
+
+        let i = 0;
+
+        while (i < runs.length) {
+            const first = runs[i][0];
+            let end = first + runs[i][1];
+
+            i++;
+
+            // a run starting at or before this copy's end is part of it
+            while (i < runs.length && runs[i][0] <= end) {
+                end = Math.max(end, runs[i][0] + runs[i][1]);
+
+                i++;
+            }
+
             cmd_ctx.copyBufferToBuffer(
-                current, 0,
-                previous, 0,
-                current.size,
+                current, first * SKIN_MATRIX_BYTES,
+                previous, first * SKIN_MATRIX_BYTES,
+                (end - first) * SKIN_MATRIX_BYTES,
             );
-            this.#first_frame_skin_matrices = false;
         }
+
+        runs.length = 0;
     }
 
     /**

package/src/shade/renderer/buffer/GPUBufferReadbackAllocator.d.ts

@@ -2,11 +2,12 @@
  * Persistent `MAP_READ | COPY_DST` buffers for reading GPU data back — {@link GPUBufferStagingAllocator}
  * run the other way.
  *
- * The same shape on purpose: a size-sorted free list, `get(min_size)` serving the smallest buffer
- * that fits and creating one when none does, `release(buffer)` putting it back. Where the staging
- * pool re-maps a buffer on release because the next writer needs it mapped, this one *unmaps*,
- * because the next copy into it needs it unmapped; the mapping is the holder's, taken after the
- * copy has landed and read at the holder's own apply point.
+ * The same shape: a size-sorted free list, `get(min_size)` serving the smallest buffer that fits
+ * and creating one when none does, `release(buffer)` putting it back. Where the staging pool re-maps
+ * a buffer on release because the next writer needs it mapped, this one *unmaps*, because the next
+ * copy into it needs it unmapped; the mapping is the holder's, taken after the copy has landed and
+ * read at the holder's own apply point. Unlike the staging pool, this one has no bound on how much
+ * larger than the request a buffer it serves may be, no size classes and no reclaim.
  *
  * Why not `buffer_allocator_main`: `TransientResourcePool`'s reuse safety rests on transients being
  * GPU-only, and a readback buffer is held by the CPU across frames.

package/src/shade/renderer/buffer/GPUBufferReadbackAllocator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBufferReadbackAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferReadbackAllocator.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA4BI;;;;OAIG;IACH;QAF4B,YAAY,GAA7B,MAAM;OAQhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,aAkChB;IAED;;;;;OAKG;IACH,iCAsBC;IAED;;;;;OAKG;IACH,iCAMC;IAkBD,gBAUC;;CACJ"}
+{"version":3,"file":"GPUBufferReadbackAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferReadbackAllocator.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA4BI;;;;OAIG;IACH;QAF4B,YAAY,GAA7B,MAAM;OAQhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,aAkChB;IAED;;;;;OAKG;IACH,iCAsBC;IAED;;;;;OAKG;IACH,iCAMC;IAkBD,gBAUC;;CACJ"}