@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -43,6 +43,25 @@ export class Renderer {
      * @type {AVBOITSettings}
      */
     avboit: AVBOITSettings;
+    /**
+     * GPU particles. When on, every {@link ParticleEmitter} node in the scene is simulated on the
+     * GPU each frame and its particles are drawn through the AVBOIT transparency pipeline as a
+     * side channel of the transparent meshes — order-independently, against them and against the
+     * opaque scene. Under {@link ShadeTransparencyMode.MBOIT} the particles are simulated but not
+     * drawn: that path is legacy and gets no new sources.
+     *
+     * @type {boolean}
+     */
+    feature_particles_enabled: boolean;
+    /**
+     * Most particles alive at once in a scene — the pool every emitter of that scene draws its
+     * records from. Read once, when the scene's {@link GPUParticleSystem} is created on the first
+     * frame {@link feature_particles_enabled} is on for it; the pool does not grow afterwards, so
+     * set this before that frame. Left undefined, the system's own default applies.
+     *
+     * @type {number|undefined}
+     */
+    particle_capacity: number | undefined;
     feature_ssr_enabled: boolean;
     feature_ssao_enabled: boolean;
     /**
@@ -333,6 +352,14 @@ export class Renderer {
      * @returns {ReSTIRDI}
      */
     get restir_di(): ReSTIRDI;
+    /**
+     * The particle system of a scene — created on first use, so a scene without emitters costs
+     * nothing until {@link feature_particles_enabled} turns it on.
+     *
+     * @param {GPUSceneContext} scene_ctx
+     * @returns {GPUParticleSystem}
+     */
+    particles(scene_ctx: GPUSceneContext): GPUParticleSystem;
     /**
      * Selects which temporal-AA / upscaler runs at the temporal-resolve
      * stage. Defaults to {@link ShadeUpscalerType.TAA}; assign
@@ -416,6 +443,7 @@ import { FramePhase } from "./extension/FramePhase.js";
 import { CascadedSceneSDF } from "./shadow/sdf/cascade/CascadedSceneSDF.js";
 import { GPULightProbeVolumeRenderer } from "./global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js";
 import { ReSTIRDI } from "./restir/di/ReSTIRDI.js";
+import { GPUParticleSystem } from "./particles/GPUParticleSystem.js";
 import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
 import { NSS } from "./postprocess/nss/NSS.js";
 import { AccumulatingPathTracer } from "./path_tracer/accumulating/AccumulatingPathTracer.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":"AAiGA;IAOI,0BAEC;IAED;;OAEG;IACH,0BAAQ;IAER;;;;;;OAMG;IACH,kDAEC;IAED;;OAEG;IACH,kBAAO;IAYP;;;OAGG;IACH,2BAEC;IAaD,0CAGC;IAED,uCAEC;IAED;;;;OAIG;IACH,wBAFU,yBAAyB,CAEoB;IAEvD;;;;;;;OAOG;IACH,mBAFU,qBAAqB,CAEkB;IAEjD;;;OAGG;IACH,QAFU,cAAc,CAEM;IAE9B,6BAA4B;IAC5B,8BAA4B;IAC5B;;;;OAIG;IACH,mCAAkC;IAClC;;;;;;;OAOG;IACH,mCAFU,OAAO,CAEyB;IAC1C,+BAA6B;IAC7B,4CAA0C;IAkB1C,uCAKC;IArBD;;;;;;;;;;OAUG;IACH,oCAGC;IASD;;;;;;;OAOG;IACH,0BAFU,OAAO,CAEe;IAQhC;;;;;OAKG;IACH,sCAOC;IAjBD,mCAEC;IAiBD;;;;;;;;;OASG;IACH,6BAFU,OAAO,CAEmB;IAWpC;;;;;OAKG;IACH,8BAA+C;IAE/C;;;;;;;;OAQG;IACH,6BAFU,OAAO,CAEmB;IAEpC;;;;;;;;;;;;;;OAcG;IACH,8BAFU,OAAO,CAEoB;IAErC;;;;;;;;;;OAUG;IACH,qBAFU,OAAO,CAEW;IAU5B;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;;;;;OAQG;IACH,eAFU,UAAU,GAAC,QAAQ,CAEF;IAU3B;;;;OAIG;IACH,gCAAwD;IAExD;;;;;;;;;;;;OAYG;IACH,gBAFU,OAAO,CAEK;IAEtB;;;OAGG;IACH,4BAFU,OAAO,CAEiB;IAKlC;;;OAGG;IACH,yBAEC;IAOD;;;OAGG;IACH,gCAEC;IAcD;;;;;;;;;OASG;IACH,qBAA+B;IAE/B,wBAA+B;IAgB/B;;;OAGG;IACH,2CAeC;IAED;;;OAGG;IACH,wCAEC;IA0BD;;;OAGG;IACH,iCAEC;IAED;;;;OAIG;IACH,2BAEC;IAQD;;;OAGG;IACH,+CAIC;IAED;;;OAGG;IACH,gDAIC;IAwCD;;;OAGG;IACH,6BAcC;IA1BD;;;OAGG;IACH,0BAEC;IAsBD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAFU,oBAAkB,IAAI,CAET;IAEvB;;OAEG;IACH;;;;;;;;;;;;;;OAcG;IACH,2DAEC;IAED;;;;;OAKG;IACH,8CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,UAAU,GACR,MAAM,CAIlB;IAgBD;;;;OAIG;IACH,iCAFY,gBAAgB,CAW3B;IAED;;;OAGG;IACH,6BAYC;IAED;;;;OAIG;IACH,wCAFa,2BAA2B,CAcvC;IAGD;;;OAGG;IACH,+BAuBC;IAmMD;;;;OAIG;IACH,0BAEC;IAgBD;;;;;;OAMG;IACH,cAFU,iBAAiB,CAEU;IAErC;;;;;;OAMG;IACH,eAgBC;IAiFD;;;;;OAKG;IACH,+EAkOC;IAED;;OAEG;IACH,gBAGC;IAQD,4BAwBC;IAqID;;;;;OAKG;IACH,UAHW,MAAM,KACN,MAAM,QAgBhB;IAoFD,0CAMC;IAED;;;;;;;;;;OAUG;IACH,qEAHW,MAAM,GACJ,OAAO,CAsBnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,8EAJW,MAAM,UACN,iBAAiB,GACf,OAAO,CAm1BnB;;CACJ;6BAn5E4B,yBAAyB;0CACZ,gCAAgC;sCACpC,4BAA4B;+BACnC,6CAA6C;2BAzBjD,yCAAyC;6BAFvC,4CAA4C;8BAD3C,2CAA2C;4BAsC7C,uBAAuB;gCA3CnB,sBAAsB;mBArCnC,oCAAoC;oBACnC,4BAA4B;kCA4Ed,gCAAgC;2BAzDvC,2BAA2B;iCAuDrB,0CAA0C;4CAzC/B,+DAA+D;yBAgClF,yBAAyB;kCAQhB,wBAAwB;oBA5BtC,0BAA0B;uCAPP,sDAAsD"}
+{"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

@@ -66,6 +66,8 @@ import {
 import { RasterizationJob } from "./rasterize/RasterizationJob.js";
 import { graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scene.js";
 import { ReSTIRDI } from "./restir/di/ReSTIRDI.js";
+import { GPUParticleSystem } from "./particles/GPUParticleSystem.js";
+import { ParticleRenderMode } from "./particles/ParticleRenderMode.js";
 import { SceneManager } from "./scene/SceneManager.js";
 import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
 import { ShadeTransparencyMode } from "./ShadeTransparencyMode.js";
@@ -188,6 +190,27 @@ export class Renderer {
      */
     avboit = new AVBOITSettings();
 
+    /**
+     * GPU particles. When on, every {@link ParticleEmitter} node in the scene is simulated on the
+     * GPU each frame and its particles are drawn through the AVBOIT transparency pipeline as a
+     * side channel of the transparent meshes — order-independently, against them and against the
+     * opaque scene. Under {@link ShadeTransparencyMode.MBOIT} the particles are simulated but not
+     * drawn: that path is legacy and gets no new sources.
+     *
+     * @type {boolean}
+     */
+    feature_particles_enabled = false;
+
+    /**
+     * Most particles alive at once in a scene — the pool every emitter of that scene draws its
+     * records from. Read once, when the scene's {@link GPUParticleSystem} is created on the first
+     * frame {@link feature_particles_enabled} is on for it; the pool does not grow afterwards, so
+     * set this before that frame. Left undefined, the system's own default applies.
+     *
+     * @type {number|undefined}
+     */
+    particle_capacity = undefined;
+
     feature_ssr_enabled = false;
     feature_ssao_enabled = true;
     /**
@@ -974,6 +997,37 @@ export class Renderer {
         return this.#restir_di;
     }
 
+    /**
+     * One particle system per scene context: the emitters are the scene's nodes, and the system's
+     * buffers hold that scene's particles.
+     * @type {Map<GPUSceneContext, GPUParticleSystem>}
+     */
+    #particle_systems = new Map();
+
+    /**
+     * The side-channel list handed to the transparency orchestrator, reused frame to frame.
+     * @type {GPUParticleSystem[]}
+     */
+    #particle_side_channels = [];
+
+    /**
+     * The particle system of a scene — created on first use, so a scene without emitters costs
+     * nothing until {@link feature_particles_enabled} turns it on.
+     *
+     * @param {GPUSceneContext} scene_ctx
+     * @returns {GPUParticleSystem}
+     */
+    particles(scene_ctx) {
+        let system = this.#particle_systems.get(scene_ctx);
+
+        if (system === undefined) {
+            system = new GPUParticleSystem(this.#graphics, scene_ctx, { capacity: this.particle_capacity });
+            this.#particle_systems.set(scene_ctx, system);
+        }
+
+        return system;
+    }
+
     /**
      *
      * @type {TAA}
@@ -1341,6 +1395,11 @@ export class Renderer {
     destroy() {
 
         window.matchMedia("(dynamic-range: high)").removeEventListener("change", this.#update_hdr_support);
+
+        for (const system of this.#particle_systems.values()) {
+            system.destroy();
+        }
+        this.#particle_systems.clear();
     }
 
 
@@ -1801,15 +1860,27 @@ export class Renderer {
         raster_main.opaque_pass = viz_rasterization_opaque_pass_descriptor;
         raster_main.alpha_tested_pass = viz_rasterization_alpha_tested_pass_descriptor;
 
-        const gr_render_buckets = graph_rasterize_scene({
+        /*
+         Taken from the rasterizer rather than re-imported. These are the very textures it just
+         wrote, and importing them a second time gave one physical texture two unrelated
+         ResourceEntry chains with no edge between the passes that wrote it and the passes that read
+         it. Correct today only because a pass writing an imported resource is a side-effect pass
+         that culling may not touch; make these targets transient — the TODO on `#vis_render_target`
+         asks for exactly that — and the whole opaque chain culls itself, silently.
+        */
+        const {
+            buckets: gr_render_buckets,
+            depth: gr_raster_depth,
+            color_targets: gr_raster_color_targets,
+        } = graph_rasterize_scene({
             job: raster_main,
             graph,
             limits: graphics.collection_limits,
         });
 
         // `let` rather than `const` because an extension at `AfterGBuffer` may publish replacements
-        let gr_viz_buffer_triangle = graph_import_texture(graph, this.#vis_render_target.color_attachments[0], "viz_triangle");
-        let gr_viz_buffer_mesh = graph_import_texture(graph, this.#vis_render_target.color_attachments[1], "viz_mesh");
+        let gr_viz_buffer_triangle = gr_raster_color_targets[0];
+        let gr_viz_buffer_mesh = gr_raster_color_targets[1];
 
         // Virtual texture feedback: derive per-pixel page usage from the viz
         // buffer (no extra geometry pass) into a unique-request hash set and
@@ -1854,7 +1925,8 @@ export class Renderer {
 
 
         const gr_texture_canvas = graph_import_texture(graph, target, "canvas");
-        let gr_texture_depth_current = graph_import_texture(graph, this.texture_depth_current, "depth");
+        // the depth the rasterizer left, not a second import of the same texture
+        let gr_texture_depth_current = gr_raster_depth;
         const gr_buffer_camera_current = graph_import_buffer(graph, view_ctx.camera.gpu_buffer, "camera/current");
         const gr_buffer_camera_previous = graph_import_buffer(graph, view_ctx.gpu_previous_camera_state.gpu_buffer, "camera/previous");
         const gr_texture_hzb = graph_import_texture(graph, view_ctx.hierarchical_z_buffer.texture, "HZB");
@@ -2099,6 +2171,16 @@ export class Renderer {
             gr_texture_material_albedo_ao = ssao.occlusion;
             bent_normals = ssao.bent_normals;
 
+            /*
+             The composite wrote the albedo target, so the handle the record carries is now a
+             version an earlier pass has superseded. `GBufferTextures` stays readable through
+             `BeforePresent`, so anything reading it from `AfterLighting` on would be reading a
+             superseded handle — rejected by validate() in a dev build, and read silently in a
+             stripped one. Latent only because every shipped consumer happens to run at
+             `AfterGBuffer`.
+            */
+            record_gbuffer.republish_albedo(gr_texture_material_albedo_ao);
+
         } else {
 
             // default to shading normals
@@ -2240,6 +2322,35 @@ export class Renderer {
         current_color_out = record_scene_color.color;
         gr_texture_depth_current = record_view_textures.depth;
 
+        // Particles move here, after the scene's nodes have their world matrices for the frame, and
+        // draw below as a side channel of the transparency pipeline.
+        const particle_side_channels = this.#particle_side_channels;
+        particle_side_channels.length = 0;
+
+        if (this.feature_particles_enabled) {
+            const particles = this.particles(scene_ctx);
+
+            // The simulation runs here; the drawing is the side channels', below. AVBOIT mode is
+            // what says so: the colour comes back untouched, no sort is recorded, and none of the
+            // sort's scratch is ever allocated, because the accumulators it would feed are sums.
+            //
+            // Not conditional on {@link transparency_mode}. MBOIT has no particle channel, so under
+            // it the particles simulate and are not drawn — the same as before this was a mode, and
+            // the `ShadeTransparencyMode` docs say why the legacy path stays as it is. Giving MBOIT
+            // `BILLBOARD` here would draw them, but over the transparency composite rather than
+            // through it, which is a worse picture than none.
+            current_color_out = particles.execute({
+                graph,
+                camera: gr_buffer_camera_current,
+                scene_database: gr_scene_database_for_velocity,
+                color: current_color_out,
+                dt: time_delta_seconds,
+                mode: ParticleRenderMode.AVBOIT,
+            });
+
+            particle_side_channels.push(particles);
+        }
+
         if (this.#feature_enabled_transparencies) {
             // do transparent alpha pass
             graph.push_scope("transparencies");
@@ -2271,6 +2382,7 @@ export class Renderer {
 
                 indirect_lighting_mode: this.indirect_lighting_mode,
                 avboit: this.avboit,
+                side_channels: particle_side_channels,
             });
 
             graph.pop_scope();
@@ -2491,13 +2603,41 @@ export class Renderer {
             profile_recorder.attach_graph(graph);
         }
 
-        command_ctx.encodeGraph(graph);
+        /**
+         * What a pass raised, if anything. Held so the frame's teardown runs before it is re-raised.
+         * @type {*}
+         */
+        let frame_error = null;
+
+        try {
+            command_ctx.encodeGraph(graph);
 
-        command_ctx.popDebugGroup();
+            command_ctx.popDebugGroup();
 
-        view_ctx.finish_frame(command_ctx);
+            view_ctx.finish_frame(command_ctx);
+        } catch (e) {
+            frame_error = e;
+        }
 
-        command_ctx.finish();
+        /*
+         `finish()` is what resolves `profiling_absorbed`, destroys this frame's query set and its
+         resolve/readback buffers, and — through the block below — lets the recorder drop the
+         handlers it holds on the graph. Hanging all of that off the statement after `encodeGraph`
+         meant a throwing pass left the recorder subscribed to a dead graph, holding the whole frame
+         graph and every pass closure in it reachable, one query set and two buffers never
+         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.
+        */
+        try {
+            command_ctx.finish();
+        } catch (teardown_error) {
+            if (frame_error === null) {
+                throw teardown_error;
+            }
+
+            // Already unwinding. A partial command buffer refusing to close is a consequence of the
+            // pass failure, and the pass failure is the one the caller needs to see.
+        }
 
         if (profile_recorder !== null) {
             /*
@@ -2513,6 +2653,10 @@ export class Renderer {
             });
         }
 
+        if (frame_error !== null) {
+            throw frame_error;
+        }
+
         this.#end_frame();
 
         return true;

package/src/shade/renderer/atmosphere/GPUSky.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSky.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/GPUSky.js"],"names":[],"mappings":"AAUA;IAuCI;;;OAGG;IACH,uCAmBC;IAlDD;;;OAGG;IACH,2CAEC;IAOD;;;OAGG;IACH,iDAEC;IAiCD,gBAGC;IAED,cAYC;IAED;;OAEG;IACH,eA+CC;;CAEJ;kCA3IiC,iCAAiC"}
+{"version":3,"file":"GPUSky.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/GPUSky.js"],"names":[],"mappings":"AAUA;IAuCI;;;OAGG;IACH,uCAmBC;IAlDD;;;OAGG;IACH,2CAEC;IAOD;;;OAGG;IACH,iDAEC;IAiCD,gBAGC;IAED,cAYC;IAED;;OAEG;IACH,eAiDC;;CAEJ;kCA7IiC,iCAAiC"}

package/src/shade/renderer/atmosphere/GPUSky.js

@@ -109,7 +109,9 @@ export class GPUSky {
         const gr_transmittance = graph.import_resource("transmittance", TextureResourceDescriptor.fromTexture(this.#lut_transmittance.gpu_texture), this.#lut_transmittance);
         const gr_multiscatter = graph.import_resource("multiscatter", TextureResourceDescriptor.fromTexture(this.#lut_multiple_scattering.gpu_texture), this.#lut_multiple_scattering);
 
-        graph_image_pass({
+        // the handle the write produced, not the one imported: binding the pre-write version below
+        // is a superseded read, which is exactly what `validate()` rejects
+        const [gr_transmittance_written] = graph_image_pass({
             graph,
             shader: shader_transmittance_lut,
             inputs: {
@@ -130,7 +132,7 @@ export class GPUSky {
             // dispatch cannot cover a different area than the shader stores into
             group_count: [this.#lut_multiple_scattering.width, this.#lut_multiple_scattering.height, 1],
             bindings: {
-                tSkyLutTransmittance: gr_transmittance,
+                tSkyLutTransmittance: gr_transmittance_written,
                 tSkyLutMultiscatterOut: gr_multiscatter
             }
         });

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

@@ -1 +1 @@
-{"version":3,"file":"graph_read_buffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/graph_read_buffer.js"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,yFAFa,QAAQ,UAAU,WAAW,CAAC,CAAC,CAgH3C;0BA7HyB,2CAA2C"}
+{"version":3,"file":"graph_read_buffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/graph_read_buffer.js"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,yFAFa,QAAQ,UAAU,WAAW,CAAC,CAAC,CAuH3C;0BApIyB,2CAA2C"}

package/src/shade/renderer/buffer/graph_read_buffer.js

@@ -52,7 +52,14 @@ export function graph_read_buffer({
          */
         const source = resources.get(buffer);
 
-        const _size = size ?? (source.size - offset);
+        /*
+         From the descriptor, not from `source.size`. The transient pool matches approximately — any
+         pooled buffer at least as large as the request, within a slack bound — so the concrete
+         resource is routinely bigger than the resource the caller named. Defaulting from it makes
+         the byte count a function of pool state: the same call reads a different number of bytes
+         run to run, and everything past the descriptor's size is the previous tenant's data.
+        */
+        const _size = size ?? (resources.getDescriptor(buffer).size - offset);
 
         const encoder = context.encoder;
 

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

@@ -369,7 +369,7 @@ export class GPUTypedTable {
         assert.isNonNegativeInteger(page_index, 'page_index');
         const page_limit = this.descriptor.page_limit;
         assert.lessThan(page_index, page_limit, `'page_index' must be less than ${page_limit} (page limit) but was ${page_index}`);
-        assert(this.pages.has(page_index) === false, 'page already allocated');
+        assert.ok(this.pages.has(page_index) === false, 'page already allocated');
 
         const page = new GPUPageMetadata();
         page.index = page_index;

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

@@ -120,6 +120,14 @@ export class GPUTypedTableDescriptor {
      * @returns {CodeChunk}
      */
     chunk_iterate(group_size_x: number, rw?: boolean): CodeChunk;
+    /**
+     * Cached {@link wgsl_gen_read_field_code} chunk for one field of this
+     * table's record type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    chunk_read_field(field_name: string): CodeChunk;
     /**
      *
      * @returns {string}
@@ -149,6 +157,13 @@ export class GPUTypedTableDescriptor {
      * @returns {string}
      */
     marshalling_method_write_field(field_name: string): string;
+    /**
+     * Name of the function that reads only one field of a record.
+     * Pair with {@link wgsl_gen_read_field_code} to emit the body.
+     * @param {string} field_name
+     * @returns {string}
+     */
+    marshalling_method_read_field(field_name: string): string;
     /**
      * Name prefix for all WGSL symbols generated by {@link wgsl_gen_iterate_code}
      * for the given workgroup size. Helpers append `_setup`, `_is_occupied`,
@@ -246,6 +261,21 @@ export class GPUTypedTableDescriptor {
      * @returns {CodeChunk}
      */
     wgsl_gen_iterate_code(group_size_x: number, rw?: boolean): CodeChunk;
+    /**
+     * Generate a reader that touches only a single struct field of a record.
+     *
+     * The whole-record reader deserializes every field — for a wide record that
+     * is a lot of loads to reach one word. A pass that runs per particle rather
+     * than per record (the simulation-order histogram reads nothing but the
+     * emitter's program id) pays that on every invocation.
+     *
+     * Only struct-typed records support this — other shapes have no field
+     * concept. The field's WGSL type is mirrored in the return type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    wgsl_gen_read_field_code(field_name: string): CodeChunk;
     /**
      * Generate a writer that touches only a single struct field of a record.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"GPUTypedTableDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTableDescriptor.js"],"names":[],"mappings":"AASA;IA+FI;;;;;;;OAOG;IACH,gDALW,MAAM,eACN,MAAM,EA4ChB;IA9ID;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,iBAAK;IAEL;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,2BAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,qCAEC;IAED;;;OAGG;IACH,6BAEC;IA2ED;;;OAGG;IACH,4BAKC;IAED;;;;;;;;OAQG;IACH,+BAKC;IAED;;;OAGG;IACH,6BAKC;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,OACN,OAAO,GAKL,SAAS,CAUrB;IAED;;;OAGG;IACH,8BAYC;IAED;;;OAGG;IACH,sCAEC;IAED;;;;;OAKG;IACH,yCAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;;;OAKG;IACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,0CARW,MAAM,OACN,OAAO,GAKL,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,wBANW,OAAO,GAIL,SAAS,CAyBrB;IAED;;;OAGG;IACH,uBAFa,SAAS,CAqBrB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,oCARW,MAAM,OACN,OAAO,GAKL,SAAS,CAwOrB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCAHW,MAAM,GACJ,SAAS,CAmCrB;IA2BD;;;;OAIG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAMlB;IAED,eAEC;IAED,mBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;;CAN1D;0BA5vByB,oCAAoC"}
+{"version":3,"file":"GPUTypedTableDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTableDescriptor.js"],"names":[],"mappings":"AASA;IA+FI;;;;;;;OAOG;IACH,gDALW,MAAM,eACN,MAAM,EA4ChB;IA9ID;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,iBAAK;IAEL;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,2BAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,qCAEC;IAED;;;OAGG;IACH,6BAEC;IAkFD;;;OAGG;IACH,4BAKC;IAED;;;;;;;;OAQG;IACH,+BAKC;IAED;;;OAGG;IACH,6BAKC;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,OACN,OAAO,GAKL,SAAS,CAUrB;IAED;;;;;;OAMG;IACH,6BAHW,MAAM,GACJ,SAAS,CASrB;IAED;;;OAGG;IACH,8BAYC;IAED;;;OAGG;IACH,sCAEC;IAED;;;;;OAKG;IACH,yCAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;;;OAKG;IACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,0CARW,MAAM,OACN,OAAO,GAKL,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,wBANW,OAAO,GAIL,SAAS,CAyBrB;IAED;;;OAGG;IACH,uBAFa,SAAS,CAqBrB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,oCARW,MAAM,OACN,OAAO,GAKL,SAAS,CAwOrB;IAED;;;;;;;;;;;;;OAaG;IACH,qCAHW,MAAM,GACJ,SAAS,CAqCrB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCAHW,MAAM,GACJ,SAAS,CAmCrB;IA2BD;;;;OAIG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAMlB;IAED,eAEC;IAED,mBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;;CAN1D;0BAh1ByB,oCAAoC"}

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

@@ -175,6 +175,13 @@ export class GPUTypedTableDescriptor {
      */
     #chunks_iterate = new Map();
 
+    /**
+     * Cache of {@link wgsl_gen_read_field_code} results, keyed by field name.
+     *
+     * @type {Map<string, CodeChunk>}
+     */
+    #chunks_read_field = new Map();
+
     /**
      *
      * @returns {CodeChunk}
@@ -238,6 +245,22 @@ export class GPUTypedTableDescriptor {
         return chunk;
     }
 
+    /**
+     * Cached {@link wgsl_gen_read_field_code} chunk for one field of this
+     * table's record type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    chunk_read_field(field_name) {
+        let chunk = this.#chunks_read_field.get(field_name);
+        if (chunk === undefined) {
+            chunk = this.wgsl_gen_read_field_code(field_name);
+            this.#chunks_read_field.set(field_name, chunk);
+        }
+        return chunk;
+    }
+
     /**
      *
      * @returns {string}
@@ -292,6 +315,16 @@ export class GPUTypedTableDescriptor {
         return `database_write_${this.marshalling_tag}_element_${field_name}`;
     }
 
+    /**
+     * Name of the function that reads only one field of a record.
+     * Pair with {@link wgsl_gen_read_field_code} to emit the body.
+     * @param {string} field_name
+     * @returns {string}
+     */
+    marshalling_method_read_field(field_name) {
+        return `database_read_${this.marshalling_tag}_element_${field_name}`;
+    }
+
     /**
      * Name prefix for all WGSL symbols generated by {@link wgsl_gen_iterate_code}
      * for the given workgroup size. Helpers append `_setup`, `_is_occupied`,
@@ -670,6 +703,57 @@ fn ${prefix}_read(
         );
     }
 
+    /**
+     * Generate a reader that touches only a single struct field of a record.
+     *
+     * The whole-record reader deserializes every field — for a wide record that
+     * is a lot of loads to reach one word. A pass that runs per particle rather
+     * than per record (the simulation-order histogram reads nothing but the
+     * emitter's program id) pays that on every invocation.
+     *
+     * Only struct-typed records support this — other shapes have no field
+     * concept. The field's WGSL type is mirrored in the return type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    wgsl_gen_read_field_code(field_name) {
+        assert.isString(field_name, 'field_name');
+
+        /**
+         *
+         * @type {WebGPUStruct}
+         */
+        const type = this.type;
+
+        assert.equal(type.isStruct, true, 'wgsl_gen_read_field_code requires a struct-typed record');
+
+        const field = type.get(field_name);
+        const field_type = field.type;
+        const field_offset_words = field.offset / GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+        assert.isNonNegativeInteger(field_offset_words, 'field_offset_words');
+
+        const lines = new LineBuilder();
+
+        const fn_name = this.marshalling_method_read_field(field_name);
+
+        lines.add(`fn ${fn_name}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>>, index: u32) -> ${field_type.wgsl_ref} {`);
+        lines.indent();
+
+        this.#wgsl_gen_element_offset(lines);
+
+        lines.add(`return `);
+        table_wgsl_gen_read_code(lines, field_offset_words, "database", field_type);
+        lines.extend(';');
+
+        lines.dedent();
+        lines.add(`}`);
+
+        const dependencies = field_type.requires_declaration ? [field_type.declaration_chunk] : [];
+
+        return CodeChunk.from(lines.build(), dependencies);
+    }
+
     /**
      * Generate a writer that touches only a single struct field of a record.
      *

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

@@ -0,0 +1,24 @@
+/**
+ * A `GPUDatabase` as the flat `array<u32>` its shaders bind — laid out from the CPU side, for
+ * running those shaders under the WGSL emulator.
+ *
+ * On a device the rows reach the buffer through the database's upload dispatch, and the software
+ * device records dispatches without running them, so a spec that wants a shader to read real rows
+ * has to produce the bytes itself. This is the one place that knows how: the page address table at
+ * the front, then each resident page at the address the database's own allocator gave it, holding
+ * its `[live_count][occupancy bitmap]` header and its records — every number taken from the
+ * descriptors and the page metadata the database keeps, which is where the generated WGSL readers
+ * and the page iterator get theirs too.
+ *
+ * Flushes the database first, on a command context of the caller's graphics, because a page gets
+ * its address from the flush: before it, every page is CPU-only and has no address to lay out at.
+ * Nothing is read back — the words are assembled from the CPU page shadows the flush leaves in
+ * place.
+ *
+ * @param {import("./GPUDatabase.js").GPUDatabase} database
+ * @param {import("../../GraphicsContext.js").GraphicsContext} graphics the context the database was
+ *        created against; the flush records onto a command context of it
+ * @returns {Uint32Array} the buffer contents, `database.buffer.size` bytes
+ */
+export function gpu_database_words(database: import("./GPUDatabase.js").GPUDatabase, graphics: import("../../GraphicsContext.js").GraphicsContext): Uint32Array;
+//# sourceMappingURL=gpu_database_words.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_database_words.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_database_words.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6CALW,OAAO,kBAAkB,EAAE,WAAW,YACtC,OAAO,0BAA0B,EAAE,eAAe,GAEhD,WAAW,CAmEvB"}

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

@@ -0,0 +1,92 @@
+import { assert } from "../../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
+
+/**
+ * A `GPUDatabase` as the flat `array<u32>` its shaders bind — laid out from the CPU side, for
+ * running those shaders under the WGSL emulator.
+ *
+ * On a device the rows reach the buffer through the database's upload dispatch, and the software
+ * device records dispatches without running them, so a spec that wants a shader to read real rows
+ * has to produce the bytes itself. This is the one place that knows how: the page address table at
+ * the front, then each resident page at the address the database's own allocator gave it, holding
+ * its `[live_count][occupancy bitmap]` header and its records — every number taken from the
+ * descriptors and the page metadata the database keeps, which is where the generated WGSL readers
+ * and the page iterator get theirs too.
+ *
+ * Flushes the database first, on a command context of the caller's graphics, because a page gets
+ * its address from the flush: before it, every page is CPU-only and has no address to lay out at.
+ * Nothing is read back — the words are assembled from the CPU page shadows the flush leaves in
+ * place.
+ *
+ * @param {import("./GPUDatabase.js").GPUDatabase} database
+ * @param {import("../../GraphicsContext.js").GraphicsContext} graphics the context the database was
+ *        created against; the flush records onto a command context of it
+ * @returns {Uint32Array} the buffer contents, `database.buffer.size` bytes
+ */
+export function gpu_database_words(database, graphics) {
+    assert.defined(database, 'database');
+    assert.defined(graphics, 'graphics');
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'gpu_database_words/flush');
+    database.update(cmd);
+    cmd.finish();
+
+    const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+    const words = new Uint32Array(database.buffer.size / word_size);
+
+    // Unallocated page slots read as ~0 on the GPU (the allocation table is seeded with it), and
+    // the readers and iterators test for exactly that value.
+    const page_limit_words = database.data_start_offset;
+
+    for (let i = 0; i < page_limit_words; i++) {
+        words[i] = 0xffffffff;
+    }
+
+    const data_start = database.data_start_offset;
+
+    for (const table of database.tables) {
+        const descriptor = table.descriptor;
+        const record_words = descriptor.packed_element_size_bytes / word_size;
+        const elements_per_page = descriptor.elements_per_page;
+        const header_words = descriptor.page_header_words;
+
+        for (const [page_index, page] of table.pages) {
+            if (!page.is_gpu_resident) {
+                continue;
+            }
+
+            const address = page.slot_offset + data_start;
+
+            words[descriptor.page_lookup_address + page_index] = address;
+
+            // Header: live count, then the occupancy bitmap — the CPU `occupancy` BitSet is the
+            // truth for both, exactly as the database's own header upload treats it.
+            const first_element = page_index * elements_per_page;
+            let live = 0;
+
+            for (let e = 0; e < elements_per_page; e++) {
+                if (!table.occupancy.get(first_element + e)) {
+                    continue;
+                }
+
+                live++;
+                words[address + 1 + (e >> 5)] |= (1 << (e & 31)) >>> 0;
+            }
+
+            words[address] = live;
+
+            assert.defined(page.cpu_data_buffer, `page ${page_index} of '${descriptor.name}' has no CPU shadow — was the database unmapped?`);
+
+            const page_words = new Uint32Array(
+                page.cpu_data_buffer,
+                page.cpu_data_address,
+                elements_per_page * record_words,
+            );
+
+            words.set(page_words, address + header_words);
+        }
+    }
+
+    return words;
+}