@woosh/meep-engine 3.12.0 → 3.13.1

package/src/shade/device/pass/ShadeGPURenderPassEncoder.js

@@ -0,0 +1,317 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Decorates {@link GPURenderPassEncoder}.
+ *
+ * The render half of {@link ShadeGPUComputePassEncoder} — see there for why the forwarding is
+ * hand-written, why every pass is wrapped rather than only the profiled ones, and what `work` is.
+ *
+ * **Known blind spot:** draws inside a {@link GPURenderBundle} handed to {@link executeBundles} are
+ * not counted, because the bundle was encoded somewhere this pass never saw. The `Proxy` this
+ * replaces had the same gap and nothing in Shade uses bundles.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPURenderPassEncoder {
+
+    /**
+     * @type {GPURenderPassEncoder}
+     */
+    #pass;
+
+    /**
+     * Where this pass's encoded work is tallied, or null when nothing is profiling.
+     *
+     * @type {GPUProfileWork|null}
+     */
+    #work;
+
+    /**
+     * @type {boolean}
+     */
+    #ended = false;
+
+    /**
+     * @param {GPURenderPassEncoder} pass
+     * @param {GPUProfileWork|null} work
+     */
+    constructor(pass, work) {
+        assert.defined(pass, 'pass');
+
+        this.#pass = pass;
+        this.#work = work;
+    }
+
+    /**
+     * @returns {string}
+     */
+    get label() {
+        return this.#pass.label;
+    }
+
+    /**
+     * @param {string} value
+     */
+    set label(value) {
+        this.#pass.label = value;
+    }
+
+    // --- GPURenderPassEncoder -----------------------------------------------
+
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     * @param {number} min_depth
+     * @param {number} max_depth
+     */
+    setViewport(x, y, width, height, min_depth, max_depth) {
+        this.#pass.setViewport(x, y, width, height, min_depth, max_depth);
+    }
+
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     */
+    setScissorRect(x, y, width, height) {
+        this.#pass.setScissorRect(x, y, width, height);
+    }
+
+    /**
+     * @param {GPUColor} color
+     */
+    setBlendConstant(color) {
+        this.#pass.setBlendConstant(color);
+    }
+
+    /**
+     * @param {number} reference
+     */
+    setStencilReference(reference) {
+        this.#pass.setStencilReference(reference);
+    }
+
+    /**
+     * @param {number} query_index
+     */
+    beginOcclusionQuery(query_index) {
+        this.#pass.beginOcclusionQuery(query_index);
+    }
+
+    endOcclusionQuery() {
+        this.#pass.endOcclusionQuery();
+    }
+
+    /**
+     * @param {Iterable<GPURenderBundle>} bundles
+     */
+    executeBundles(bundles) {
+        this.#pass.executeBundles(bundles);
+    }
+
+    end() {
+        assert.notOk(this.#ended, 'pass already ended');
+
+        this.#ended = true;
+
+        this.#pass.end();
+    }
+
+    // --- GPURenderCommandsMixin ---------------------------------------------
+
+    /**
+     * @param {GPURenderPipeline} pipeline
+     */
+    setPipeline(pipeline) {
+        this.#pass.setPipeline(pipeline);
+    }
+
+    /**
+     * Rest arguments, so the arity that arrives is the arity that leaves — `size` has no default to
+     * stand in for, it means "the rest of the buffer", and a trailing `undefined` is not the same
+     * as an absent argument.
+     * @see ShadeGPUComputePassEncoder#setBindGroup
+     *
+     * @param {GPUBuffer} buffer
+     * @param {GPUIndexFormat} index_format
+     * @param {number} [offset]
+     * @param {number} [size]
+     */
+    setIndexBuffer(...args) {
+        this.#pass.setIndexBuffer(...args);
+    }
+
+    /**
+     * Rest arguments, for the reason given on {@link setIndexBuffer}.
+     *
+     * @param {number} slot
+     * @param {GPUBuffer} buffer
+     * @param {number} [offset]
+     * @param {number} [size]
+     */
+    setVertexBuffer(...args) {
+        this.#pass.setVertexBuffer(...args);
+    }
+
+    /**
+     * Named parameters rather than rest arguments, because the counts have to be read — and the
+     * defaults are WebGPU's own, so materialising them here passes four defined values instead of
+     * a trailing `undefined`. @see ShadeGPUComputePassEncoder#setBindGroup
+     *
+     * @param {number} vertex_count
+     * @param {number} [instance_count=1]
+     * @param {number} [first_vertex=0]
+     * @param {number} [first_instance=0]
+     */
+    draw(vertex_count, instance_count = 1, first_vertex = 0, first_instance = 0) {
+        const work = this.#work;
+
+        if (work !== null) {
+            work.draw_count++;
+            work.vertex_count += vertex_count;
+            work.instance_count += instance_count;
+        }
+
+        this.#pass.draw(vertex_count, instance_count, first_vertex, first_instance);
+    }
+
+    /**
+     * Named parameters with WebGPU's own defaults, for the reason given on {@link draw}.
+     *
+     * @param {number} index_count
+     * @param {number} [instance_count=1]
+     * @param {number} [first_index=0]
+     * @param {number} [base_vertex=0]
+     * @param {number} [first_instance=0]
+     */
+    drawIndexed(index_count, instance_count = 1, first_index = 0, base_vertex = 0, first_instance = 0) {
+        const work = this.#work;
+
+        if (work !== null) {
+            work.draw_count++;
+            work.index_count += index_count;
+            work.instance_count += instance_count;
+        }
+
+        this.#pass.drawIndexed(index_count, instance_count, first_index, base_vertex, first_instance);
+    }
+
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    drawIndirect(indirect_buffer, indirect_offset) {
+        const work = this.#work;
+
+        if (work !== null) {
+            // Counts live in a GPU buffer, so there is nothing to add to the vertex or instance
+            // totals. Counted apart so those are not read as covering this.
+            work.indirect_draw_count++;
+        }
+
+        this.#pass.drawIndirect(indirect_buffer, indirect_offset);
+    }
+
+    /**
+     * @param {GPUBuffer} indirect_buffer
+     * @param {number} indirect_offset
+     */
+    drawIndexedIndirect(indirect_buffer, indirect_offset) {
+        const work = this.#work;
+
+        if (work !== null) {
+            work.indirect_draw_count++;
+        }
+
+        this.#pass.drawIndexedIndirect(indirect_buffer, indirect_offset);
+    }
+
+    // --- GPUBindingCommandsMixin --------------------------------------------
+
+    /**
+     * @see ShadeGPUComputePassEncoder#setBindGroup for why the third argument is omitted rather
+     * than forwarded as `undefined`
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {number[]} [dynamic_offsets]
+     */
+    setBindGroup(index, bind_group, dynamic_offsets) {
+        if (dynamic_offsets === undefined) {
+            this.#pass.setBindGroup(index, bind_group);
+        } else {
+            this.#pass.setBindGroup(index, bind_group, dynamic_offsets);
+        }
+    }
+
+    /**
+     * The `Uint32Array`-slice form of {@link setBindGroup}.
+     *
+     * @see ShadeGPUComputePassEncoder#setBindGroupRange for why this is named rather than overloaded
+     *
+     * @param {number} index
+     * @param {GPUBindGroup} bind_group
+     * @param {Uint32Array} dynamic_offsets_data
+     * @param {number} data_start
+     * @param {number} data_length
+     */
+    setBindGroupRange(index, bind_group, dynamic_offsets_data, data_start, data_length) {
+        this.#pass.setBindGroup(index, bind_group, dynamic_offsets_data, data_start, data_length);
+    }
+
+    /**
+     * Rest arguments, for the reason given on {@link setIndexBuffer}.
+     *
+     * @param {number} range_offset
+     * @param {ArrayBufferView|ArrayBuffer} data
+     * @param {number} [data_offset]
+     * @param {number} [data_size]
+     */
+    setImmediates(...args) {
+        this.#pass.setImmediates(...args);
+    }
+
+    // --- GPUDebugCommandsMixin ----------------------------------------------
+
+    /**
+     * @param {string} label
+     */
+    pushDebugGroup(label) {
+        this.#pass.pushDebugGroup(label);
+    }
+
+    popDebugGroup() {
+        this.#pass.popDebugGroup();
+    }
+
+    /**
+     * @param {string} label
+     */
+    insertDebugMarker(label) {
+        this.#pass.insertDebugMarker(label);
+    }
+
+    // --- Shade --------------------------------------------------------------
+
+    /**
+     * Record which pipeline descriptor this pass ran.
+     *
+     * @see ShadeGPUComputePassEncoder#record_pipeline
+     *
+     * @param {RenderPipelineDescriptor} descriptor
+     * @returns {void}
+     */
+    record_pipeline(descriptor) {
+        const work = this.#work;
+
+        if (work === null) {
+            return;
+        }
+
+        work.pipeline = descriptor.label ?? "";
+    }
+}

package/src/shade/device/timing/GPUTimerArray.d.ts

@@ -26,10 +26,10 @@ export class GPUTimerArray {
     /**
      * Visit every slot that was claimed this frame, in slot order, with its raw timestamps.
      *
-     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. {@link
-     * results_to_console_table} is the same data rounded for a human to read at a glance; a
-     * recording needs the values themselves, and the difference matters once quantization is in
-     * play — see the profiler's treatment of `timestamp_period_ns`.
+     * Raw: nanoseconds as the device reported them, `BigInt`, unscaled. Rounding belongs to
+     * whoever is displaying them; a recording needs the values themselves, and the difference
+     * matters once quantization is in play — see the profiler's treatment of
+     * `timestamp_period_ns`.
      *
      * @param {(slot_id: number, label: string, type: string, t_begin: bigint, t_end: bigint) => void} visitor
      * @returns {void}
@@ -42,11 +42,6 @@ export class GPUTimerArray {
      */
     resolve(encoder: GPUCommandEncoder): void;
     download_results(): Promise<void>;
-    /**
-     * prepare tabular formatting for console output
-     * @returns {Object}
-     */
-    results_to_console_table(): any;
     #private;
 }
 //# sourceMappingURL=GPUTimerArray.d.ts.map

package/src/shade/device/timing/GPUTimerArray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IAwKI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IAjKD;;;;OAIG;IACH,4BAEC;IAgED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,gCAA8B,SAAS,CAInD;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,+BAA6B,SAAS,CAIlD;IAED;;;;;;;;;;OAUG;IACH,oCAHqB,MAAM,SAAS,MAAM,QAAQ,MAAM,WAAW,MAAM,SAAS,MAAM,KAAK,IAAI,GACpF,IAAI,CAsBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAwBC;IAED;;;OAGG;IACH,gCAqBC;;CAEJ"}
+{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IAwKI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IAjKD;;;;OAIG;IACH,4BAEC;IAgED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,gCAA8B,SAAS,CAInD;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,+BAA6B,SAAS,CAIlD;IAED;;;;;;;;;;OAUG;IACH,oCAHqB,MAAM,SAAS,MAAM,QAAQ,MAAM,WAAW,MAAM,SAAS,MAAM,KAAK,IAAI,GACpF,IAAI,CAsBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAuBC;;CAEJ"}