@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,600 +0,0 @@
-# Adaptive voxel-based order-independent transparency (AVBOIT) — implementation plan
-
-**Status:** implemented, default mode, device tier in progress — revision 8
-**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.
->
-> **Revision 6** (ledger entry 22) adds the second side channel and the door to it. `DynamicMeshAVBOITChannel`
-> draws a `DynamicMeshBatch` — trails, first and only — through the three contracts, and a channel can now come
-> from outside the renderer: `Renderer.add_transparency_channel`, held across restarts by
-> `GraphicsEngine.add_transparency_channel` the way extensions are. A channel may say it is empty
-> (`avboit_is_empty`) and is then left out of the frame, so one that is always registered does not make the
-> orchestrator run on frames with nothing transparent. What the particle channel did privately and a second
-> channel needs — the coverage clamp, the covering/emitting routing, a world box's depth interval and the slice
-> marking — are shared chunks now. The meshlet passes are untouched.
->
-> **Revision 7** (ledger entry 24): the dynamic meshes' splat is rasterized with four samples and weights each
-> fragment's extinction by the share of the voxel its triangle covers, so a trail thinner than a voxel
-> occludes steadily instead of in the columns whose centres it happens to cross (§9). The meshlet and particle
-> splats are unchanged.
->
-> **Revision 8** (ledger entry 26) is the review against the deck. The lookup bias grows by the fragment's
-> own footprint (§3.8), which closes §9's sloped-surface risk. The particle splat's soft fade is averaged over
-> the voxel rather than read at its corner. A water plane in view takes the warp's whole budget (§9); taking
-> the water out of the volume was tried and withdrawn as anti-OIT.
->
-> **Revision 9** (ledger entry 27): the warp build can try virtual resolutions between octaves
-> (`AVBOITSettings.warp_steps_per_octave`) and hold the previous frame's against refining
-> (`warp_hysteresis`), both off by default (§3.4). The deck's curve re-adjustment was measured and gives
-> nothing from a pure-log curve.
->
-> **Revision 10** (ledger entry 28): the warp build is one workgroup, an invocation per occupancy word, with
-> subgroup reductions and a subgroup scan for the LUT (§3.4); it was one invocation.
->
-> **Revision 11** (ledger entry 29): four steps per octave is the default, and revision 9's hysteresis is
-> removed.
-
----
-
-## 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)`.
-   *2026-09-16: `ShadeDrawSide.Back` transparent materials used to be dropped here. They are not any
-   more — `Back` and `Front` are one bucket now, so asking for either returns both.*
-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 (*revision 6:* and the dynamic meshes, for trails, the
-second). `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
-
-*Revision 10:* one workgroup of 128 invocations, one per occupancy word. Revisions 1–9 had a single
-invocation, on the argument that a 1 K-entry prefix sum is not a workload and that a single lane keeps the
-shader runnable in the WGSL emulator; at `V_max = 4096` the serial LUT alone measured 136 µs (ledger entry 27).
-A resolution tried is every invocation marking the virtual slices its finest word's runs touch, at most two
-words, OR-ed into workgroup memory, then every word of it dilated by its own invocation and counted with a
-subgroup reduction; the LUT is a subgroup scan of the chosen words' counts. Each decision is made on a count
-read back through `workgroupUniformLoad`. The emulator cannot run it: the pure parts are chunks with specs,
-and the whole was verified bit-exact against the single-lane build on a device (ledger entry 28).
-
-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
-resolution, marked afresh from the finest 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.
-
-*Revision 9:* with `warp_steps_per_octave > 1` the build also tries `2 L · 2^(-i / steps)` virtual slices
-between the octave `L` that fits and the one above it, finest first, with the finest bits rewritten into
-those slices conservatively run by run, so the occupied count lands closer to the budget; any virtual count
-works downstream, since the coordinate is the finest one scaled by `V / V_max`. Ledger entry 27 has what it
-buys and costs. *Revision 11:* four steps is the default; the hysteresis revision 9 added beside the steps
-is removed (ledger entry 29).
-
-### 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.
-
-*Revision 8:* that minimum is for a surface splatted at its own depth, and the draw also reads the
-neighbouring columns, up to a voxel away, where a surface tilted away from the camera was splatted nearer.
-Every draw of a surface that splats adds `avboit_footprint_bias` — `8 × fwidth(v)` virtual slices, a voxel's
-width of its own depth change, capped at `2 V / P`, the base bias of the coarsest slicing — so a tilted
-surface does not occlude itself; additive particles, which write nothing into the volume, add none. A
-tilted fragment is then not occluded by what lies within that band in front of it (ledger entry 26). The
-cap bounds the band; the whole reach is at most `2 + 2 V / P`.
-
-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. |
-| *Revision 10:* warp built by one workgroup, an invocation per occupancy word, subgroup reductions and scan | One invocation (revisions 1–9) | At 4096 virtual slices the serial LUT alone cost 136 µs on an RTX 4090, and the steps' run walk up to 295 µs more; the workgroup takes 3–9 µs with the same output (ledger entry 28). The emulator cannot run it; its pure parts are chunks with specs. |
-| 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); unused since rev 10
-    chunk_avboit_warp_marks.js              the virtual slices a finest word's runs touch (rev 10)
-    chunk_avboit_warp_level_word.js         a resolution's word, dilated and cut at V
-    chunk_avboit_warp_step_count.js         the resolutions between octaves
-    chunk_avboit_warp_lut_entry.js          one LUT entry from its word and the count below it
-    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 workgroup (rev 10)
-    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.~~ **Done,
-  2026-09-16 (`ca95ad3ac`)**, and it was the bucket-filter change this predicted: `Back` is `Front` with
-  the winding reversed in the vertex shader, so both modes draw it and neither needed a third pass.
-- **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.
-  *Revision 7:* trails are the case where it showed — a moving thin trail occluded in some columns and not
-  others — and the dynamic-mesh splat alone is multisampled and coverage-weighted now (ledger entry 24).
-  Such a trail reaches the volume everywhere, diluted to the share of each voxel it covers.
-- **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.
-  *Revision 8:* measured and closed. It was not only grazing angles: from about 30° at 1080p a tilted surface
-  over another transparent layer striped in an 8-pixel sawtooth, 3–5 sRGB codes on the device at 45–60°. The
-  footprint bias (§3.8) removes it up to its cap, about 85° in a sparse volume (ledger entry 26).
-- **A surface spanning a long depth range** — a water plane above all, from the shore to the horizon —
-  occupies so many virtual slices that the warp halves to `V = P`, and every other transparent surface in
-  the frame is sliced at the coarsest resolution (*revision 8*, measured in ledger entry 26).

package/src/shade/renderer/restir/reservoir/NOTES.md

@@ -1,6 +0,0 @@
-Basic idea is to stocastically decide which lights are visible, and feed that information into shading stage
-
-References:
-https://github.com/NVIDIAGameWorks/RTXDI
-http://www.zyanidelab.com/how-to-add-thousands-of-lights-to-your-renderer/
-https://cwyman.org/presentations/2021_HPG_Productizing_ReSTIR.pdf

package/src/shade/renderer/shader/chunk/atmosphere/NOTES.md

@@ -1,6 +0,0 @@
-# references:
-https://sebh.github.io/publications/egsr2020.pdf
-https://www.shadertoy.com/view/slSXRW
-https://www.reddit.com/r/GraphicsProgramming/comments/osbbhg/shadertoy_implementation_of_a_scalable_and/
-https://github1s.com/Fewes/MinimalAtmosphere/blob/master/Assets/Atmosphere/Shaders/Atmosphere.cginc#L146
-https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/1bbe66e7ea0d358e84af4471a90aa9c35b583de0/framework/rendermodules/skydome/shaders/skydomeproc.hlsl#L70