@woosh/meep-engine 3.31.0 → 3.33.0

package/src/shade/renderer/GraphicsContext.js

@@ -11,6 +11,7 @@ import { GPUBufferAllocatorNative } from "./buffer/GPUBufferAllocatorNative.js";
 import { create_buffer, GPUBufferContext } from "./buffer/GPUBufferContext.js";
 import { GPUBufferReadbackAllocator } from "./buffer/GPUBufferReadbackAllocator.js";
 import { GPUBufferStagingAllocator } from "./buffer/GPUBufferStagingAllocator.js";
+import { GPUBufferUploadAllocator } from "./buffer/GPUBufferUploadAllocator.js";
 import { GPUGeometryManager } from "./geometry/GPUGeometryManager.js";
 import { GPUCollectionLimits } from "./rasterize/expand/GPUCollectionLimits.js";
 import { GPUSamplerManager } from "./GPUSamplerManager.js";
@@ -137,11 +138,19 @@ export class GraphicsContext {
     buffer_allocator_native;
 
     /**
-     * Used to upload data to the GPU
+     * Mapped `MAP_WRITE` buffers, one per upload: where a {@link ShadeGPUCommandContext} sends its
+     * large writes, for which a mapping is the faster road (see `MAPPED_UPLOAD_THRESHOLD`).
      * @type {GPUBufferStagingAllocator}
      */
     buffer_allocator_staging;
 
+    /**
+     * Upload blocks for {@link ShadeGPUCommandContext}'s small writes — every uniform a pass is
+     * handed by value among them. Sent with one queue write per block, not mapped.
+     * @type {GPUBufferUploadAllocator}
+     */
+    buffer_allocator_upload;
+
     /**
      * Used to read data back from the GPU: `MAP_READ` buffers, held by the CPU across frames, which
      * is why they cannot come from {@link buffer_allocator_main}.
@@ -174,8 +183,10 @@ export class GraphicsContext {
     increment_time() {
         this.#timer_increment++;
 
-        // advance the single frame clock for both substitutable pools in lockstep
+        // advance the single frame clock for the pools in lockstep
         this.buffer_allocator_main.increment_time();
+        this.buffer_allocator_staging.increment_time();
+        this.buffer_allocator_upload.increment_time();
         this.allocator_textures.increment_time();
     }
 
@@ -197,6 +208,7 @@ export class GraphicsContext {
         this.buffer_allocator_main = new GPUBufferAllocator(device);
         this.buffer_allocator_native = new GPUBufferAllocatorNative(device);
         this.buffer_allocator_staging = new GPUBufferStagingAllocator(device);
+        this.buffer_allocator_upload = new GPUBufferUploadAllocator(device);
         this.buffer_allocator_readback = new GPUBufferReadbackAllocator(device);
 
         this.allocator_textures = new GPUTextureAllocator(device);
@@ -246,53 +258,65 @@ export class GraphicsContext {
             pass.setImmediates(0, immediate.buffer.raw_bytes, immediate.offset, immediate.size);
         }
 
-        const bind_group_descriptors = pipeline.layout.bindGroupLayouts;
-
         const bind_group_count = bindings.length;
 
-        assert.lessThanOrEqual(bind_group_count, bind_group_descriptors.length, 'too many bind groups (more than in descriptor)');
-
-        const bind_group_manager = this.bind_groups;
+        assert.lessThanOrEqual(bind_group_count, pipeline.layout.bindGroupLayouts.length, 'too many bind groups (more than in descriptor)');
 
         for (let i = 0; i < bind_group_count; i++) {
-            const group_resource_set = bindings[i];
-
-            assert.isArray(group_resource_set, `bindings[${i}]`);
-
-            const bind_group_layout_descriptor = bind_group_descriptors[i];
-
-            const descriptor = BindGroupDescriptor.from(
-                bind_group_layout_descriptor,
-                group_resource_set
-            );
-
-            const bind_group = bind_group_manager.obtain(descriptor);
+            this.setPipelineBindGroup(pass, pipeline, i, bindings[i]);
+        }
+    }
 
-            if (DEBUG_LOGGING) {
-                // debug
-                const descriptor_rev = bind_group_manager.reverse_lookup(bind_group);
+    /**
+     * Set one bind group of `pipeline`'s layout, leaving the others as they are — for a pass whose
+     * groups change at different rates, where {@link setPipelineBindings} would set every group up
+     * to the last one on each change.
+     *
+     * @param {GPUBindingCommandsMixin} pass
+     * @param {PipelineDescriptorBase} pipeline
+     * @param {number} index the group's index in the pipeline's layout
+     * @param {GPUBindingResource[]} resources the group's entries, in binding order
+     */
+    setPipelineBindGroup(pass, pipeline, index, resources) {
+        assert.isArray(resources, `bindings[${index}]`);
 
-                const entries = descriptor_rev.entries
-                    .map(e => {
-                        if (e.buffer !== undefined) {
-                            return `buffer:"${e.buffer.label}"`;
-                        } else if (e instanceof GPUTextureView) {
-                            return "texture_view"
-                        } else if (e instanceof GPUSampler) {
-                            return "sampler"
-                        } else {
-                            // something else
-                            return "unknown";
-                        }
+        const bind_group_descriptors = pipeline.layout.bindGroupLayouts;
 
-                    })
-                    .filter(e => e !== undefined);
+        assert.lessThan(index, bind_group_descriptors.length, 'index is past the last group in the descriptor');
 
-                console.log(`pass.setBindGrpup(${i}, [ ${entries.join(', ')} ])`);
-            }
+        const bind_group_manager = this.bind_groups;
 
-            pass.setBindGroup(i, bind_group);
+        const descriptor = BindGroupDescriptor.from(
+            bind_group_descriptors[index],
+            resources
+        );
+
+        const bind_group = bind_group_manager.obtain(descriptor);
+
+        if (DEBUG_LOGGING) {
+            // debug
+            const descriptor_rev = bind_group_manager.reverse_lookup(bind_group);
+
+            const entries = descriptor_rev.entries
+                .map(e => {
+                    if (e.buffer !== undefined) {
+                        return `buffer:"${e.buffer.label}"`;
+                    } else if (e instanceof GPUTextureView) {
+                        return "texture_view"
+                    } else if (e instanceof GPUSampler) {
+                        return "sampler"
+                    } else {
+                        // something else
+                        return "unknown";
+                    }
+
+                })
+                .filter(e => e !== undefined);
+
+            console.log(`pass.setBindGrpup(${index}, [ ${entries.join(', ')} ])`);
         }
+
+        pass.setBindGroup(index, bind_group);
     }
 
     /**
@@ -316,6 +340,7 @@ export class GraphicsContext {
 
         r += this.buffer_allocator_main.gpu_memory_usage;
         r += this.buffer_allocator_staging.gpu_memory_usage;
+        r += this.buffer_allocator_upload.gpu_memory_usage;
         r += this.buffer_allocator_readback.gpu_memory_usage;
 
         r += this.allocator_textures.gpu_memory_usage;
@@ -331,28 +356,55 @@ export class GraphicsContext {
     update() {
         const command_ctx = ShadeGPUCommandContext.create(this, 'GraphicsContext.update');
 
-        // The one place per frame the meshlet pool compacts, at the head of the frame: before the
-        // clone flush in geometries.update, before the VG runtime's flush, before any pass. Its
-        // per-frame bound is a bound because this is the only call (COMPACTION_PLAN_2026_09_16
-        // §4.5).
-        this.geometries.meshlets.sweep(command_ctx);
+        /**
+         * What the update raised, if anything. Held so the context is finished before it is
+         * re-raised: a context never finished keeps everything it took for good — an upload block,
+         * transient buffers — and a manager that throws every frame would leak that much every
+         * frame.
+         * @type {*}
+         */
+        let update_error = null;
 
-        this.geometries.update(command_ctx);
+        try {
+            // The one place per frame the meshlet pool compacts, at the head of the frame: before the
+            // clone flush in geometries.update, before the VG runtime's flush, before any pass. Its
+            // per-frame bound is a bound because this is the only call (COMPACTION_PLAN_2026_09_16
+            // §4.5).
+            this.geometries.meshlets.sweep(command_ctx);
 
-        this.textures.update();
-        this.materials.update(command_ctx);
+            this.geometries.update(command_ctx);
 
-        this.bind_groups.update();
+            this.textures.update();
+            this.materials.update(command_ctx);
 
-        this.increment_time();
+            this.bind_groups.update();
 
-        this.allocator_textures.update();
+            this.increment_time();
 
-        this.#collection_limits.update(command_ctx, this.buffer_allocator_main);
+            this.allocator_textures.update();
 
-        command_ctx.finish();
+            this.#collection_limits.update(command_ctx, this.buffer_allocator_main);
+        } catch (e) {
+            update_error = e;
+        }
+
+        try {
+            command_ctx.finish();
+        } catch (teardown_error) {
+            if (update_error === null) {
+                throw teardown_error;
+            }
+
+            // already unwinding: the update's own error is the one the caller needs to see
+        }
+
+        if (update_error !== null) {
+            throw update_error;
+        }
 
         this.buffer_allocator_main.update();
+        this.buffer_allocator_staging.update();
+        this.buffer_allocator_upload.update();
     }
 
     destroy() {
@@ -371,6 +423,7 @@ export class GraphicsContext {
         this.buffer_allocator_main.destroy();
         this.buffer_allocator_native.destroy();
         this.buffer_allocator_staging.destroy();
+        this.buffer_allocator_upload.destroy();
         this.buffer_allocator_readback.destroy();
 
         this.#collection_limits.destroy();

package/src/shade/renderer/Renderer.d.ts

@@ -210,7 +210,18 @@ export class Renderer {
      * @type {Signal<ShadeDeviceFailure>}
      */
     onDeviceFailure: any;
-    onFrameFinished: 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: any;
     /**
      *
      * @param {number} v
@@ -440,7 +451,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: PerspectiveCamera, scene: Scene, time_delta_seconds?: number): boolean;
     /**
@@ -457,11 +470,14 @@ 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: PerspectiveCamera, scene: Scene, time_delta_seconds: number, target: GPUTextureContext): boolean;
     #private;
 }
+export type GPUFrameRecorder = import("../device/timing/profile/GPUFrameRecorder.js").GPUFrameRecorder;
 export type GPUProfileSession = import("../device/timing/profile/GPUProfileSession.js").GPUProfileSession;
 export type PerspectiveCamera = import("./camera/PerspectiveCamera.js").PerspectiveCamera;
 export type RenderExtension = import("./extension/RenderExtension.js").RenderExtension;
@@ -477,7 +493,6 @@ import { DepthOfField } from "./postprocess/dof/raymarch/DepthOfField.js";
 import { DepthOfFieldU } from "./postprocess/dof/gather/DepthOfFieldU.js";
 import { ViewManager } from "./view/ViewManager.js";
 import { GraphicsContext } from "./GraphicsContext.js";
-import Signal from "../../core/events/signal/Signal.js";
 import Vector2 from "../../core/geom/Vector2.js";
 import { GPUTextureContext } from "./texture/GPUTextureContext.js";
 import { FramePhase } from "./extension/FramePhase.js";

package/src/shade/renderer/Renderer.d.ts.map

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

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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"}