@woosh/meep-engine 3.15.0 → 3.16.0

package/src/engine/graphics3/particles/GPUParticularRenderer.js

@@ -2,7 +2,12 @@ import { assert } from "../../../core/assert.js";
 import { round_up } from "../../../core/math/round_up.js";
 import { TextureDescriptor } from "../../../shade/descriptor/texture/TextureDescriptor.js";
 import { TextureViewDescriptor } from "../../../shade/descriptor/texture/TextureViewDescriptor.js";
-import { EMITTER_STRIDE } from "../../../shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
+import { GPUDatabase } from "../../../shade/renderer/buffer/table/GPUDatabase.js";
+import {
+    PARTICLE_DATABASE_INITIAL_SIZE,
+    PARTICLE_DATABASE_SPEC,
+    PARTICLE_EMITTER_TABLE
+} from "../../../shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js";
 import { PARTICLE_RECORD_WORD_COUNT } from "../../../shade/renderer/particles/ParticleConstants.js";
 import {
     create_particle_billboard_pipeline,
@@ -13,7 +18,7 @@ import { SAMPLER_LINEAR_UPSCALE } from "../../../shade/renderer/texture/SAMPLER_
 import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
 import {
     blending_type_to_particle_blend,
-    write_particle_layer_record,
+    particle_layer_record,
     write_particle_records
 } from "./particle_gpu_records.js";
 
@@ -68,14 +73,26 @@ export class GPUParticularRenderer {
     #slots_capacity = 0;
 
     /**
-     * @type {GPUBuffer|null}
+     * The emitter table the billboard renderer reads a particle's layer record out of.
+     *
+     * A `GPUDatabase` rather than a flat buffer because that is the layout the renderer's generated
+     * reader indexes — the table owns the addressing, the growth and the per-record staging, so
+     * there is nothing here that knows where a record physically lands.
+     *
+     * Built on first use: the device arrives with the frame graph's execution context, not with the
+     * constructor.
+     *
+     * @type {GPUDatabase|null}
      */
-    #emitters = null;
+    #database = null;
 
     /**
-     * @type {number} capacity in emitter records
+     * How many layer records the last pack wrote. Rows past it are removed rather than left
+     * resident, so a frame with fewer layers than the last does not keep paying for them.
+     *
+     * @type {number}
      */
-    #emitters_capacity = 0;
+    #record_count = 0;
 
     /**
      * @type {GPUTextureContext|null}
@@ -117,16 +134,6 @@ export class GPUParticularRenderer {
      */
     #pool_staging_f32 = new Float32Array(0);
 
-    /**
-     * @type {Uint32Array}
-     */
-    #emitter_staging = new Uint32Array(0);
-
-    /**
-     * @type {Float32Array}
-     */
-    #emitter_staging_f32 = new Float32Array(0);
-
     /**
      * Draw order, back to front.
      *
@@ -157,22 +164,33 @@ export class GPUParticularRenderer {
         return this.#count;
     }
 
+    /**
+     * How many layer records the last pack wrote — the occupied rows of the emitter table.
+     *
+     * @returns {number}
+     */
+    get record_count() {
+        return this.#record_count;
+    }
+
     /**
      * Pack this frame's particles and upload them.
      *
      * Runs inside the pass rather than beside it, because a `GraphicsContext` — the device, the
      * texture pool, the samplers — is something the frame graph hands out at execution time and the
-     * frame's pass context does not carry. Uploading there is legal: these are queue writes, not
-     * encoder writes.
+     * frame's pass context does not carry. The pool, the draw order and the atlas go up as queue
+     * writes; the emitter table's rows go up as the database's own upload dispatch, encoded here
+     * ahead of the draw that reads them.
      *
      * @param {GraphicsContext} graphics
+     * @param {ShadeGPUCommandContext} encoder the frame's open command context
      * @param {ParticleEmitter[]} emitters
      * @param {Sampler2D} atlas the sprite atlas every layer's patch is cut from
      * @param {number[]|Float32Array} camera_position world space
      * @param {number[]|Float32Array} camera_right world space
      * @param {number[]|Float32Array} camera_up world space
      */
-    #pack(graphics, emitters, atlas, camera_position, camera_right, camera_up) {
+    #pack(graphics, encoder, emitters, atlas, camera_position, camera_right, camera_up) {
         assert.defined(graphics, 'graphics');
 
         this.#count = 0;
@@ -180,7 +198,6 @@ export class GPUParticularRenderer {
         const drawn = [];
 
         let particle_capacity = 0;
-        let layer_count = 0;
 
         for (let i = 0; i < emitters.length; i++) {
             const emitter = emitters[i];
@@ -198,20 +215,18 @@ export class GPUParticularRenderer {
             drawn.push(emitter);
 
             particle_capacity += particles;
-            layer_count += emitter.layers.length;
         }
 
         if (drawn.length === 0) {
             return;
         }
 
-        this.#reserve_staging(particle_capacity, layer_count);
+        this.#reserve_staging(particle_capacity);
 
         const pool = this.#pool_staging;
         const pool_f32 = this.#pool_staging_f32;
 
-        const emitter_records = this.#emitter_staging;
-        const emitter_records_f32 = this.#emitter_staging_f32;
+        const table = this.#obtain_database(graphics.device).get(PARTICLE_EMITTER_TABLE);
 
         let record_index = 0;
         let written = 0;
@@ -242,11 +257,11 @@ export class GPUParticularRenderer {
 
                 const uv = patch.uv;
 
-                write_particle_layer_record(emitter_records, emitter_records_f32, record_index, {
+                table.set(record_index, particle_layer_record({
                     atlas_region: [uv.position.x, uv.position.y, uv.size.x, uv.size.y],
                     blend,
                     soft_depth
-                });
+                }));
 
                 layer_records[j] = record_index;
 
@@ -262,11 +277,38 @@ export class GPUParticularRenderer {
             return;
         }
 
+        // Layers that were drawn last frame and are not this frame: free their rows, so a busy
+        // frame's page count does not become the floor for every quiet frame after it.
+        for (let i = record_index; i < this.#record_count; i++) {
+            table.remove(i);
+        }
+
+        this.#record_count = record_index;
+
         this.#count = written;
 
         this.#order(written, camera_position);
 
-        this.#upload(graphics, written, record_index, atlas);
+        this.#upload(graphics, encoder, written, atlas);
+    }
+
+    /**
+     * The emitter table's database, built on first use.
+     *
+     * @param {GPUDevice} device
+     * @returns {GPUDatabase}
+     */
+    #obtain_database(device) {
+        if (this.#database === null) {
+            this.#database = new GPUDatabase({
+                device,
+                definition: PARTICLE_DATABASE_SPEC,
+                label: "particular/emitters",
+                initial_data_size_bytes: PARTICLE_DATABASE_INITIAL_SIZE,
+            });
+        }
+
+        return this.#database;
     }
 
     /**
@@ -310,9 +352,8 @@ export class GPUParticularRenderer {
 
     /**
      * @param {number} particle_capacity
-     * @param {number} layer_capacity
      */
-    #reserve_staging(particle_capacity, layer_capacity) {
+    #reserve_staging(particle_capacity) {
         const words = particle_capacity * PARTICLE_RECORD_WORD_COUNT;
 
         if (this.#pool_staging.length < words) {
@@ -328,24 +369,15 @@ export class GPUParticularRenderer {
             this.#slot_staging = new Uint32Array(capacity);
             this.#depth_staging = new Float32Array(capacity);
         }
-
-        const emitter_words = layer_capacity * EMITTER_STRIDE;
-
-        if (this.#emitter_staging.length < emitter_words) {
-            const buffer = new ArrayBuffer(Math.ceil(emitter_words * GROWTH_FACTOR) * 4);
-
-            this.#emitter_staging = new Uint32Array(buffer);
-            this.#emitter_staging_f32 = new Float32Array(buffer);
-        }
     }
 
     /**
      * @param {GraphicsContext} graphics
+     * @param {ShadeGPUCommandContext} encoder the frame's open command context
      * @param {number} count
-     * @param {number} record_count
      * @param {Sampler2D} atlas
      */
-    #upload(graphics, count, record_count, atlas) {
+    #upload(graphics, encoder, count, atlas) {
         const device = graphics.device;
 
         this.#pool = this.#obtain_buffer(
@@ -358,14 +390,11 @@ export class GPUParticularRenderer {
             capacity => this.#slots_capacity = capacity
         );
 
-        this.#emitters = this.#obtain_buffer(
-            device, this.#emitters, record_count * EMITTER_STRIDE * 4, "particular/emitters",
-            capacity => this.#emitters_capacity = capacity
-        );
-
         device.queue.writeBuffer(this.#pool, 0, this.#pool_staging, 0, count * PARTICLE_RECORD_WORD_COUNT);
         device.queue.writeBuffer(this.#slots, 0, this.#slot_staging, 0, count);
-        device.queue.writeBuffer(this.#emitters, 0, this.#emitter_staging, 0, record_count * EMITTER_STRIDE);
+
+        // Rows staged by #pack reach the buffer here, encoded before the draw that reads them.
+        this.#database.update(encoder);
 
         this.#obtain_atlas(graphics, atlas);
     }
@@ -469,7 +498,7 @@ export class GPUParticularRenderer {
         const data = {};
 
         const pass = graph.add('particles', data, (data, resources, context) => {
-            this.#pack(context.graphics, emitters, atlas, camera_position, camera_right, camera_up);
+            this.#pack(context.graphics, context.encoder, emitters, atlas, camera_position, camera_right, camera_up);
 
             this.#execute(data, resources, context, camera);
         });
@@ -509,8 +538,8 @@ export class GPUParticularRenderer {
         const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
             camera,
             pool: this.#pool,
-            sorted: this.#slots,
-            emitters: this.#emitters,
+            draw_list: this.#slots,
+            emitter_database: this.#database.buffer,
             atlas: this.#atlas.obtainView(),
             atlas_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
             scene_depth: depth_view
@@ -580,10 +609,10 @@ export class GPUParticularRenderer {
             this.#slots_capacity = 0;
         }
 
-        if (this.#emitters !== null) {
-            this.#emitters.destroy();
-            this.#emitters = null;
-            this.#emitters_capacity = 0;
+        if (this.#database !== null) {
+            this.#database.destroy();
+            this.#database = null;
+            this.#record_count = 0;
         }
 
         if (this.#atlas !== null) {

package/src/engine/graphics3/particles/particle_gpu_records.d.ts

@@ -12,26 +12,30 @@
  */
 export function blending_type_to_particle_blend(blending_type: BlendingType): number;
 /**
- * Describe one particle layer to the billboard renderer.
+ * One particle layer as a row of the emitter table
+ * ({@link ../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js}).
  *
  * **A record per layer, not per emitter.** The renderer reads the sprite's atlas rectangle from the
  * emitter record, and in meep the sprite belongs to the *layer* — one emitter's particles can come
  * from several layers with different sprites. Since every particle names its own record, splitting
  * this way costs nothing and keeps the draw a single one.
  *
- * @param {Uint32Array} records
- * @param {Float32Array} records_f32 the same buffer, viewed as floats
- * @param {number} index record index
+ * Every field of the struct is filled, including the ones a CPU-simulated layer has no use for (the
+ * VM program offsets, the seed, the spawn rate). A field left out is not written as zero — the
+ * serializer skips it and the table's page buffers are recycled, so an omitted field would show
+ * whatever the slot's previous tenant left behind.
+ *
  * @param {object} layer
- * @param {number[]} layer.atlas_region uv offset x, y and uv scale x, y
+ * @param {ArrayLike<number>} layer.atlas_region uv offset x, y and uv scale x, y
  * @param {number} layer.blend a member of {@link EMITTER_BLEND}
  * @param {boolean} layer.soft_depth
+ * @returns {object} the value to store in the emitter table
  */
-export function write_particle_layer_record(records: Uint32Array, records_f32: Float32Array, index: number, { atlas_region, blend, soft_depth }: {
-    atlas_region: number[];
+export function particle_layer_record({ atlas_region, blend, soft_depth }: {
+    atlas_region: ArrayLike<number>;
     blend: number;
     soft_depth: boolean;
-}): void;
+}): object;
 /**
  * Write one emitter's live particles into the shared pool.
  *

package/src/engine/graphics3/particles/particle_gpu_records.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_gpu_records.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/particles/particle_gpu_records.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;GAWG;AACH,+DAHW,YAAY,GACV,MAAM,CAQlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qDARW,WAAW,eACX,YAAY,SACZ,MAAM;IAEU,YAAY,EAA5B,MAAM,EAAE;IACM,KAAK,EAAnB,MAAM;IACS,UAAU,EAAzB,OAAO;SAsCjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6CATW,WAAW,YACX,YAAY,cACZ,MAAM,2CAEN,MAAM,EAAE,gBACR,MAAM,EAAE,aACR,MAAM,EAAE,GACN,MAAM,CA4ElB;AApMD;;;;;;;GAOG;AACH,qCAFU,MAAM,CAEwB;AAExC;;GAEG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;GAEG;AACH,kCAFU,MAAM,CAEqB;AAErC;;GAEG;AACH,qCAFU,MAAM,CAEwB;6BA9CX,gDAAgD"}
+{"version":3,"file":"particle_gpu_records.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/particles/particle_gpu_records.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;GAWG;AACH,+DAHW,YAAY,GACV,MAAM,CAQlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IALoC,YAAY,EAArC,UAAU,MAAM,CAAC;IACH,KAAK,EAAnB,MAAM;IACS,UAAU,EAAzB,OAAO;IACL,MAAM,CA0ClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6CATW,WAAW,YACX,YAAY,cACZ,MAAM,2CAEN,MAAM,EAAE,gBACR,MAAM,EAAE,aACR,MAAM,EAAE,GACN,MAAM,CA4ElB;AA5MD;;;;;;;GAOG;AACH,qCAFU,MAAM,CAEwB;AAExC;;GAEG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;GAEG;AACH,kCAFU,MAAM,CAEqB;AAErC;;GAEG;AACH,qCAFU,MAAM,CAEwB;6BA9CX,gDAAgD"}

package/src/engine/graphics3/particles/particle_gpu_records.js

@@ -12,11 +12,11 @@ import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/
 import {
     EMITTER_ATTRIBUTE_ABSENT,
     EMITTER_BLEND,
-    EMITTER_FIELD,
-    EMITTER_FLAG,
     EMITTER_PROJECTION,
-    EMITTER_STRIDE
-} from "../../../shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
+    make_emitter_flags
+} from "../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_GENERATION_FIRST } from "../../../shade/renderer/particles/data/particle_header.js";
+import { NODE3D_SCENE_ID } from "../../../shade/renderer/scene/NODE3D_STRUCT.js";
 import {
     PARTICLE_RECORD_HEADER_EMITTER,
     PARTICLE_RECORD_WORD_COUNT
@@ -68,57 +68,65 @@ export function blending_type_to_particle_blend(blending_type) {
 }
 
 /**
- * Describe one particle layer to the billboard renderer.
+ * One particle layer as a row of the emitter table
+ * ({@link ../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js}).
  *
  * **A record per layer, not per emitter.** The renderer reads the sprite's atlas rectangle from the
  * emitter record, and in meep the sprite belongs to the *layer* — one emitter's particles can come
  * from several layers with different sprites. Since every particle names its own record, splitting
  * this way costs nothing and keeps the draw a single one.
  *
- * @param {Uint32Array} records
- * @param {Float32Array} records_f32 the same buffer, viewed as floats
- * @param {number} index record index
+ * Every field of the struct is filled, including the ones a CPU-simulated layer has no use for (the
+ * VM program offsets, the seed, the spawn rate). A field left out is not written as zero — the
+ * serializer skips it and the table's page buffers are recycled, so an omitted field would show
+ * whatever the slot's previous tenant left behind.
+ *
  * @param {object} layer
- * @param {number[]} layer.atlas_region uv offset x, y and uv scale x, y
+ * @param {ArrayLike<number>} layer.atlas_region uv offset x, y and uv scale x, y
  * @param {number} layer.blend a member of {@link EMITTER_BLEND}
  * @param {boolean} layer.soft_depth
+ * @returns {object} the value to store in the emitter table
  */
-export function write_particle_layer_record(records, records_f32, index, { atlas_region, blend, soft_depth }) {
-    assert.isNonNegativeInteger(index, 'index');
-
-    const base = index * EMITTER_STRIDE;
-
-    records.fill(0, base, base + EMITTER_STRIDE);
-
-    let flags = blend << 4;
-
-    if (soft_depth) {
-        flags |= EMITTER_FLAG.SOFT_DEPTH;
-    }
-
-    // BILLBOARD: the quad faces the camera and the rotation attribute rolls it in the view plane,
-    // which is what the legacy point sprite does. Velocity alignment is folded into that rotation
-    // when the particles are written, rather than being a projection mode of its own.
-    flags |= EMITTER_PROJECTION.BILLBOARD << 6;
-
-    records[base + EMITTER_FIELD.FLAGS] = flags;
-
-    records[base + EMITTER_FIELD.RENDER_POSITION] = PARTICLE_WORD_POSITION;
-    records[base + EMITTER_FIELD.RENDER_SIZE] = PARTICLE_WORD_SIZE;
-    records[base + EMITTER_FIELD.RENDER_COLOR] = PARTICLE_WORD_COLOR;
-    records[base + EMITTER_FIELD.RENDER_ROTATION] = PARTICLE_WORD_ROTATION;
-    records[base + EMITTER_FIELD.RENDER_FRAME] = EMITTER_ATTRIBUTE_ABSENT;
-    records[base + EMITTER_FIELD.RENDER_VELOCITY] = EMITTER_ATTRIBUTE_ABSENT;
-
-    records_f32[base + EMITTER_FIELD.ATLAS_REGION] = atlas_region[0];
-    records_f32[base + EMITTER_FIELD.ATLAS_REGION + 1] = atlas_region[1];
-    records_f32[base + EMITTER_FIELD.ATLAS_REGION + 2] = atlas_region[2];
-    records_f32[base + EMITTER_FIELD.ATLAS_REGION + 3] = atlas_region[3];
-
-    // one cell: the sprite sheet animation the flipbook exists for is a later feature, and a 1x1
-    // grid is the identity of that mapping rather than a disabled branch
-    records_f32[base + EMITTER_FIELD.FLIPBOOK] = 1;
-    records_f32[base + EMITTER_FIELD.FLIPBOOK + 1] = 1;
+export function particle_layer_record({ atlas_region, blend, soft_depth }) {
+    return {
+        // BILLBOARD: the quad faces the camera and the rotation attribute rolls it in the view
+        // plane, which is what the legacy point sprite does. Velocity alignment is folded into that
+        // rotation when the particles are written, rather than being a projection mode of its own.
+        flags: make_emitter_flags({
+            soft_depth,
+            blend,
+            projection: EMITTER_PROJECTION.BILLBOARD,
+        }),
+
+        atlas_region,
+
+        render_position: PARTICLE_WORD_POSITION,
+        render_size: PARTICLE_WORD_SIZE,
+        render_color: PARTICLE_WORD_COLOR,
+        render_rotation: PARTICLE_WORD_ROTATION,
+        render_frame: EMITTER_ATTRIBUTE_ABSENT,
+        render_velocity: EMITTER_ATTRIBUTE_ABSENT,
+
+        // one cell: the sprite sheet animation the flipbook exists for is a later feature, and a
+        // 1x1 grid is the identity of that mapping rather than a disabled branch
+        flipbook: [1, 1],
+
+        // meep simulates these particles on the CPU, so there is no VM program, no seed and no
+        // GPU-side spawning behind this record — only the drawing half of it is ever read. The
+        // node is the scene root, which is as good as any: the particles carry world positions.
+        init_offset: 0,
+        init_count: 0,
+        update_offset: 0,
+        update_count: 0,
+        constant_offset: 0,
+        program_id: 0,
+        seed: 0,
+        spawn_rate: 0,
+        node: NODE3D_SCENE_ID,
+        generation: PARTICLE_GENERATION_FIRST,
+        bounds_center: [0, 0, 0],
+        bounds_radius: 0,
+    };
 }
 
 /**

package/src/engine/graphics3/preview/make_model_preview_scene.js

@@ -144,7 +144,7 @@ export function make_model_preview_scene(bundle, framing, aspect_ratio) {
      Shade's own samples put a camera at negative Z looking back at the origin, so that is where a
      preview's camera stands.
     */
-    camera.transform.position.set(0, 0, -framing.camera_distance);
+    camera.transform.setTranslation(0, 0, -framing.camera_distance);
 
     camera.transform.lookAt(scratch_target);
 

package/src/engine/graphics3/shade_camera_projection_ray.js

@@ -59,11 +59,11 @@ export function shade_camera_projection_ray(camera, x, y, out_source, out_direct
 
     v3_matrix4_multiply(SCRATCH_WORLD, 0, SCRATCH_CLIP, 0, SCRATCH_INVERSE);
 
-    const position = camera.transform.position;
+    const position = camera.transform;
 
-    const origin_x = position.x;
-    const origin_y = position.y;
-    const origin_z = position.z;
+    const origin_x = position.translation_x;
+    const origin_y = position.translation_y;
+    const origin_z = position.translation_z;
 
     out_source.set(origin_x, origin_y, origin_z);
 

package/src/engine/graphics3/shade_node_to_entity_composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shade_node_to_entity_composition.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/shade_node_to_entity_composition.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,gEAFa,UAAU,CAwBtB;AAED;;;;;;;;GAQG;AACH,yEAFa,UAAU,CAmBtB;2BAlF0B,6BAA6B"}
+{"version":3,"file":"shade_node_to_entity_composition.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/shade_node_to_entity_composition.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,gEAFa,UAAU,CA6BtB;AAED;;;;;;;;GAQG;AACH,yEAFa,UAAU,CAmBtB;2BAtF0B,6BAA6B"}