@woosh/meep-engine 3.14.5 → 3.15.0

package/src/shade/playground/particle_system/README.md

@@ -17,6 +17,10 @@ It has to be `http://localhost` rather than `file://`: WebGPU needs a secure con
 imports from `file://` are blocked by CORS anyway. The page imports nothing but meep's own relative
 ESM, so any static server rooted at the repo also serves it.
 
+**It needs `subgroups`**, and refuses to start without it. The simulate input list is bucketed by VM
+program so no wave spans two programs, and the bucket offsets come from `graph_prefix_scan_csdldf`,
+which is built on subgroup ops.
+
 **It needs immediate data**, and refuses to start without it. Emit, simulate and build-indirect each
 carry their per-dispatch state (`u_dt`, `u_time`, `u_frame`, and for emit the request count and the
 pool capacity) as an immediate block rather than as a transient uniform buffer, so an adapter whose
@@ -35,6 +39,12 @@ Four emitters sharing one 32k pool, chosen so each renderer path is visible at o
 | sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
 | dust | alpha | billboard, soft-depth | a wide slow drift, so the ground plane and the low wall both get a soft intersection |
 
+Four distinct compiled programs, so this is also where the simulation-order bucketing has something
+to do: without it a simulate wave holds fire, smoke, spark and dust particles side by side, each
+wanting different opcodes out of the interpreter's `switch` and different registers out of its
+dynamically-indexed file. Nothing on screen changes when it is on — it is a coherence change, not a
+visual one — which is why it is pinned by specs rather than by looking.
+
 Ground plane and three boxes are drawn first into a reverse-Z `depth32float` buffer. The billboard
 pass loads that colour target and depth-tests against the same buffer read-only, so particles are
 **occluded** by the boxes and the soft-depth emitters sample the depth they were occluded by.
@@ -75,9 +85,10 @@ npx vitest run src/shade/playground/particle_system/particle_scene.spec.js
 
 That mock runs no shaders, so the spec asserts nothing about what a pass computed. What it does
 assert is that the frame is legal and wired the way the design requires — pass order and
-attachments, the alive lists ping-ponging so no frame reads the list it appends to, the immediate
-blocks written before every dispatch that declares them, and simulate and the draw both taking their
-counts from the indirect buffers. Any WebGPU validation failure anywhere in the frame arrives as an
+attachments, no frame reading the list it appends to, the immediate blocks written before every
+dispatch that declares them, simulate and the draw both taking their counts from the indirect
+buffers, and the two orderings staying in separate buffers: simulate reads the program-coherent
+list, the billboard draw reads the alive list. Any WebGPU validation failure anywhere in the frame arrives as an
 uncaptured error, which every test fails on.
 
 The picture is the browser's job; the spec cannot see it.

package/src/shade/playground/particle_system/index.html

@@ -105,6 +105,7 @@
     <div><span class="key">alive</span><span id="stat-alive">—</span></div>
     <div><span class="key">free</span><span id="stat-dead">—</span></div>
     <div><span class="key">draw instances</span><span id="stat-draw">—</span></div>
+    <div><span class="key">sim lanes</span><span id="stat-sim-lanes">—</span></div>
     <div><span class="key">sim workgroups</span><span id="stat-dispatch">—</span></div>
 </div>
 

package/src/shade/playground/particle_system/main.js

@@ -39,7 +39,17 @@ async function main() {
         return show_message("No WebGPU adapter — this browser exposes the API but has no usable GPU.");
     }
 
-    const device = await adapter.requestDevice();
+    // The coherence pass's bucket offsets come from the CSDLDF prefix scan, which is built on
+    // subgroup ops — refusing by name beats the pipeline-creation error a device without it raises.
+    if (!adapter.features.has("subgroups")) {
+        return show_message(
+            "This browser's WebGPU adapter does not offer the 'subgroups' feature.\n"
+            + "The simulate list's program-coherent bucketing scans its bin counts with the CSDLDF\n"
+            + "prefix scan, which is built on subgroup ops."
+        );
+    }
+
+    const device = await adapter.requestDevice({ requiredFeatures: ["subgroups"] });
     device.addEventListener?.("uncapturederror", (e) => console.error("WebGPU error:", e.error.message));
 
     // Every compute pass here carries its per-dispatch state as immediate data, an optional
@@ -148,7 +158,7 @@ async function main() {
 }
 
 /** Push one stats snapshot into the overlay. Absent elements are simply skipped. */
-function write_hud({ fps, alive, dead, dispatch, draw }) {
+function write_hud({ fps, alive, dead, dispatch, draw, sim_padded }) {
     const put = (id, value) => {
         const node = document.getElementById(id);
         if (node !== null) {
@@ -160,6 +170,9 @@ function write_hud({ fps, alive, dead, dispatch, draw }) {
     put("stat-alive", alive.toLocaleString());
     put("stat-dead", dead.toLocaleString());
     put("stat-draw", draw[1].toLocaleString());
+    // Padding rounds each program's run up to a whole workgroup, so this is >= alive; the gap is
+    // what wave-coherence costs in lanes.
+    put("stat-sim-lanes", sim_padded.toLocaleString());
     put("stat-dispatch", dispatch[0].toLocaleString());
 }
 

package/src/shade/playground/particle_system/particle_scene.d.ts

@@ -2,7 +2,10 @@
  * @typedef {object} ParticleSceneStats
  * @property {number} alive particles alive at the end of the captured frame
  * @property {number} dead free slots left in the pool
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
+ *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
+ * @property {number} sim_padded length of the program-coherent list the coherence pass built this
+ *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
  * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
  */
@@ -37,9 +40,15 @@ export type ParticleSceneStats = {
      */
     dead: number;
     /**
-     * the snapshot next frame's simulate reads as its input length
+     * the snapshot next frame's simulate reads as its input length — the
+     * PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
      */
     alive_in: number;
+    /**
+     * length of the program-coherent list the coherence pass built this
+     * frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
+     */
+    sim_padded: number;
     /**
      * simulate's indirect dispatch args, `[x, y, z]` workgroups
      */

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAyEA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CA8OlB;AA3QD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CAiUlB;AAjWD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}

package/src/shade/playground/particle_system/particle_scene.js

@@ -4,7 +4,23 @@ import { m4_look_at } from "../../../core/geom/3d/mat4/m4_look_at.js";
 import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "../../renderer/particles/ParticleConstants.js";
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+} from "../../renderer/particles/ParticleConstants.js";
+import {
+    PREFIX_SCAN_CSDLDF_HEADER_WORDS,
+    PREFIX_SCAN_CSDLDF_PARTITION_SIZE,
+    shader_prefix_scan_csdldf,
+} from "../../renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { build_indirect_compute_dispatch_command } from "../../renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    shader_particle_bucket_fill,
+    shader_particle_bucket_histogram,
+    shader_particle_bucket_pad,
+    shader_particle_bucket_reset,
+    shader_particle_bucket_scatter,
+} from "../../renderer/particles/coherence/shader_particle_bucket.js";
 import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
 import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
@@ -23,10 +39,7 @@ import {
     shader_particle_build_indirect,
     shader_particle_reset_counters,
 } from "../../renderer/particles/shaders/shader_particle_finalize.js";
-import {
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    shader_particle_simulate,
-} from "../../renderer/particles/shaders/shader_particle_simulate.js";
+import { shader_particle_simulate } from "../../renderer/particles/shaders/shader_particle_simulate.js";
 
 /**
  * The scene the particle playground draws, with every reference to the page removed: it takes a
@@ -50,6 +63,12 @@ import {
  * billboard draw via `drawIndirect`, both from args the build-indirect pass writes on the GPU. No
  * CPU readback participates in sizing anything — a stale CPU count would orphan alive-list entries
  * when the population grows and double-free slots when it shrinks.
+ *
+ * The four emitters run four distinct compiled programs, so this is also where the simulation-order
+ * bucketing has something to do: without it a simulate wave holds fire, smoke, spark and dust
+ * particles side by side, each wanting different opcodes out of the interpreter's switch. The
+ * bucketing passes are encoded directly here rather than through `graph_particles`, which is the
+ * frame-graph wiring of the same sequence.
  */
 
 /** Maximum simultaneous particles across every emitter — they share one pool. */
@@ -75,7 +94,10 @@ const STATS_OFFSET_DRAW_ARGS = 48;
  * @typedef {object} ParticleSceneStats
  * @property {number} alive particles alive at the end of the captured frame
  * @property {number} dead free slots left in the pool
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
+ *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
+ * @property {number} sim_padded length of the program-coherent list the coherence pass built this
+ *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
  * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
  */
@@ -148,6 +170,37 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
     const dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: args_usage });
     const draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: args_usage });
 
+    // --- simulation-order (coherence) buffers -------------------------------------------------
+    //
+    // A separate set from the render-order sort's, on purpose: one list is grouped by VM program and
+    // camera-independent, the other is back-to-front by view depth. Sharing a buffer between them
+    // would couple a camera-driven ordering to a program-driven one.
+    const sizes = system.bufferSizes();
+    const buckets = system.bucketCount();
+    const sim_list = device.createBuffer({ label: "particles/sim_list", size: sizes.sim_list, usage: storage });
+    const sim_keys = device.createBuffer({ label: "particles/sim_keys", size: sizes.sim_keys, usage: storage });
+    const sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: sizes.sim_histogram, usage: storage });
+    const sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: sizes.sim_bucket_counts, usage: storage });
+    const sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: sizes.sim_cursor, usage: storage });
+    const sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: sizes.sim_dispatch_args, usage: args_usage });
+
+    // Scratch the reused CSDLDF scan needs: the indirect command it is dispatched with, and its
+    // decoupled-lookback spine. One partition covers every plausible bucket count.
+    const scan_command = device.createBuffer({
+        label: "particles/sim_scan_command",
+        size: 3 * 4,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    });
+    // Cleared at the top of every frame, not just on creation: the spine carries per-partition
+    // flags, and a stale FLAG_INCLUSIVE left over from last frame is read as this frame's answer.
+    // The frame-graph wiring gets this for free from `BufferResourceDescriptor.empty`; encoding by
+    // hand has to ask. Rounded to a 256-byte allocation rather than the 8 bytes one partition needs.
+    const scan_spine = device.createBuffer({
+        label: "particles/sim_scan_spine",
+        size: Math.max(256, Math.ceil(buckets / PREFIX_SCAN_CSDLDF_PARTITION_SIZE) * 2 * 4),
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
     const initial = system.initialFreeList();
     device.queue.writeBuffer(dead, 0, initial.dead);
     device.queue.writeBuffer(counters, 0, initial.counters);
@@ -205,7 +258,12 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
         capacity,
 
         /** Buffers a harness may inspect. Not for the frame loop, which never reads them back. */
-        buffers: { pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants, dispatch_args, draw_args },
+        buffers: {
+            pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants,
+            dispatch_args, draw_args,
+            sim_list, sim_keys, sim_histogram, sim_bucket_counts, sim_cursor, sim_dispatch_args,
+            sim_scan_command: scan_command, sim_scan_spine: scan_spine,
+        },
 
         /**
          * Encode one whole frame: geometry, then emit + simulate + build-indirect, then the
@@ -259,13 +317,59 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
                 encoder: cmd,
                 bindings: {
                     emitters, program, vm_constants: constants, pool,
-                    alive_in: alive_read, alive_out: alive_write, dead, counters,
+                    sim_list, alive_out: alive_write, dead, counters,
                     settings: { u_dt: dt, u_time: time, u_frame: system.frame },
                 },
                 command: dispatch_args,
             });
 
-            // Snapshot the final alive count (next frame's simulate input) + write this frame's draw args.
+            // --- coherence: regroup the finished alive list by VM program for NEXT frame's simulate ---
+            //
+            // Reads the list emit and simulate have both finished appending to, and rewrites
+            // `sim_list` — the buffer simulate read a few lines above. Consecutive dispatches are
+            // ordered, so the read is complete before the write lands.
+            shader_particle_bucket_reset.dispatchThreads({
+                encoder: cmd,
+                bindings: { counters, histogram: sim_histogram, cursor: sim_cursor, sim_dispatch_args, u_bucket_count: buckets },
+                thread_count_x: bucket_reset_thread_count(buckets),
+            });
+
+            shader_particle_bucket_histogram.dispatchIndirect({
+                encoder: cmd,
+                bindings: { emitters, pool, alive: alive_write, keys: sim_keys, histogram: sim_histogram, counters },
+                command: sim_dispatch_args,
+            });
+
+            shader_particle_bucket_pad.dispatchThreads({
+                encoder: cmd,
+                bindings: { histogram: sim_histogram, bucket_counts: sim_bucket_counts, u_bucket_count: buckets },
+                thread_count_x: buckets,
+            });
+
+            // The same scan the radix sort runs its spine through, reused unmodified.
+            cmd.clearBuffer(scan_spine, 0, scan_spine.size);
+            build_indirect_compute_dispatch_command(
+                PREFIX_SCAN_CSDLDF_PARTITION_SIZE, cmd, sim_histogram, 0, scan_command, 0,
+            );
+            shader_prefix_scan_csdldf.dispatchIndirect({
+                encoder: cmd,
+                command: scan_command,
+                bindings: { scan_in: sim_histogram, spine: scan_spine },
+            });
+
+            shader_particle_bucket_scatter.dispatchIndirect({
+                encoder: cmd,
+                bindings: { keys: sim_keys, alive: alive_write, scanned: sim_histogram, cursor: sim_cursor, sim_list, counters },
+                command: sim_dispatch_args,
+            });
+
+            shader_particle_bucket_fill.dispatchThreads({
+                encoder: cmd,
+                bindings: { bucket_counts: sim_bucket_counts, scanned: sim_histogram, sim_list, counters, u_bucket_count: buckets },
+                thread_count_x: buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE,
+            });
+
+            // Snapshot the padded list length (next frame's simulate input) + write this frame's draw args.
             shader_particle_build_indirect.dispatch({
                 encoder: cmd,
                 bindings: { counters, dispatch_args, draw_args, u_workgroup_size: PARTICLE_SIMULATE_WORKGROUP_SIZE },
@@ -320,6 +424,7 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
                 alive: words[0],
                 dead: words[1],
                 alive_in: words[4],
+                sim_padded: words[5],
                 dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
                 draw: [words[draw_base], words[draw_base + 1]],
             };
@@ -529,6 +634,18 @@ function translation(x, y, z) {
     return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
 }
 
+/**
+ * Threads the bucket reset pass needs: enough to cover the scan's header plus its bins, rounded up
+ * to the whole `vec4` the last bin lands in (the scan reads whole `vec4`s, so the tail has to be
+ * cleared too or garbage joins the sums).
+ *
+ * @param {number} bucket_count
+ * @returns {number}
+ */
+function bucket_reset_thread_count(bucket_count) {
+    return PREFIX_SCAN_CSDLDF_HEADER_WORDS + ((bucket_count + 3) & ~3);
+}
+
 function data_buffer(device, label, data, usage) {
     const buffer = device.createBuffer({ label, size: Math.max(data.byteLength, 4), usage });
     device.queue.writeBuffer(buffer, 0, data);

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

@@ -118,6 +118,7 @@ export class GraphicsContext {
     readonly isGraphicsContext: boolean;
     #private;
 }
+export type BinaryBuffer = import("../../core/binary/BinaryBuffer.js").BinaryBuffer;
 import { GPUGeometryManager } from "./geometry/GPUGeometryManager.js";
 import { GPUMaterialManager } from "./material/GPUMaterialManager.js";
 import { GPUSamplerManager } from "./GPUSamplerManager.js";

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

@@ -1 +1 @@
-{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AAwBA;IAoJI,yBA8BC;IAjLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAkCD;;;;;;;;OAQG;IACH,gGALW,oBAAoB,EAAE,cACtB;QAAC,MAAM,eAAe;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,mDAFa,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAcC;IAED,4BAEC;IAED,eAmBC;IAED,gBAcC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;mCA9UkC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAXzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAchD,6BAA6B;sCACtB,4CAA4C;iCAbjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAErC,uCAAuC;oCAO7C,kCAAkC;iCARtB,8BAA8B"}
+{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AA4BA;IAoJI,yBA8BC;IAjLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAkCD;;;;;;;;OAQG;IACH,gGALW,oBAAoB,EAAE,cACtB;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,mDAFa,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAcC;IAED,4BAEC;IAED,eAmBC;IAED,gBAcC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BAtUY,OAAO,mCAAmC,EAAE,YAAY;mCAZlC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAXzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAchD,6BAA6B;sCACtB,4CAA4C;iCAbjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAErC,uCAAuC;oCAO7C,kCAAkC;iCARtB,8BAA8B"}

package/src/shade/renderer/GraphicsContext.js

@@ -20,6 +20,10 @@ import { GPUTextureAllocator } from "./texture/GPUTextureAllocator.js";
 import { TextureManager } from "./texture/TextureManager.js";
 import { VirtualTextureManager } from "./texture/virtual/VirtualTextureManager.js";
 
+
+/**
+ * @typedef {import("../../core/binary/BinaryBuffer.js").BinaryBuffer} BinaryBuffer
+ */
 const DEBUG_LOGGING = false;
 
 export class GraphicsContext {

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

@@ -11,7 +11,7 @@ export class Renderer {
      *
      * @returns {HTMLCanvasElement|OffscreenCanvas|undefined}
      */
-    get canvas(): OffscreenCanvas | HTMLCanvasElement;
+    get canvas(): HTMLCanvasElement | OffscreenCanvas;
     /**
      * @type {GPUDevice}
      */
@@ -29,6 +29,20 @@ 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;
     feature_ssr_enabled: boolean;
     feature_ssao_enabled: boolean;
     /**
@@ -388,6 +402,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";

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";
@@ -65,6 +68,8 @@ import { graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scen
 import { ReSTIRDI } from "./restir/di/ReSTIRDI.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 +172,22 @@ 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();
+
     feature_ssr_enabled = false;
     feature_ssao_enabled = true;
     /**
@@ -2178,35 +2199,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.
@@ -2250,7 +2244,13 @@ export class Renderer {
             // 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 +2270,7 @@ export class Renderer {
                 volumetrics_metadata: volumetrics.metadata,
 
                 indirect_lighting_mode: this.indirect_lighting_mode,
+                avboit: this.avboit,
             });
 
             graph.pop_scope();

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/geometry/MeshletGeometrySerializationAdapter.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();
     klass: typeof MeshletGeometry;

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAzFM,uEAAuE;gCAE9C,sBAAsB"}
+{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAtGM,uEAAuE;gCAE9C,sBAAsB"}

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js

@@ -4,6 +4,19 @@ import {
 import { blas_from_meshlets } from "./blas_from_meshlets.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter {
 
     version = 0

package/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.d.ts

@@ -3,9 +3,27 @@
  * to fill an existing instance (e.g. a subclass of `MeshletGeometry`)
  * in place; otherwise a fresh instance is created and returned.
  *
+ * **This is synchronous, single-threaded, and it is not cheap — so at load time it belongs
+ * OFFLINE, not on the frame loop.** Measured converting one level's meshes: 3.3k triangles across
+ * 23 meshes took 53 ms, 7.5k across 30 took 74 ms, and **199k across 45 took 1,246 ms** — an
+ * unbroken second and a quarter of main thread, scaling linearly, on a level that is small.
+ * Reported from a port as GAP-008.
+ *
+ * **The offline route already exists and is the intended pipeline.**
+ * {@link MeshletGeometrySerializationAdapter} round-trips a `MeshletGeometry` to and from a
+ * `BinaryBuffer` losslessly, so an asset build can call this once, serialize the result beside the
+ * source mesh, and leave the runtime with a deserialize and an upload. Nothing about this function
+ * needs to run in a browser. If you are calling it from a level loader, that is the thing to change
+ * first — before reaching for a worker, which only moves the cost.
+ *
+ * A pooled worker-backed geometry service, with meshlet construction as one of the things it
+ * serves, is where this is going; it is not here yet, and it would not remove the reason to build
+ * offline.
+ *
  * @param {Geometry} geometry
  * @param {MeshletGeometry} [out]
  * @returns {MeshletGeometry}
+ * @see MeshletGeometrySerializationAdapter for the offline format
  */
 export function meshlet_geometry_build_from_geometry(geometry: Geometry, out?: MeshletGeometry): MeshletGeometry;
 import { MeshletGeometry } from "./MeshletGeometry.js";

package/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meshlet_geometry_build_from_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,+EAHW,eAAe,GACb,eAAe,CAoC3B;gCA7C+B,sBAAsB"}
+{"version":3,"file":"meshlet_geometry_build_from_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+EAJW,eAAe,GACb,eAAe,CAqC3B;gCA/D+B,sBAAsB"}