@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -7,6 +7,7 @@ import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPU_DATABASE_NULL } from "../buffer/table/GPU_DATABASE_NULL.js";
 import { generate_record_writer } from "../buffer/table/serde/generate_record_writer.js";
 import {
+    enquire_scene_update_transform_hierarchy_pipelines,
     graph_scene_update_transform_hierarchy
 } from "../scene/hierarchy/graph_scene_update_transform_hierarchy.js";
 import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
@@ -48,6 +49,7 @@ import {
 } from "./skinning/shader_skin_matrix_prep.js";
 
 /**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve} AnimationCurve
  * @typedef {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
  * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
@@ -351,6 +353,18 @@ function skin_content_equals(skin, joints, inverse_bind_matrices) {
  */
 export class GPUAnimationManager {
 
+    /**
+     * Offer the pipelines {@link tick} runs on every frame: the transform hierarchy, which composes
+     * world matrices whether or not anything is animated — see {@link PipelineEnquiry}. The clip,
+     * pose and skinning passes are left to the first frame that has a clip or a skin.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquire_scene_update_transform_hierarchy_pipelines(enquiry);
+    }
+
+
     /** @type {GPUDevice} */
     #device;
 

package/src/shade/renderer/animation/skinning/shader_meshlet_apply_skinning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_meshlet_apply_skinning.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/shader_meshlet_apply_skinning.js"],"names":[],"mappings":"AAqCA;;;;GAIG;AACH,yCAA0C;AAiT1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0DAIG;8BAtV2B,+BAA+B"}
+{"version":3,"file":"shader_meshlet_apply_skinning.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/shader_meshlet_apply_skinning.js"],"names":[],"mappings":"AAqCA;;;;GAIG;AACH,yCAA0C;AAmT1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0DAIG;8BAxV2B,+BAA+B"}

package/src/shade/renderer/animation/skinning/shader_meshlet_apply_skinning.js

@@ -96,9 +96,11 @@ resources.createGroup()
 // skinning into a shared slot would race, so the shader skips the
 // write for any attribute where the flag is set — the cloned slot
 // keeps the source's value and lighting on those vertices uses an
-// undeformed direction. For typical character meshes
-// normals/tangents vary per vertex and so don't get the all-equal
-// collapse, so this skip rarely engages in practice.
+// undeformed direction. MeshletBatch#compress never collapses either
+// on a meshlet that carries skin weights, so the skip engages only
+// for a meshlet encoded before it stopped (2026-10-16): until then a
+// flat cloth sheet, every bind normal alike, collapsed and was lit in
+// its bind pose whatever shape it took.
 //
 // SkinningJoints + SkinningWeights are read-only here. They CAN be
 // compressed — a meshlet where every vertex shares the same joint

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts

@@ -9,6 +9,12 @@
  * see "Rendering 'Assassin's Creed Shadows'" GDC 2025 by Nicolas Lopez
  */
 export class GPUDatabase {
+    /**
+     * Offer the pipelines {@link update} uploads records with — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: PipelineEnquiry): void;
     /**
      * @param {Object} options
      * @param {GPUDatabaseDefinition} options.definition Immutable schema
@@ -144,6 +150,7 @@ export class GPUDatabase {
     destroy(): void;
     #private;
 }
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
 export type GPUDatabaseDefinition = import("./GPUDatabaseDefinition.js").GPUDatabaseDefinition;
 import { GPUTypedTable } from "./GPUTypedTable.js";

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA2CA;;;;;;;;;GASG;AACH;IA6FI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAkJhB;IAlPD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,oBAEC;IA2JD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;;;;;;;;;OAWG;IACH,kCAeC;IAED;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;qCAxoCY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB;oCALd,0BAA0B"}
+{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA4CA;;;;;;;;;GASG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAKzB;IA8FD;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAkJhB;IAlPD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,oBAEC;IA2JD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;;;;;;;;;OAWG;IACH,kCAeC;IAED;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IAkPD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;8BAvpCY,OAAO,6CAA6C,EAAE,eAAe;qCACrE,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BAPzC,oBAAoB;oCALd,0BAA0B"}

package/src/shade/renderer/buffer/table/GPUDatabase.js

@@ -20,6 +20,7 @@ import { PageBufferPool } from "./PageBufferPool.js";
 import { PageSlotAllocator } from "./PageSlotAllocator.js";
 
 /**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
  * @typedef {import("./GPUDatabaseDefinition.js").GPUDatabaseDefinition} GPUDatabaseDefinition
  */
@@ -53,6 +54,17 @@ const UPLOAD_CHUNK_SIZE = 256 * KILOBYTE;
  */
 export class GPUDatabase {
 
+    /**
+     * Offer the pipelines {@link update} uploads records with — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.compute.push(gpu_table_element_upload_shader.pipeline);
+        enquiry.compute.push(gpu_table_partial_upload_shader.pipeline);
+    }
+
+
     /**
      * Immutable schema.
      * @type {GPUDatabaseDefinition}
@@ -822,7 +834,9 @@ export class GPUDatabase {
 
         assert.isNonNegativeInteger(total_descriptor_count, 'total_descriptor_count');
 
-        const descriptor_words = new Uint32Array(descriptors.data, 0, descriptor_cursor / word_size);
+        // read in place — the buffer already carries a view and the order its words were written in
+        const descriptor_view = descriptors.dataView;
+        const endianness = descriptors.endianness;
 
         const table_descriptor = table.descriptor;
 
@@ -831,7 +845,7 @@ export class GPUDatabase {
         let descriptors_uploaded = 0;
 
         while (descriptors_uploaded < total_descriptor_count) {
-            const chunk_data_start = descriptor_words[descriptors_uploaded * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS + 3];
+            const chunk_data_start = descriptor_view.getUint32((descriptors_uploaded * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS + 3) * word_size, endianness);
 
             let chunk_count = 0;
             let chunk_data_end = chunk_data_start;
@@ -840,8 +854,9 @@ export class GPUDatabase {
                 chunk_count < max_descriptors_per_chunk
                 && descriptors_uploaded + chunk_count < total_descriptor_count
                 ) {
-                const base = (descriptors_uploaded + chunk_count) * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS;
-                const range_end = descriptor_words[base + 3] + descriptor_words[base + 2];
+                const base = (descriptors_uploaded + chunk_count) * descriptor_stride;
+                const range_end = descriptor_view.getUint32(base + 3 * word_size, endianness)
+                    + descriptor_view.getUint32(base + 2 * word_size, endianness);
                 const next_data_end = Math.max(chunk_data_end, range_end);
 
                 // Always take one descriptor, however big its range — a range can't exceed a

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts

@@ -18,6 +18,14 @@
  * shader packs a batch contiguously in request order, so a consumer's run of rows lands in its
  * destination as one `set` — which a per-row function could never have done.
  *
+ * **A run is one request.** {@link request_run} asks for the same byte range of consecutive rows —
+ * the rows of an `add_run`, say — under one handle and one status. It is split at page boundaries
+ * here, never by the caller, and its ranges land back to back in the target. It is all or nothing:
+ * Delivered only when every row is, Dropped when any row is (not resident at encode, not occupied,
+ * or freed while in flight), and it counts once in {@link delivered_count}, {@link dropped_count}
+ * and {@link stalled_count}. A run of whole records is one copy per page it touches rather than one
+ * per row.
+ *
  * **Gather, then one copy.** Rows sit at scattered offsets across pages, so a compute shader packs
  * the requested ranges contiguously before a single copy into a readback buffer. Packing a *range*
  * rather than a record is what makes it worth doing: an entity's world matrix is 64 bytes of a
@@ -51,7 +59,7 @@ export class GPUDatabaseReadback {
      * @param {Object} options
      * @param {import("./GPUDatabase.js").GPUDatabase} options.database
      * @param {GPUDevice} options.device
-     * @param {number} [options.gather_threshold] requests at or above which a dispatch is used
+     * @param {number} [options.gather_threshold] copies at or above which a dispatch is used
      * @param {number} [options.max_in_flight] batches in flight before a frame's requests are dropped
      * @param {string} [options.label]
      */
@@ -63,7 +71,8 @@ export class GPUDatabaseReadback {
         label?: string;
     });
     /**
-     * Requests at or above which a batch is gathered rather than copied range by range.
+     * Copies at or above which a batch is gathered rather than copied range by range — see
+     * {@link DEFAULT_GATHER_THRESHOLD} for what counts as one.
      * @returns {number}
      */
     get gather_threshold(): number;
@@ -164,6 +173,27 @@ export class GPUDatabaseReadback {
      * @returns {number} a handle into {@link status}, valid until the frame after its result lands
      */
     request(table: number, row: number, byte_offset: number, byte_size: number, target: Uint8Array, target_byte_offset?: number): number;
+    /**
+     * Ask for the same byte range of `row_count` consecutive rows, landing back to back in `target`
+     * from `target_byte_offset` — row `first_row + i`'s range at `target_byte_offset + i * byte_size`
+     * — under one handle.
+     *
+     * The run may cross pages; it is split at their boundaries here. Its status is
+     * {@link GPUReadbackStatus.Delivered} only when every row was delivered, and
+     * {@link GPUReadbackStatus.Dropped} when any row was dropped — a page not resident or a row not
+     * occupied when the batch was encoded, a row freed while it was in flight, or the pipeline full
+     * — and then nothing of it is written.
+     *
+     * @param {number} table from {@link table}
+     * @param {number} first_row
+     * @param {number} row_count at least 1
+     * @param {number} byte_offset within each record, word-aligned
+     * @param {number} byte_size per row, a positive multiple of the word size
+     * @param {Uint8Array} target memory the caller owns and keeps, as for {@link request}
+     * @param {number} target_byte_offset where the first row's range lands
+     * @returns {number} a handle into {@link status}, valid until the frame after its result lands
+     */
+    request_run(table: number, first_row: number, row_count: number, byte_offset: number, byte_size: number, target: Uint8Array, target_byte_offset: number): number;
     /**
      * Deliver every batch whose bytes have arrived, oldest first and stopping at the first that has
      * not, then start the map for every batch whose frame has been submitted.

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabaseReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabaseReadback.js"],"names":[],"mappings":"AA6LA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IA+II;;;;;;;OAOG;IACH;QAN2D,QAAQ,EAAxD,OAAO,kBAAkB,EAAE,WAAW;QACnB,MAAM;QACR,gBAAgB,GAAjC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,KAAK,GAAtB,MAAM;OAuBhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;IAED;;;;;OAKG;IACH,8BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;;;;OAQG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;;OAUG;IACH,YAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAVW,MAAM,OACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,uBAGV,MAAM,GACJ,MAAM,CAgDlB;IAED;;;;;;;;;;;OAWG;IACH,SAFa,MAAM,CAiElB;IAED;;;;;OAKG;IACH,gBAHW,OAAO,2CAA2C,EAAE,sBAAsB,GACxE,OAAO,CAyDnB;IAijBD,gBAyBC;;CACJ"}
+{"version":3,"file":"GPUDatabaseReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabaseReadback.js"],"names":[],"mappings":"AAoOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH;IA+II;;;;;;;OAOG;IACH;QAN2D,QAAQ,EAAxD,OAAO,kBAAkB,EAAE,WAAW;QACnB,MAAM;QACR,gBAAgB,GAAjC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,KAAK,GAAtB,MAAM;OAuBhB;IAED;;;;OAIG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;IAED;;;;;OAKG;IACH,8BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;;;;OAQG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;;OAUG;IACH,YAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAVW,MAAM,OACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,uBAGV,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBATW,MAAM,aACN,MAAM,aACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,sBACV,MAAM,GACJ,MAAM,CAkDlB;IAED;;;;;;;;;;;OAWG;IACH,SAFa,MAAM,CAiElB;IAED;;;;;OAKG;IACH,gBAHW,OAAO,2CAA2C,EAAE,sBAAsB,GACxE,OAAO,CAyDnB;IAgpBD,gBAyBC;;CACJ"}