@woosh/meep-engine 3.15.0 → 3.16.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":"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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

@@ -66,6 +66,7 @@ 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 { SceneManager } from "./scene/SceneManager.js";
 import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
 import { ShadeTransparencyMode } from "./ShadeTransparencyMode.js";
@@ -188,6 +189,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 +996,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 +1394,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 +1859,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 +1924,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 +2170,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 +2321,24 @@ 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);
+
+            particles.simulate({
+                graph,
+                camera: gr_buffer_camera_current,
+                scene_database: gr_scene_database_for_velocity,
+                dt: time_delta_seconds,
+            });
+
+            particle_side_channels.push(particles);
+        }
+
         if (this.#feature_enabled_transparencies) {
             // do transparent alpha pass
             graph.push_scope("transparencies");
@@ -2271,6 +2370,7 @@ export class Renderer {
 
                 indirect_lighting_mode: this.indirect_lighting_mode,
                 avboit: this.avboit,
+                side_channels: particle_side_channels,
             });
 
             graph.pop_scope();
@@ -2491,13 +2591,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 +2641,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_emulator_image.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Build the `array<u32>` image of a {@link GPUDatabase} — the exact bytes the generated marshalling
+ * functions ({@link GPUTypedTableDescriptor#chunk_read} and friends) index: the page address table,
+ * then pages at the addresses it names, each page's records past its
+ * `[u32 live_count][u32 occupancy_bitmap...]` header.
+ *
+ * This exists for the WGSL emulator. The production route to those bytes is a compute dispatch
+ * ({@link ./gpu_table_element_upload_shader.js}) against a live device, and the software device
+ * records dispatches without running them — so a spec that wants to run a database-reading shader
+ * on the CPU has no way to obtain a filled buffer. Everything here is derived from the descriptor's
+ * own published geometry (`page_lookup_address`, `elements_per_page`, `page_header_words`,
+ * `packed_element_size_bytes`), which is the same geometry the upload shader receives as its
+ * settings, so the two cannot drift apart silently.
+ *
+ * Pages are allocated in ascending (table index, page index) order — the addresses therefore differ
+ * from what a live database's slot allocator would hand out for the same writes. Nothing reads a
+ * page address except through the table, so the layout is equivalent, not identical.
+ *
+ * @param {GPUDatabaseDefinition} definition
+ * @param {Object<string, Iterable<[number, *]>>} contents records per table name, as
+ *        `[element_index, value]` pairs (a `Map`, or an array of pairs)
+ * @returns {Uint32Array}
+ */
+export function gpu_database_emulator_image(definition: GPUDatabaseDefinition, contents: {
+    [x: string]: Iterable<[number, any]>;
+}): Uint32Array;
+//# sourceMappingURL=gpu_database_emulator_image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_database_emulator_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_database_emulator_image.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;QAJkB,MAAM,GAAE,SAAS,CAAC,MAAM,MAAI,CAAC;IAElC,WAAW,CAwFvB"}

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