@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_PLAN_2026_09_03.md

@@ -0,0 +1,534 @@
+# Adaptive voxel-based order-independent transparency (AVBOIT) — implementation plan
+
+**Status:** implemented, default mode, device tier in progress — revision 5
+**Date:** 2026-09-03
+**Author:** Alex Goldring / Company Named Limited, with Claude
+**Scope:** `src/shade/renderer/rasterize/native/avboit/` (new), `src/shade/renderer/ShadeTransparencyMode.js`
+(new), `src/shade/renderer/Renderer.js` (one field, one call site),
+`src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js` (two extra return values)
+**Source:** Drobot, M. — *Adaptive Voxel-Based Order Independent Transparency*, Advances in Real-Time Rendering in
+Games, SIGGRAPH 2025 (talk deck, 60 pages, `AVBOIT_SIG2025_MDROBOT-final.pdf`)
+**Ledger:** [`AVBOIT_LEDGER.md`](./AVBOIT_LEDGER.md) — what actually landed, step by step, and what each step found
+
+> **Revision 2** (ledger entries 12 and 14) amends §3.5, §4 and §7 on the transmission tint. Revision 1
+> derived a per-channel transmittance from the base colour unconditionally, and called that the OpenPBR
+> default; it is glTF's reading, OpenPBR's transmission colour defaults to white, and the engine's other
+> paths transmit untinted. The first real renders showed a red pane under AVBOIT and clear glass under
+> MBOIT and the path tracer, which a mode switch the contract calls safe to flip must not do. The tint is
+> kept and off by default, switched at runtime through `Renderer.avboit`.
+>
+> **Revision 3** (ledger entry 15): AVBOIT is the default (§0, §3.10); the slice floor is set by
+> `AVBOIT_VIRTUAL_SLICES_MAX = 4096` (§3.2, §9); the draw discards fragments the volume calls extinct before
+> shading them (§3.8); §6's software-device tier is a recorder, not an end-to-end runner, and the plan no
+> longer expects a full-orchestrator spec from it; §7's phase-2 list is decided item by item.
+>
+> **Revision 4** (ledger entry 18) is the review against the engine. The depth curve is the engine's own log
+> slicing (§3.2) rather than a second one; the bit fold reuses the Morton decode; the integral samples through
+> the sampler the draw already binds; the per-material draw loop is one shared module for both pipelines; and
+> the chunks follow the one-function-per-file convention (§5).
+>
+> **Revision 5** (ledger entry 19) widens the pipeline past meshlets. `AVBOITSideChannel` is a contract for a
+> transparent source that is not a meshlet bucket — the GPU particles are the first — asked for its occupancy,
+> its splat and its draw at the three points where the meshlet buckets contribute theirs (§3.1). The draw grew
+> a fourth accumulator, `emission`, for additive fragments: they cover nothing, so the resolve's
+> renormalization must not scale them (§3.8, §3.9). Integrate and resolve are otherwise untouched, and MBOIT,
+> now the legacy path, gets no channel of its own.
+
+---
+
+## 0. The one thing this document is about
+
+A second transparency pipeline, selected by `Renderer.transparency_mode`, that sits next to the existing
+moment-based one and shares everything up to the draw commands. It replaces the *transmittance function*
+(four power moments per pixel) with a *voxelized extinction volume* at reduced resolution, integrated along
+view rays into a 3D transmittance lookup, with the depth axis adaptively packed so that the 128 physical slices
+land where transparent geometry actually is.
+
+Everything else — material filtering, meshlet expansion, HZB culling, indirect draw commands, forward shading,
+volumetric compositing, the final composite onto the scene colour — is the same as MBOIT, and is reused rather
+than copied where the existing code allows it.
+
+What this document is **not**: a survey of OIT techniques (the deck has one, slides 10–20). *Revision 3:*
+AVBOIT is the default, on the strength of the first real renders (ledger entries 12 and 15): it held the
+stacked-card case the way the reference did and MBOIT did not. MBOIT stays selectable.
+
+---
+
+## 1. What is there now
+
+`src/shade/renderer/rasterize/native/oit/` is MBOIT, wired at a single call site
+([`Renderer.js:2222-2249`](../../../Renderer.js)), guarded by the private `#feature_enabled_transparencies`.
+Its orchestrator [`graph_rasterize_meshes_transparent_oit.js`](../oit/graph_rasterize_meshes_transparent_oit.js)
+records, per frame:
+
+1. `filter_materials_by_bucket` twice — `(Transparent, Triangles, Front)` and `(…, Double)`;
+   `ShadeDrawSide.Back` transparent materials are dropped ([`:545-561`](../oit/graph_rasterize_meshes_transparent_oit.js)).
+2. `graph_prepare_meshlet_draw_commands_by_material` twice — copy bucket, HZB mesh filter, expand to meshlets,
+   HZB meshlet filter, count/scan/sort by material, build one indirect draw command per material.
+3. `MBOIT/generate moments` twice (front clears, double loads) — additive MRT into `r32float` + `rgba32float`,
+   which is what puts `float32-blendable` on the device floor
+   ([`Renderer.js:1160`](../../../Renderer.js), [`RENDERER_CONTRACT.md` §2](../../../../RENDERER_CONTRACT.md)).
+4. `MBOIT/resolve moments` twice — full forward shading, moments reconstruct transmittance, premultiplied
+   colour × transmittance added into an `rgba16float` accumulator.
+5. `shader_oit_blend` — one image pass onto the scene colour with `one / src-alpha` blending.
+
+Per-fragment inputs, depth conventions and the material coupling for transmission are described in the two
+shaders this plan mirrors: [`shader_oit_generate_moments.js`](../oit/shader_oit_generate_moments.js) (coverage,
+Fresnel for `transmission_factor > 0`, `OIT_COVERAGE_MAX`) and
+[`shader_oit_resolve_moments_ibl.js`](../oit/shader_oit_resolve_moments_ibl.js) (shading, volumetrics with
+`get_view_space_depth`, the additive output).
+
+Mode switches in `Renderer` follow one shape — an enum file next to `ShadeIndirectLightingMode.js`, a public
+field, a ternary at the call site — and the cleanest instance is `dof_algorithm`
+([`Renderer.js:2321-2336`](../../../Renderer.js)).
+
+---
+
+## 2. The algorithm, as the deck presents it
+
+The talk's own summary of VBOIT (slide 48) and what the adaptive extension adds (slides 93–97):
+
+**VBOIT.**
+1. Fit a log depth curve over the slices.
+2. Clear a volumetric extinction buffer at reduced resolution (1/8 of the frame in XY).
+3. Splat every transparent fragment into it — extinction `-log(1 - α)` in a normalized 8-bit fixed point, added
+   with atomics, packed several fields per `u32`. *Linear* splatting (split by slice fraction between two
+   adjacent slices) removes the aliasing that point splatting shows.
+4. Integrate extinction along each view ray into a 3D transmittance-integral texture. Stop a ray when it
+   saturates, or when the splat detected an overflow (the first overflowing slice is kept with an atomic min).
+5. Draw transparencies in any order at full resolution: look the integral up at the fragment's depth, with a
+   two-slice bias toward the camera so a surface does not occlude itself; weight the fragment by that
+   transmittance; accumulate weighted colour, weighted α (the normalization denominator) and total extinction.
+6. Resolve: `background × exp(-Σ extinction) + Σ(colour × w) / Σ(α × w) × (1 - exp(-Σ extinction))`.
+
+**Adaptive.** Before splatting, voxelize the *bounds* of transparent geometry into a 1-bit-per-slice
+occupancy at a high *virtual* slice resolution. If more slices are occupied than there are physical slices,
+halve the virtual resolution and repeat. A prefix sum over the occupied slices gives a 1D depth-warp LUT that
+maps virtual depth to a physical slice, skipping empty depth ranges; the LUT is sampled at splat and at draw.
+The result is a depth axis whose precision goes where the geometry is, at no per-sample cost.
+
+**Colour.** RGB extinction is kept in a second buffer (10|10|10 packed), and the talk's measured cost of RGB
+over monochrome is ~1.1× — practical, where MBOIT/WBOIT have no clean split.
+
+Known limits (slides 86–92): two events in the same slice degenerate to weighted blending, and the two-slice
+sample bias means events closer than that do not occlude each other. Slice separation is the whole game, which
+is what the adaptive packing buys.
+
+---
+
+## 3. Design for meep
+
+### 3.1 Frame-graph passes
+
+All recorded under `graph.push_scope("transparencies")` by the new orchestrator
+`graph_rasterize_meshes_transparent_avboit(...)`, taking the same argument object as the MBOIT one and
+returning the resource ID of the composited colour.
+
+| # | Pass | Kind | Reads | Writes |
+|---|------|------|-------|--------|
+| 1 | draw-command prep × 2 (shared) | compute | buckets, HZB, camera | meshlets, draw commands, *meshlet collection*, *iterator command* |
+| 2 | `AVBOIT/occupancy` × 2 | compute, indirect | meshlet collection, meshlet metadata, scene database, camera | `occupancy` bits |
+| 3 | `AVBOIT/build warp` | compute, 1 workgroup | occupancy, camera | `warp` LUT + header |
+| 4 | `AVBOIT/splat` × 2 | render, 1/8 res | draw commands, meshlets, warp | `extinction` (atomics), `overflow` (atomics) |
+| 5 | `AVBOIT/integrate` | compute, per voxel column | extinction, overflow, warp | `integral` 3D texture |
+| 6 | `AVBOIT/draw` × 2 | render, internal res | draw commands, meshlets, depth, warp, integral, lights, volumetrics | `accum_color`, `accum_norm`, `accum_ext` |
+| 7 | `AVBOIT/resolve` | image | scene colour, the three accumulators | composited colour (new transient) |
+
+Step 1 is `graph_prepare_meshlet_draw_commands_by_material`, extended to also return the HZB-filtered meshlet
+collection (the one with a `count` header) and the indirect dispatch command it already builds over it. The
+sorted meshlet buffer the draw uses is a bare `array<MeshletDefinition>` with no count
+([`shader_sort_meshlets_by_material.js:20`](../../bucket/shader_sort_meshlets_by_material.js)), so the
+occupancy pass cannot iterate it on its own; the collection before sorting can. The two extra return values are
+additive and MBOIT ignores them.
+
+The front and double-sided variants of steps 4 and 6 exist for the same reason as in MBOIT: different
+`cullMode`, so a different pipeline, threaded through `rp_rewrite_for_primitive_state`.
+
+*Revision 5:* steps 2, 4 and 6 also take contributions from **side channels** — transparent sources that are
+not meshlet buckets, the GPU particles being the first. `graph_rasterize_meshes_transparent_avboit` takes
+`side_channels`, an array of `AVBOITSideChannel`, and asks each for its occupancy after the meshlet buckets'
+(step 2), its splat after theirs (step 4) and its draw after theirs (step 6), threading the handles the way
+every pass here does. Steps 5 and 7 are unchanged and cannot tell the two apart. Step 6 writes a fourth
+accumulator, `accum_emission` (§3.9). The orchestrator now returns early only when there are neither
+transparent materials nor channels.
+
+### 3.2 Depth curve and virtual slices
+
+Let `z` be the fragment's view-space depth (`get_view_space_depth`, positive, world units). *Revision 4:* the
+curve is the engine's log depth slicing — `cluster_depth_to_z_slice`, the same function the light clusters
+and the froxels use — with parameters from `build_light_cluster_parameters` built once per frame by
+`avboit_build_depth_curve`:
+
+```
+slice(z) = log2(z · B + O) · scale        clamped to [0, V_max]
+```
+
+`build_light_cluster_parameters` takes a near offset and a `scale`; `scale` is the linearization the deck
+describes (larger flattens the curve toward linear), and AVBOIT chooses it so that `O` is zero — pure log
+from `near + AVBOIT_DEPTH_CURVE_NEAR_OFFSET` — because the adaptive warp makes near-plane precision free.
+The parameters are built for `V_max`; the coordinate at the active resolution `V` is `slice × V / V_max`.
+Revisions 1–3 carried a curve of their own with the same shape and a `z0` knob; it was a reinvention.
+
+`V` starts at `AVBOIT_VIRTUAL_SLICES_MAX = 4096` (128 words of occupancy bits; 1024 until revision 3) and
+halves until the occupied count fits `AVBOIT_PHYSICAL_SLICES = 128`. Halving keeps the curve fixed and doubles slice thickness, so the
+occupancy at the coarser level is exactly the OR of adjacent pairs — no re-voxelization, which is what the deck
+notes too ("coverage data doesn't need to be regenerated"). The loop terminates at `V = P` in the worst case
+(three halvings from 1024).
+
+### 3.3 Occupancy prepass
+
+One thread per surviving meshlet (indirect over the filtered collection's count). The world AABB is projected
+with `aabb3_project(bounds, node.global)` exactly as the HZB filter does
+([`shader_hzb_meshlet_filter_1way.js`](../../cull/hzb/shader_hzb_meshlet_filter_1way.js)), then again with
+`camera.view_matrix`; the view-space depth range is `[-max.z, -min.z]` (the camera looks down −Z; see
+`chunk_volumetrics_sun_optical_depth.js:123`). Entirely in front of `near` → skip. Otherwise clamp to
+`[near, far]`, map both ends through `t()`, dilate by one virtual slice each side, and `atomicOr` the bits of
+that range into `occupancy: array<atomic<u32>, 32>`.
+
+Only the Z axis is voxelized. The deck also keeps XY tile occupancy to skip empty tiles in clear and
+integration; that is an optimization on passes that cost ~0.25 ms at our resolution and is out of scope (§7).
+
+### 3.4 Warp LUT build
+
+A single-invocation compute shader (`@workgroup_size(1)`) — the work is a few thousand bit operations, and a
+single lane keeps the whole thing runnable in the WGSL emulator, whose barriers are no-ops and which has no
+workgroup-cooperative dispatch. This is not a fallback for a subgroup path; a 1 K-entry prefix sum is not a
+workload.
+
+Per level, in order: dilate the occupancy by one slice each side *at this level* (a fragment on the edge of a
+meshlet's bounds linear-splats half its extinction one slice out, and that slice has to belong to the same run
+— dilating only at the finest level can shrink to nothing after halving), count, and either accept or halve the
+undilated bits and repeat.
+
+Output, `AVBOIT_WARP_STRUCT`:
+
+```
+virtual_count   u32      V
+occupied_count  u32      physical slices in use, ≤ P
+physical_count  u32      P
+voxel_width, voxel_height  u32   extinction resolution
+depth_near, depth_far, depth_z0  f32   the curve, copied so every consumer reads one place
+lut             array<u32, V_max + 1>   lut[v] = (prefix(v) << 1) | occupied(v);  lut[V] = occupied_count << 1
+```
+
+The warp itself is a continuous, monotonic, piecewise-linear map from virtual to physical depth:
+
+```
+φ(v_f) = prefix(v) + occupied(v) × frac(v_f),   v = min(floor(v_f), V - 1)
+```
+
+Slope 1 inside an occupied run, flat across a gap. Flat is the property that makes the deck's "filterable"
+begin/end flags unnecessary here: a sample that falls in a gap lands exactly on the boundary between the two
+runs, and with the integral stored at slice *boundaries* (§3.6) that reads the previous run's full total and
+none of the next run's — which is the right answer for empty space.
+
+### 3.5 Splat
+
+A render pass at `ceil(internal / AVBOIT_VOXEL_DOWNSCALE)` with the shared `vertex_shader_chunk`, no depth
+attachment, and a `r8unorm` transient colour attachment with `writeMask: 0` because WebGPU wants at least one
+attachment and the fragment shader has no outputs. No depth test against the opaque scene is needed: a splat
+behind an opaque surface lies at greater depth than any visible transparent fragment, and the integral at a
+depth only contains slices in front of it.
+
+The fragment computes `opacity` exactly as the MBOIT generate pass does (alpha, or Fresnel when
+`transmission_factor > 0`), then, new to this path, an RGB self-transmittance:
+
+```
+coverage  = min(opacity, OIT_COVERAGE_MAX)
+tint      = mix(vec3(1), base_colour, transmission_factor)      // clamped ≥ 1e-3
+T_self    = (1 - coverage) × tint
+e         = saturate(-log(T_self) / AVBOIT_EXTINCTION_MAX)       // AVBOIT_EXTINCTION_MAX = ln 256
+```
+
+so a plain alpha-blended material behaves exactly as under MBOIT (`tint = 1`) and a transmissive one filters
+the background per channel, which the scalar moment path cannot do and the deck lists as the reason RGB OIT is
+worth having.
+
+*Revision 2:* the tint weight is `transmission_factor × tint_from_base_color`, where the flag comes from
+`Renderer.avboit.transmission_tint_from_base_color` through the warp header, and is **off by default**. Base
+colour as transmission colour is glTF's semantics; the engine's material has no transmission colour, and its
+forward shader and path tracer transmit untinted, so the default keeps every mode agreeing on what an asset
+means. The RGB plumbing stays and costs nothing while it waits for a real transmission colour.
+
+Depth: `p_f = φ(t(z) × V)`; linear splat with `c = p_f - 0.5`, `(1 - frac c)` into `floor(c)` and `frac c`
+into the next slice, each clamped to `[0, P - 1]`. Each slice gets one `atomicAdd` of the three 8-bit counts
+packed 10|10|10 into a `u32` (§3.7). The returned previous value is checked per channel; a field that crosses
+255 records the slice in `overflow` — three `array<atomic<u32>>` planes, one per channel, holding
+`P - slice` under `atomicMax` so that the buffer's zero-clear reads as "no overflow" and no fill pass is needed.
+
+### 3.6 Integration
+
+One thread per voxel column. Walks `s = 0 … P - 1`, keeps a running RGB extinction, and stores it into
+`integral[x, y, s]` *before* adding slice `s` — an exclusive prefix, so texel `s` holds the integral at the
+near boundary of slice `s`, and the texture has `P + 1` depth texels with `integral[P]` holding the total. Per
+channel, once `s` reaches that channel's first overflow slice the running value is pinned at 1.0. Values are
+saturated at 1.0 throughout.
+
+Format: `rgba8unorm`, 3D, `STORAGE_BINDING | TEXTURE_BINDING`, sampled trilinearly. Eight bits is what the deck
+ships and what the splat already quantizes to; `rgba16float` is a one-constant change if a smoke gradient shows
+banding, at twice the memory (§9).
+
+Layout of `extinction`: column-major with slice fastest, `index = (y × W + x) × P + s`, so the integration
+reads 512 contiguous bytes per column.
+
+### 3.7 Packing and precision
+
+Three 8-bit values in 10-bit fields, as the deck does: two guard bits per field so that four saturating events
+in one slice can pile up before a carry corrupts the low bits of the neighbouring channel, and overflow is
+flagged the first time a field's sum exceeds 255 — past which the ray is extinct anyway. A carry out of the top
+field lands in the two unused bits.
+
+`AVBOIT_EXTINCTION_MAX = ln 256`: the fixed-point unit is `ln 256 / 255 ≈ 0.0217` of extinction, so the
+finest non-zero occlusion a single event can register is ~2.2 % and full saturation is `T = 1/256`. The
+resolve does *not* depend on this quantization for the surfaces' own alpha — the accumulators are float and
+carry the exact `-log(1 - α)` — only the relative ordering weights do.
+
+### 3.8 Draw
+
+A copy of the MBOIT resolve shader's shape — same vertex chunk, same material/scene/light groups, same forward
+shading and inline volumetric composite — with the moment lookup replaced by
+
+```
+v_s  = max(t(z) × V - AVBOIT_SAMPLE_BIAS_SLICES, 0)            // bias in virtual slices, see below
+w    = (φ(v_s) + 0.5) / (P + 1)
+E    = textureSampleLevel(integral, linear, vec3(uv, w), 0).rgb
+T    = exp(-E × AVBOIT_EXTINCTION_MAX)
+```
+
+and, before any of the shading, a discard when `T ≤ 1/256` in every channel — the volume already calls the
+fragment extinct, so its shading would be multiplied away; what its own extinction would have added to the
+total is bounded by that same `1/256` (revision 3, `AVBOIT_EXTINCT_TRANSMITTANCE`). Then three additive
+`rgba16float` targets:
+
+```
+accum_color += colour × coverage × T          (premultiplied, as MBOIT)
+accum_norm  += (1 - T_self) × T               per channel
+accum_ext   += -log(T_self)                   per channel
+```
+
+The bias is applied in *virtual* space before the warp, not in physical space after it: inside a run the two
+are identical, and at the start of a run the virtual bias walks into the gap, where φ is flat and the sample
+reads the previous run's total — instead of reading two slices into a run that may be arbitrarily far away.
+With the splat and storage conventions above the analytic minimum that avoids any self-occlusion is 1.5 slices;
+`AVBOIT_SAMPLE_BIAS_SLICES = 2.0` follows the deck and leaves half a slice of margin.
+
+IBL and Brick4 variants are two files, as for MBOIT, sharing the fragment body text; the Brick4 one carries
+the extra `brick4` storage buffer in the view group.
+
+### 3.9 Resolve
+
+RGB total transmittance cannot go through fixed-function blending without dual-source blending, so the resolve
+reads the scene colour as an input and writes a fresh `rgba16float` transient (the MBOIT blend shader's own
+`TODO` says as much). Per channel:
+
+```
+T_total = exp(-accum_ext)
+norm    = accum_norm > 1e-4 ? (1 - T_total) / accum_norm : 0
+out     = scene × T_total + accum_color × norm + accum_emission
+```
+
+with the same NaN backstop as MBOIT, falling back to the scene colour.
+
+*Revision 5:* `accum_emission` is the fourth accumulator, for fragments that emit without covering —
+additive particles today. Such a fragment writes zero extinction and zero norm, so the normalization, whose
+job is to redistribute exactly the `1 - T_total` the covering surfaces took from the scene, must not touch
+it; it joins the sum as it is, already attenuated by the transmittance in front of it at draw time. The
+alternative, a three-target draw pipeline for frames with no such source, is a variant of the draw the plan
+refuses to keep two of (§5); the cost of the fourth target is one `rgba16float` at internal resolution and a
+`vec4(0)` written by every transparent mesh fragment.
+
+### 3.10 The switch
+
+`src/shade/renderer/ShadeTransparencyMode.js`:
+
+```js
+export const ShadeTransparencyMode = { MBOIT: 0, AVBOIT: 1 };
+```
+
+`Renderer.transparency_mode = ShadeTransparencyMode.MBOIT` (public field, documented), and at the call site a
+ternary between the two orchestrators, which take the same argument object. Nothing else in `Renderer` changes.
+
+### 3.11 Device requirements
+
+AVBOIT blends only `rgba16float`, so it does not need `float32-blendable`; the atomics it uses on storage
+buffers from the fragment stage are core WebGPU. The engine keeps requiring `float32-blendable` while MBOIT is
+the default; the contract gets a sentence saying which mode needs it. The subgroup-using CSDLDF scan in the
+draw-command prep is shared with MBOIT and unchanged.
+
+One layout detail with no precedent in the tree: no render pipeline here writes a storage buffer from the
+fragment stage yet, and `ShaderResourceSetDescriptor.generatePipelineLayout(stage)` gives every group the same
+visibility. WebGPU refuses a `storage` buffer binding visible to the vertex stage, so the splat pipeline builds
+its layout group by group — material, scene and view at `VERTEX | FRAGMENT`, the atomics group at `FRAGMENT`.
+
+---
+
+## 4. Decisions and the alternatives they beat
+
+| Decision | Alternative | Why not |
+|----------|-------------|---------|
+| RGB 10\|10\|10 extinction from the start | Scalar 8\|8\|8\|8 (four slices per word, 4× less memory) | The deck's whole argument for the voxel path is that RGB becomes affordable, and a transmission colour on the material is the obvious next step; the scalar buffer is a memory optimization for VFX-heavy content, listed in §7. *Revision 2:* the per-channel tint is opt-in (§3.5) — the material model does not carry a transmission colour, so deriving one from the base colour by default made one asset mean two things across the mode switch. |
+| Packed 8-bit counts with overflow-min | One `u32` per channel per slice (no carry, no overflow logic) | 3× memory (200 MB at 4 K) and three atomics per splat; the deck measured packed at the same speed as monochrome. |
+| Storage buffer for the extinction volume | 3D storage texture | WebGPU has no atomic image operations. |
+| Integral as exclusive prefix at slice boundaries, `P + 1` texels | Inclusive prefix at slice centres | Makes a gap sample land exactly on a run boundary and read the right total; costs one extra depth texel. |
+| Sample bias in virtual space before the warp | Bias in physical space after it | Across a gap the physical bias reaches into a different depth region; the virtual one stops at the flat boundary. |
+| Warp LUT built by one invocation | Workgroup prefix sum with subgroup ops | 1 K entries; a single lane is microseconds and the emulator can run it. Not a fallback path. |
+| Occupancy from meshlet AABBs | Conservative software voxelization of quads and boxes (the deck) | The engine already has HZB-filtered meshlet bounds on the GPU; a meshlet is a tighter primitive than a mesh box. |
+| *Revision 4:* the engine's depth slicing, Morton decode, linear-clamp sampler and a shared draw loop | The pipeline's own curve, bit fold, sampler descriptor and a copy of the MBOIT draw loop | Reinventions, found in review. The one thing kept apart from the engine on purpose is the shared draw-fragment body text (`avboit_draw_fragment_body.js`): MBOIT duplicates its resolve body across the IBL and Brick4 files, and two 45-line bodies drifting apart is the worse failure. |
+| No depth test in the splat pass | Low-res depth from the HZB | Correctness does not need it (§3.5); it is a splat-throughput optimization to measure first. |
+| Resolve writes a new transient | Two in-place blend passes (multiply, then add) | One shader, one pass; the transient is aliased by the graph. |
+| `rgba8unorm` integral | `rgba16float` | Matches the deck and the splat quantization; the swap is one constant if banding shows. |
+| MBOIT stays the default | Flip to AVBOIT | The contract promises no lesser frame; the new path has not been seen on real content yet. |
+
+Rejected outright: the deck's chroma-skew approximation for memory-constrained platforms (slides 132–135) —
+it exists because that content could not afford the RGB buffer, and we can.
+
+---
+
+## 5. Files
+
+```
+src/shade/renderer/ShadeTransparencyMode.js
+src/shade/renderer/rasterize/native/material_draw_indirect.js   the per-material indirect draw loop, shared with MBOIT
+src/shade/renderer/rasterize/native/avboit/
+    AVBOIT_PLAN_2026_09_03.md               this document
+    AVBOIT_LEDGER.md                        the step ledger
+    AVBOIT_CONSTANTS.js                     P, V_max, downscale, curve offset, extinction max, bias, early-out
+    AVBOITSettings.js                       Renderer.avboit
+    AVBOIT_WARP_STRUCT.js                   header + LUT storage layout
+    avboit_build_depth_curve.js             cluster parameters for the finest resolution (JS)
+    chunk_avboit_pack_counts.js             10|10|10 pack
+    chunk_avboit_unpack_counts.js           … and unpack
+    chunk_avboit_transmittance_to_extinction.js
+    chunk_avboit_extinction_to_transmittance.js
+    chunk_avboit_extinction_to_counts.js
+    chunk_avboit_counts_to_extinction.js
+    chunk_avboit_overflows.js               the per-channel overflow predicate
+    chunk_avboit_occupancy_range.js         slice interval → dilated slice range
+    chunk_avboit_occupancy_word_mask.js     bits of one word inside a range
+    chunk_avboit_dilate_word.js             one-slice dilation across words
+    chunk_avboit_fold_pairs.js              halve a word's resolution (via decode32_morton2)
+    chunk_avboit_warp.js                    φ(v_f) over the LUT
+    chunk_avboit_view_depth_to_virtual.js   the curve, scaled to the active resolution
+    chunk_avboit_view_depth_to_physical.js  curve then warp
+    chunk_avboit_integral_depth_coordinate.js   bias, warp, boundary-centred texel coordinate
+    chunk_avboit_sample_transmittance.js    trilinear sample and exp
+    chunk_avboit_transmission_tint.js       base colour × weight
+    chunk_avboit_splat_slice.js             the two-slice voxel write, shared with the side channels
+    AVBOITSideChannel.js                    the contract for a non-meshlet transparent source (rev 5)
+    shader_avboit_occupancy.js              compute, per meshlet
+    shader_avboit_build_warp.js             compute, one invocation
+    shader_avboit_splat.js                  render pass, 1/8 resolution, atomics
+    shader_avboit_integrate.js              compute, per column
+    avboit_draw_fragment_body.js            shared WGSL text of the draw fragment
+    shader_avboit_draw_ibl.js               render pass, IBL indirect
+    shader_avboit_draw_brick4.js            render pass, Brick4 indirect
+    shader_avboit_resolve.js                image shader
+    graph_rasterize_meshes_transparent_avboit.js
+    avboit_spec_support.js                  test-only helpers
+    *.spec.js                               one per chunk and shader, see §6
+src/shade/playground/avboit/                A/B page, see §6 tier 4
+```
+
+Naming follows the directory's conventions: `chunk_*` for a `CodeChunk` holding exactly the one function the
+file is named after (650 of the engine's ~700 chunk files do; revision 4 brought these in line), `shader_*`
+for a complete pipeline, `graph_*` for a recorder, `SCREAMING_SNAKE` for structs and constants, specs beside
+their subject.
+
+---
+
+## 6. Verification
+
+The four tiers from [`gpu-testing-tiers`], each pinning what the one below cannot see:
+
+1. **WGSL validity** — `avboit_shaders_wgsl_validity.spec.js`, `test.each` over every assembled module
+   (vertex + fragment of splat and the two draws, the four compute shaders, the resolve image shader), zero
+   diagnostics. Catches missing chunk dependencies and reserved words; proves nothing about types.
+2. **Emulator** — numeric behaviour of the pure parts:
+   - `chunk_avboit_depth_curve.spec.js`: `t(near) = 0`, `t(far) = 1`, monotonic, `z(t(z)) = z`.
+   - `chunk_avboit_pack.spec.js`: pack/unpack round trip, the overflow predicate, extinction ↔ transmittance.
+   - `shader_avboit_build_warp.spec.js`: sparse occupancy keeps `V_max`; dense occupancy halves until it fits;
+     the LUT is a prefix sum with the dilation applied; `φ` is monotone, slope 1 on runs, flat on gaps.
+   - `shader_avboit_integrate.spec.js`: one column with events at known slices → exclusive prefix, saturation,
+     per-channel overflow pinning; written through `textureStore` into a 3D `CPUBitmapData`.
+   - `chunk_avboit_sample_transmittance.spec.js`: sampling in a gap returns the previous run's total; the bias
+     removes self-occlusion for an event splatted at the same depth.
+3. **SoftwareGPUDevice** — `graph_rasterize_meshes_transparent_avboit.spec.js`: the warp build's dispatch and
+   buffer, the integration's dispatch and its `P + 1`-deep storage-and-sampled texture, the resolve's single
+   full-screen draw into a fresh target, the splat pipeline's atomics group visible to the fragment stage
+   only, and a source-level pin of the `Renderer` switch. *Revision 3:* the software device records and
+   validates; it is not an end-to-end runner and never was meant as one, so a spec of the whole orchestrator
+   over a scene is not a goal of this plan. The composition is proven on a device.
+4. **Real compile and eyes** — every module through `createShaderModule` on a real device (the validator has no
+   type checker, [`wgsl-real-compile-via-browser-pane`]), then a playground page with layered transparent quads
+   at controlled depth separations, a tinted glass pane, and the MBOIT/AVBOIT switch — the deck's own test
+   harness in miniature. Bounded per [`bounded-user-verification`]: one scripted session, findings into the
+   ledger.
+
+---
+
+## 7. Out of scope (deliberately, with the reason)
+
+*Revision 3* decides the optimizations one by one, against the rule that a phase-2 item has to be clean and
+unambiguous, must not break anything else, and must not be situational:
+
+- **Per-fragment extinct early-out** — *done* (§3.8). No new resource, no pass, a bounded error below the
+  volume's own precision, and it removes the whole forward shading cost of every fragment behind something
+  opaque-in-the-volume.
+- **XY tile occupancy** to skip empty tiles in clear and integration — *no*. The passes it would trim are
+  sub-millisecond at 1/8 resolution and the clear is one `clearBuffer`; the prepass would gain a second
+  output and the integration a second input for a saving that would not register.
+- **Zero-transmittance depth cull** (slides 77–85) — *not now*. It is the deck's largest measured win on
+  VFX-heavy scenes, and it is exactly the situational kind: nothing on a scene without dense overdraw, a
+  depth copy because post-process reads the scene depth after transparency, and a new pass that writes depth.
+  Worth a plan of its own when there is a scene that needs it and a profile that shows the draw cost.
+- **Monochrome extinction buffer** beside the RGB one — *no*. Two representations of the same volume and a
+  merge in the integration, for content that is mostly scalar VFX; this engine's transparent content is not
+  known to be that.
+- **Sparse voxel texture** (slide 122) — *no*. The deck's own future work.
+- **Chroma skew** (§4).
+- **`ShadeDrawSide.Back` transparent materials** — dropped today by MBOIT; the same filter is used here so the
+  two modes draw the same set. Fixing it is a bucket-filter change that belongs to both.
+- **Exposing the tunables on `Renderer`** — the constants in `AVBOIT_CONSTANTS.js` are the knobs; whether any
+  deserves a public field is a question for after the page in §6 has been looked at. *Revision 2:* one did —
+  the transmission tint, because it changes a material's meaning rather than a quality/cost trade; it lives
+  on `Renderer.avboit` (`AVBOITSettings`).
+
+---
+
+## 8. Staging
+
+Each step lands with its tests green before the next starts; the ledger records what each found.
+
+1. **Skeleton and switch** — enum, `Renderer.transparency_mode`, an orchestrator that records only the shared
+   prep and the resolve (identity), the prep helper's two extra return values. Proves the wiring compiles and
+   the default frame is byte-identical.
+2. **Depth curve, warp, pack chunks** with their emulator specs.
+3. **Occupancy + warp build** shaders, the warp struct, emulator spec for the build.
+4. **Splat** shader and the per-group pipeline layout; validity spec.
+5. **Integrate** shader with its emulator spec; the 3D integral texture in the graph.
+6. **Draw** (IBL and Brick4) and the sample chunk with its spec; the three accumulators.
+7. **Resolve** image shader; the orchestrator complete; SoftwareGPUDevice spec.
+8. **Real compile** of every module on a device; fix what the type checker finds.
+9. **Playground** A/B page; look; record.
+10. **Docs** — contract, changelog, ledger closed out.
+
+---
+
+## 9. Risks and open questions
+
+- **Sub-pixel geometry at 1/8 resolution** never reaches the extinction volume, so it does not occlude anything
+  behind it (it still draws). The deck accepts this for VFX; thin glass edges may show it. The downscale is a
+  constant.
+- **Meshlet bounds as occupancy** are conservative in depth only as far as the bounds are right; skinned meshes
+  with stale bounds would splat outside their run and clamp to its edge. Watch for it on the page.
+- **8-bit integral** — banding in long smooth gradients; the swap to `rgba16float` is one constant.
+- **Contention** — every fragment of a large sprite covering the same low-res texel hits the same `u32`; the
+  deck's numbers say this is fine on console, and a WebGPU number is what the page is for.
+- **The bias** — 2.0 virtual slices is the deck's figure; 1.5 is the analytic minimum here. Lower means closer
+  events occlude each other; the page's layered quads are the test. *Revision 3:* kept at 2.0. The margin over
+  the minimum is what covers the depth difference between a splat fragment (one 1/8-resolution pixel centre)
+  and a draw fragment (a full-resolution pixel centre) on a sloped surface, and the slice floor was raised by
+  `AVBOIT_VIRTUAL_SLICES_MAX` instead (§3.2).
+- **Sloped surfaces** — a splat fragment carries the depth of its low-resolution pixel centre; on a surface at
+  a grazing angle that can differ from the full-resolution fragment's depth by more than the bias. Self-occlusion
+  along the slope would be the symptom; the page's copyable camera state is what makes that reproducible.

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_WARP_STRUCT.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The depth-warp LUT and everything a consumer needs to use it, written once per frame by
+ * `shader_avboit_build_warp` and read by the splat, integrate and draw passes.
+ *
+ * `lut[v] = (prefix(v) << 1) | occupied(v)` for `v` in `[0, virtual_count]`, where `prefix(v)` counts
+ * the occupied virtual slices before `v`. `lut[virtual_count]` carries the total with the occupied bit
+ * clear. Entries past `virtual_count` are not written and must not be read; `chunk_avboit_warp` clamps.
+ *
+ * The header repeats the curve parameters, the voxel resolution and the renderer's switches so that a
+ * fragment shader reads one buffer rather than a uniform it would otherwise need a bind group of its
+ * own for.
+ */
+export const AVBOIT_WARP_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=AVBOIT_WARP_STRUCT.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_WARP_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AVBOIT_WARP_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOIT_WARP_STRUCT.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,8CAewB;6BA9BK,sCAAsC"}

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_WARP_STRUCT.js

@@ -0,0 +1,33 @@
+import { u32, vec3f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { AVBOIT_VIRTUAL_SLICES_MAX } from "./AVBOIT_CONSTANTS.js";
+
+/**
+ * The depth-warp LUT and everything a consumer needs to use it, written once per frame by
+ * `shader_avboit_build_warp` and read by the splat, integrate and draw passes.
+ *
+ * `lut[v] = (prefix(v) << 1) | occupied(v)` for `v` in `[0, virtual_count]`, where `prefix(v)` counts
+ * the occupied virtual slices before `v`. `lut[virtual_count]` carries the total with the occupied bit
+ * clear. Entries past `virtual_count` are not written and must not be read; `chunk_avboit_warp` clamps.
+ *
+ * The header repeats the curve parameters, the voxel resolution and the renderer's switches so that a
+ * fragment shader reads one buffer rather than a uniform it would otherwise need a bind group of its
+ * own for.
+ */
+export const AVBOIT_WARP_STRUCT = WebGPUStruct.from({
+    /** active virtual slice count V, a power-of-two divisor of AVBOIT_VIRTUAL_SLICES_MAX, ≥ physical_count */
+    virtual_count: u32,
+    /** physical slices in use after packing, ≤ physical_count */
+    occupied_count: u32,
+    /** AVBOIT_PHYSICAL_SLICES, here so the shaders and the allocation cannot disagree */
+    physical_count: u32,
+    /** extinction volume XY resolution */
+    voxel_width: u32,
+    voxel_height: u32,
+    /** 1 when transmitted light is filtered by the base colour, see AVBOITSettings; 0 otherwise */
+    tint_from_base_color: u32,
+    /** the depth curve for the finest virtual resolution, see avboit_build_depth_curve */
+    cluster_parameters: vec3f,
+    lut: WebGPUArray.from(u32, AVBOIT_VIRTUAL_SLICES_MAX + 1),
+}, "AVBOITWarp").pack();

package/src/shade/renderer/rasterize/native/avboit/avboit_build_depth_curve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The depth curve of the extinction volume, as `cluster_parameters` for the engine's log slicing
+ * (`cluster_depth_to_z_slice`), built for the finest virtual resolution.
+ *
+ * `build_light_cluster_parameters` is the light clusters' and the froxels' curve: slice
+ * `= log2(depth · B + O) · scale`, with `scale` deciding how much of the range is logarithmic and
+ * `near_offset` where it starts. The choice here is pure log from the offset plane — `scale` such that
+ * `O` comes out zero — because the adaptive warp makes near-plane precision free (empty slices cost no
+ * physical slice), so there is nothing to gain by flattening the curve as the light clusters do.
+ *
+ * Slice thickness at view depth `z` is then `z · ln(far / offset) / (V_max - 1)`; the numbers for the
+ * defaults are on `AVBOIT_VIRTUAL_SLICES_MAX`.
+ *
+ * @param {number} near camera near plane, world units
+ * @param {number} far camera far plane, world units
+ * @param {Float32Array|number[]} [result] three floats
+ * @returns {Float32Array|number[]} `result`
+ */
+export function avboit_build_depth_curve(near: number, far: number, result?: Float32Array | number[]): Float32Array | number[];
+//# sourceMappingURL=avboit_build_depth_curve.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/avboit_build_depth_curve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avboit_build_depth_curve.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/avboit_build_depth_curve.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,+CALW,MAAM,OACN,MAAM,WACN,YAAY,GAAC,MAAM,EAAE,GACnB,YAAY,GAAC,MAAM,EAAE,CAiBjC"}