@woosh/meep-engine 3.31.0 → 3.32.0

package/src/shade/renderer/Renderer.js

@@ -85,6 +85,7 @@ import { View } from "./view/View.js";
 import { ViewManager } from "./view/ViewManager.js";
 
 /**
+ * @typedef {import("../device/timing/profile/GPUFrameRecorder.js").GPUFrameRecorder} GPUFrameRecorder
  * @typedef {import("../device/timing/profile/GPUProfileSession.js").GPUProfileSession} GPUProfileSession
  * @typedef {import("./camera/PerspectiveCamera.js").PerspectiveCamera} PerspectiveCamera
  * @typedef {import("./extension/RenderExtension.js").RenderExtension} RenderExtension
@@ -472,6 +473,17 @@ export class Renderer {
      */
     onDeviceFailure = new Signal();
 
+    /**
+     * Sent at the end of every frame {@link render} or {@link render_to_target} completes, with the
+     * number of frames completed so far. A frame that throws is not one of them: whatever it had
+     * recorded may still have been submitted, but it sends nothing and is not counted.
+     *
+     * **Submitted, not finished.** The frame's commands have been handed to the queue and the GPU
+     * may not have started them; a listener that needs the GPU to be done with the frame waits on
+     * {@link GPUQueue#onSubmittedWorkDone} instead.
+     *
+     * @type {Signal<number>}
+     */
     onFrameFinished = new Signal();
 
     /**
@@ -1898,7 +1910,9 @@ export class Renderer {
      * simulation, the animation tick and exposure adaptation all step by it. Zero by default, which
      * draws the current state and moves nothing; a fixed fraction of a second here instead would run
      * the simulation at that rate no matter what the caller's clock was doing.
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     * @returns {boolean} whether a frame was encoded and submitted. False only when there is nothing
+     * to draw with — the device was lost, or the renderer destroyed. Frames the GPU has not finished
+     * yet neither hold this one back nor make it return false.
      */
     render(
         camera,
@@ -1937,13 +1951,100 @@ export class Renderer {
      * @param {Scene} scene
      * @param {number} time_delta_seconds
      * @param {GPUTextureContext} target must match {@link output_resolution}
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     * @returns {boolean} whether a frame was encoded and submitted. False only when there is nothing
+     * to draw with — the device was lost, or the renderer destroyed. Frames the GPU has not finished
+     * yet neither hold this one back nor make it return false.
      */
     render_to_target(
         camera,
         scene,
         time_delta_seconds,
         target
+    ) {
+        try {
+            return this.#draw_to_target(camera, scene, time_delta_seconds, target);
+        } catch (error) {
+            this.#finish_stranded_frame();
+
+            throw error;
+        }
+    }
+
+    /**
+     * The frame's command context from the moment it is created until the frame's teardown takes
+     * it, and null otherwise — so a frame that throws before its teardown leaves it here for
+     * {@link render_to_target} to finish.
+     *
+     * @type {ShadeGPUCommandContext|null}
+     */
+    #frame_command_ctx = null;
+
+    /**
+     * The profiler's recorder for the frame {@link #frame_command_ctx} belongs to, and the session
+     * that handed it out — null when that frame is not profiled — so a frame that throws before its
+     * teardown still closes its profile frame. Otherwise a capture leaves out exactly the frames
+     * that failed.
+     *
+     * @type {GPUFrameRecorder|null}
+     */
+    #frame_profile_recorder = null;
+
+    /**
+     * @type {GPUProfileSession|null}
+     */
+    #frame_profile_session = null;
+
+    /**
+     * Finish the context a frame left behind when it threw before its teardown: the scene tick, the
+     * shadow draw and every extension phase run between the context's creation and the teardown,
+     * and a throw from any of them used to leave it open for good, holding its upload block, its
+     * transient buffers and its profiler's buffers — every frame it happened.
+     *
+     * What comes back is what it holds. What it recorded is submitted if the encoder can still be
+     * finished: a throw once the `Shade` debug group is open leaves that group unclosed, the
+     * command buffer is invalid, and the submission is refused with nothing of the frame run — as it
+     * is for a pass that throws, whose teardown shares the same unclosed group.
+     */
+    #finish_stranded_frame() {
+        const stranded = this.#frame_command_ctx;
+        const recorder = this.#frame_profile_recorder;
+        const session = this.#frame_profile_session;
+
+        this.#frame_command_ctx = null;
+        this.#frame_profile_recorder = null;
+        this.#frame_profile_session = null;
+
+        if (stranded === null) {
+            return;
+        }
+
+        try {
+            stranded.finish();
+        } catch (teardown_error) {
+            // already unwinding: the frame's own error is the one the caller needs to see
+        }
+
+        if (recorder !== null) {
+            stranded.profiling_absorbed.then(() => {
+                session.end_frame(recorder, performance.now());
+            });
+        }
+    }
+
+    /**
+     * The whole of {@link render_to_target}, which only adds the finishing of a frame that throws.
+     *
+     * @param {PerspectiveCamera} camera
+     * @param {Scene} scene
+     * @param {number} time_delta_seconds
+     * @param {GPUTextureContext} target
+     * @returns {boolean}
+     */
+    #draw_to_target(
+        camera,
+        scene,
+        time_delta_seconds,
+        target
     ) {
         assert.defined(target, 'target');
         assert.equal(target.isGPUTextureContext, true, 'target.isGPUTextureContext !== true');
@@ -2020,6 +2121,8 @@ export class Renderer {
             "Renderer/main-0"
         );
 
+        this.#frame_command_ctx = command_ctx;
+
         /**
          * The frame recorder for this frame, or null when nothing is profiling.
          * @type {GPUFrameRecorder|null}
@@ -2033,6 +2136,9 @@ export class Renderer {
 
             if (profile_recorder !== null) {
                 command_ctx.enable_profiling(profile_recorder, 0);
+
+                this.#frame_profile_recorder = profile_recorder;
+                this.#frame_profile_session = this.profile_session;
             }
         }
 
@@ -2822,6 +2928,11 @@ export class Renderer {
          destroyed, and the session's frame accounting silently short a frame. A render loop that
          catches and carries on repeats that every failing frame until the device complains.
         */
+        // the teardown has it from here, whatever the finish does
+        this.#frame_command_ctx = null;
+        this.#frame_profile_recorder = null;
+        this.#frame_profile_session = null;
+
         try {
             command_ctx.finish();
         } catch (teardown_error) {

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -418,8 +418,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
@@ -427,11 +429,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
      */

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}

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/GPUBufferStagingAllocator.d.ts

@@ -1,6 +1,11 @@
 /**
- * Provides staging buffers for pushing data from CPU to GPU.
+ * Mapped `MAP_WRITE | COPY_SRC` buffers for pushing data from the CPU to the GPU, one per upload.
  *
+ * A buffer comes out mapped; its holder fills it, unmaps it, copies out of it and gives it back, and
+ * the pool maps it again — a round trip through the GPU — before it can come out again. For bytes
+ * that is the cheaper road; for thousands of small writes a frame the round trips are the cost, which
+ * is why a {@link ShadeGPUCommandContext} brings only its large writes here (see
+ * `MAPPED_UPLOAD_THRESHOLD`).
  */
 export class GPUBufferStagingAllocator {
     /**
@@ -9,6 +14,8 @@ export class GPUBufferStagingAllocator {
      */
     constructor(device: GPUDevice);
     /**
+     * Bytes in every buffer this pool has made and not destroyed: free, handed out, or on the way
+     * back.
      *
      * @returns {number}
      */
@@ -22,8 +29,10 @@ export class GPUBufferStagingAllocator {
     /**
      *
      * @param {GPUBuffer} buffer
+     * @returns {boolean} whether it was taken back: false for a buffer given back already, or one
+     * this pool did not hand out
      */
-    release(buffer: GPUBuffer): void;
+    release(buffer: GPUBuffer): boolean;
     destroy(): void;
     #private;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AASA;;;GAGG;AACH;IAaI;;;OAGG;IACH,+BAIC;IAED;;;OAGG;IACH,+BAQC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aAiChB;IAgCD;;;OAGG;IACH,iCAiBC;IAED,gBAOC;;CACJ"}
+{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IA8CI;;;OAGG;IACH,+BAIC;IAED;;;;;OAKG;IACH,+BAEC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aAsChB;IAkCD;;;;;OAKG;IACH,4BAHa,OAAO,CA0BnB;IAgCD,gBAUC;;CACJ"}