@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -29,6 +29,39 @@ export class Renderer {
      * @type {ShadeIndirectLightingMode}
      */
     indirect_lighting_mode: ShadeIndirectLightingMode;
+    /**
+     * Which order-independent transparency technique draws the transparent buckets. Both modes
+     * are wired at the single transparency call site and take the same inputs, so this is safe to
+     * flip at runtime for an A/B. See {@link ShadeTransparencyMode} for what each one costs and
+     * needs from the device. AVBOIT is the default since 2026-09-03: depth-complexity invariant
+     * where MBOIT leaks stacked surfaces, and no 32-bit float blending.
+     * @type {ShadeTransparencyMode}
+     */
+    transparency_mode: ShadeTransparencyMode;
+    /**
+     * Switches of the AVBOIT mode, read every frame while {@link transparency_mode} selects it.
+     * @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;
     /**
@@ -319,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
@@ -388,6 +429,8 @@ export class Renderer {
 }
 import { SceneManager } from "./scene/SceneManager.js";
 import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
+import { ShadeTransparencyMode } from "./ShadeTransparencyMode.js";
+import { AVBOITSettings } from "./rasterize/native/avboit/AVBOITSettings.js";
 import { MotionBlur } from "./postprocess/motion_blur/MotionBlur.js";
 import { DepthOfField } from "./postprocess/dof/raymarch/DepthOfField.js";
 import { DepthOfFieldU } from "./postprocess/dof/gather/DepthOfFieldU.js";
@@ -400,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":"AA4FA;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,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,CAu2BnB;;CACJ;6BAr5E4B,yBAAyB;0CACZ,gCAAgC;2BApB/C,yCAAyC;6BAFvC,4CAA4C;8BAD3C,2CAA2C;4BAiC7C,uBAAuB;gCAtCnB,sBAAsB;mBArCnC,oCAAoC;oBACnC,4BAA4B;kCAuEd,gCAAgC;2BApDvC,2BAA2B;iCAkDrB,0CAA0C;4CApC/B,+DAA+D;yBA6BlF,yBAAyB;kCAMhB,wBAAwB;oBAvBtC,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

@@ -54,6 +54,9 @@ import { shader_debug_velocity } from "./postprocess/velocity/shader_debug_veloc
 import {
     graph_rasterize_meshes_transparent_oit
 } from "./rasterize/native/oit/graph_rasterize_meshes_transparent_oit.js";
+import {
+    graph_rasterize_meshes_transparent_avboit
+} from "./rasterize/native/avboit/graph_rasterize_meshes_transparent_avboit.js";
 import {
     viz_rasterization_alpha_tested_pass_descriptor
 } from "./rasterize/native/viz/viz_rasterization_alpha_tested_pass_descriptor.js";
@@ -63,8 +66,11 @@ 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";
+import { AVBOITSettings } from "./rasterize/native/avboit/AVBOITSettings.js";
 import { graph_image_pass } from "./shader/graph/graph_image_pass.js";
 import { graph_import_buffer } from "./shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
@@ -167,6 +173,43 @@ export class Renderer {
      */
     indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
 
+    /**
+     * Which order-independent transparency technique draws the transparent buckets. Both modes
+     * are wired at the single transparency call site and take the same inputs, so this is safe to
+     * flip at runtime for an A/B. See {@link ShadeTransparencyMode} for what each one costs and
+     * needs from the device. AVBOIT is the default since 2026-09-03: depth-complexity invariant
+     * where MBOIT leaks stacked surfaces, and no 32-bit float blending.
+     * @type {ShadeTransparencyMode}
+     */
+    transparency_mode = ShadeTransparencyMode.AVBOIT;
+
+    /**
+     * Switches of the AVBOIT mode, read every frame while {@link transparency_mode} selects it.
+     * @type {AVBOITSettings}
+     */
+    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;
     /**
@@ -953,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}
@@ -1320,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();
     }
 
 
@@ -1780,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
@@ -1833,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");
@@ -2078,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
@@ -2178,35 +2280,8 @@ export class Renderer {
 
             }
 
-            // current_color_out = indirect_diffuse
-            // current_color_out = indirect_specular
-
         }
 
-        // current_color_out = graph_decode_rgbe9995_to_rgb16float({
-        //     graph,
-        //     input:indirect_diffuse_near_field,
-        //     resolution: view_ctx.resolution,
-        // });
-        //
-        // const [norm] = graph_image_pass({
-        //     shader: shader_decode_octahedral_normal,
-        //     inputs:{
-        //         tInput: bent_normals,
-        //     },
-        //     graph,
-        //     output_resolution: view_ctx.resolution,
-        // });
-        //
-        // [current_color_out] = graph_image_pass({
-        //     graph,
-        //     shader: shader_draw_normals,
-        //     inputs:{
-        //         tInput: norm,
-        //     },
-        //     output_resolution: view_ctx.resolution,
-        // });
-
         // Composite volumetric fog over the finalized opaque + background + indirect colour.
         // A dedicated pass (not inline in the shading shaders) because indirect lighting is added
         // in a separate additively-blended pass, so the full surface radiance only exists here.
@@ -2246,11 +2321,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);
+
+            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");
 
-            current_color_out = graph_rasterize_meshes_transparent_oit({
+            // Mutually exclusive by construction: one orchestrator runs at this one call site, and both
+            // take the same argument object, so the mode is a pure selector.
+            const graph_rasterize_meshes_transparent = this.transparency_mode === ShadeTransparencyMode.AVBOIT
+                ? graph_rasterize_meshes_transparent_avboit
+                : graph_rasterize_meshes_transparent_oit;
+
+            current_color_out = graph_rasterize_meshes_transparent({
                 graph,
                 buckets: gr_render_buckets,
                 view_ctx,
@@ -2270,6 +2369,8 @@ export class Renderer {
                 volumetrics_metadata: volumetrics.metadata,
 
                 indirect_lighting_mode: this.indirect_lighting_mode,
+                avboit: this.avboit,
+                side_channels: particle_side_channels,
             });
 
             graph.pop_scope();
@@ -2490,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;
 
-        command_ctx.popDebugGroup();
+        try {
+            command_ctx.encodeGraph(graph);
 
-        view_ctx.finish_frame(command_ctx);
+            command_ctx.popDebugGroup();
 
-        command_ctx.finish();
+            view_ctx.finish_frame(command_ctx);
+        } catch (e) {
+            frame_error = e;
+        }
+
+        /*
+         `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) {
             /*
@@ -2512,6 +2641,10 @@ export class Renderer {
             });
         }
 
+        if (frame_error !== null) {
+            throw frame_error;
+        }
+
         this.#end_frame();
 
         return true;

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

@@ -0,0 +1,13 @@
+/**
+ * Selects which order-independent transparency technique draws the transparent buckets.
+ *
+ * Both modes share everything up to the draw commands (material filtering, meshlet expansion, HZB
+ * culling) and both composite onto the scene colour at `FramePhase.AfterLighting`; they differ in
+ * how the per-pixel transmittance in front of a fragment is represented.
+ */
+export type ShadeTransparencyMode = number;
+export namespace ShadeTransparencyMode {
+    let MBOIT: number;
+    let AVBOIT: number;
+}
+//# sourceMappingURL=ShadeTransparencyMode.d.ts.map

package/src/shade/renderer/ShadeTransparencyMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeTransparencyMode.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/ShadeTransparencyMode.js"],"names":[],"mappings":";;;;;;;oCAOU,MAAM"}

package/src/shade/renderer/ShadeTransparencyMode.js

@@ -0,0 +1,30 @@
+/**
+ * Selects which order-independent transparency technique draws the transparent buckets.
+ *
+ * Both modes share everything up to the draw commands (material filtering, meshlet expansion, HZB
+ * culling) and both composite onto the scene colour at `FramePhase.AfterLighting`; they differ in
+ * how the per-pixel transmittance in front of a fragment is represented.
+ *
+ * @enum {number}
+ */
+export const ShadeTransparencyMode = {
+    /**
+     * Moment-based OIT (Peters et al. 2017): four power moments of the transmittance function per
+     * pixel, additively blended at full resolution into `r32float` + `rgba32float` targets, which
+     * is what puts `float32-blendable` on the device floor. Smooth, cheap, and not depth-complexity
+     * invariant — stacked opaque-ish layers leak. The default until 2026-09-03.
+     *
+     * See `rasterize/native/oit/`.
+     */
+    MBOIT: 0,
+    /**
+     * Adaptive voxel-based OIT (Drobot, SIGGRAPH 2025): extinction splatted into a 1/8-resolution
+     * voxel volume whose depth axis is adaptively packed onto 128 physical slices, integrated into a
+     * 3D transmittance lookup. Depth-complexity and shift invariant, filters the background per
+     * channel for transmissive materials (opt-in, `Renderer.avboit`), and needs no 32-bit float
+     * blending. The default.
+     *
+     * See `rasterize/native/avboit/`.
+     */
+    AVBOIT: 1,
+};

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