@woosh/meep-engine 3.11.0 → 3.11.2

package/src/engine/graphics3/ParticipatingMediaSystem3.js

@@ -0,0 +1,184 @@
+import { assert } from "../../core/assert.js";
+import { isArrayEqualStrict } from "../../core/collection/array/isArrayEqualStrict.js";
+import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+
+/**
+ * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
+ *
+ * The same shape as {@link LightSystem3}: the ECS says what exists and where, and this keeps the
+ * renderer's own objects in step. A {@link ParticipatingMediaVolume} is a unit cube posed by a
+ * transform, so an entity's `Transform` is the volume — position, size and orientation with no
+ * translation step in between.
+ *
+ * **The transform is taken as world-space, with no hierarchy applied**, which is what the volume
+ * model can express: a volume is an oriented box in the scene and Shade has no parent chain to walk
+ * for it. Parenting a fog volume to a moving entity therefore leaves the fog where the child's own
+ * transform puts it. The lights are placed the same way, for the same reason.
+ *
+ * **Changes are polled once a frame rather than subscribed to.** A `Transform` announces itself and
+ * nothing else here does — a density tuned by an editor slider, a particle spec swapped wholesale
+ * for a different Mie solution — so subscribing would cover one field in three and the other two
+ * would still have to be polled. Two paths that have to agree, where one does the whole job. It
+ * costs about two dozen float comparisons per volume per frame and a scene holds volumes in the
+ * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
+ * change is visible within a frame rather than instantly.
+ *
+ * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
+ * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
+ * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
+ * frame it decides nothing has to happen.
+ *
+ * @see ParticipatingMedia the component
+ * @see SceneVolumetrics what the volumes are handed to
+ */
+export class ParticipatingMediaSystem3 extends System {
+
+    dependencies = [ParticipatingMedia, Transform];
+
+    /**
+     * @type {GraphicsEngine3}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {Map<number, {component: ParticipatingMedia, transform: Transform, volume: ParticipatingMediaVolume}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#graphics.set_scene(this.#scene);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(component, transform, entity) {
+        const volume = new ParticipatingMediaVolume();
+
+        participating_media_volume_write(volume, component, transform);
+
+        this.#scene.volumetrics.add(volume);
+
+        this.#entries.set(entity, { component, transform, volume });
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        const volumetrics = this.#scene.volumetrics;
+
+        for (const entry of this.#entries.values()) {
+            const volume = entry.volume;
+
+            if (participating_media_volume_is_current(volume, entry.component, entry.transform)) {
+                continue;
+            }
+
+            participating_media_volume_write(volume, entry.component, entry.transform);
+
+            volumetrics.invalidate();
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#scene.volumetrics.remove(entry.volume);
+
+        this.#entries.delete(entity);
+    }
+}
+
+/**
+ * Copy what the component and its transform say onto the volume Shade will render.
+ *
+ * The particle spec is **copied, not referenced**: two entities are routinely built from the same
+ * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
+ * retune the other's.
+ *
+ * @param {ParticipatingMediaVolume} volume Shade's
+ * @param {ParticipatingMedia} component meep's
+ * @param {Transform} transform where the box is
+ */
+export function participating_media_volume_write(volume, component, transform) {
+    volume.density = component.density;
+    volume.fade_distance = component.fade_distance;
+
+    volume.particle_spec.copy(component.particle_spec);
+
+    volume.transform.copy(transform);
+}
+
+/**
+ * Whether the volume already says what the component and transform say.
+ *
+ * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
+ * scene's volumetrics table a trip to the GPU.
+ *
+ * **The transform is compared by its matrix rather than by `Transform.equals`**, because the matrix
+ * is the entire transform the GPU is given — the volume's position, rotation and scale are never
+ * read on their own. That makes this exactly the question worth asking, "would the upload differ",
+ * and it catches a transform posed by writing its matrix, which comparing position, rotation and
+ * scale would not.
+ *
+ * @param {ParticipatingMediaVolume} volume
+ * @param {ParticipatingMedia} component
+ * @param {Transform} transform
+ * @returns {boolean}
+ */
+export function participating_media_volume_is_current(volume, component, transform) {
+    return volume.density === component.density
+        && volume.fade_distance === component.fade_distance
+        && isArrayEqualStrict(volume.transform.matrix, transform.matrix)
+        && volume.particle_spec.equals(component.particle_spec);
+}

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#354@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#356@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#354@#clear_field"(fluid: FluidComponent): void;
+    static "__#356@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#354@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#356@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#354@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#356@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

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

@@ -0,0 +1,191 @@
+# volumetrics_froxel
+
+Real participating media, a movable sun and a wide-FOV camera in front of the froxel volumetrics
+pass.
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/volumetrics_froxel/index.html>.
+
+## Why it exists
+
+`shader_volumetrics_build_lighting` and the passes around it were reviewed against current practice.
+Five correctness findings came out of it; four were fixed and one was closed as a documented
+non-issue. All five were geometric, and geometry is the class of defect a unit test can prove but
+not show — an emulator can assert that a sample lands at the wrong depth and still not tell you
+whether that reads as a smear, a seam, or nothing at all. This page was where that got decided.
+
+| finding | what it was | where the fix lives |
+|---|---|---|
+| C-01a | Planar view depth walked as a distance along a unit ray, so the froxel sample fell short by cos θ | `chunk_camera_ray_planar_depth_scale`, from the lighting pass |
+| C-01b | The aerial pass integrated Beer's law over a planar depth difference rather than arc length | same chunk, from the aerial pass — this was the visible half |
+| C-02 | Cell-averaged grids read with the boundary-sampled convention, a ~0.53-froxel bias | `chunk_volumetrics_froxel_content_offset` |
+| C-03 | Shadow ray clipped against a frustum with no far plane, so a sun anywhere in the view cone got zero optical depth | `chunk_integrate_optical_depth` takes the metadata frustum |
+| C-04 | The shadow march addressed the froxel grid with the aerial LUT's depth curve | `volumetrics_position_world_to_froxel_uvw` |
+| C-05 | Adjacent columns carry independent jitter, so an XY fetch mixes depths | closed — zero-mean and TAA-absorbable; `volumetrics/NOTES.md` has the measurements and why the obvious fix makes it worse |
+
+Those fixes are in the permanent path now and there is nothing left to A/B. What the page is for is
+the *next* change here — the performance findings especially, since every one of them trades image
+quality for time and none can be judged from a screenshot.
+
+Q-01 was judged here and now ships unconditionally: every clustered point and spot light is occluded
+by geometry, sampled with one nearest tap out of the shadow atlas. The two checkboxes that switched
+that off, or swapped the tap for the deferred pass's filter kernels, are gone along with the metadata
+word behind them — `volumetrics/NOTES.md` keeps the measurements that closed the question. The
+torches are the local lights here: 130 point lights, every one of them a shadow caster, and **zero
+spot lights**, so the spot half has no on-screen coverage on this page and is covered by
+`shader_volumetrics_build_lighting_local_shadow.spec.js` instead. Adding a `SpotLight` from the
+console is the way to look at it.
+
+Q-04 went the same way and its switch is gone too. The sun's media self-shadowing is one fetch into
+a ladder of three cascaded volumes built once a frame with their third axis on the sun, and that is
+now the only path for it: the `__VOL_SUN_SHADOW` global and the checkbox over it are removed along
+with the `sun_shadow_mode` word they drove, so nothing on this page reproduces the march/cascade
+comparison any more. Restoring it means re-adding that word and the branch in
+`shader_volumetrics_build_lighting` that reads it.
+
+Worth knowing what it was, because it is the size of what the page can no longer show. Against a
+march at `STEP_COUNT = 512` the cascades read within 1.2 mean luminance at every viewpoint here and
+across 40 to 110 degrees of field of view, while sixteen steps read **+58** and **+70** at the two
+poses beside the small fog boxes — the step there is eight units, the box is three thick, and the
+march goes straight over it. They are also cheaper: 0.37 ms against 0.53 at 1080p, 0.81 against 1.52
+at 2160p, per pass. `volumetrics/NOTES.md` has the whole measurement, including the one that says a
+*single* world-uniform box could not have been sized correctly at any resolution — every shape
+measured has a field of view at which it is 28 to 50 luminance from the truth, and which one that is
+moves with the resolution.
+
+The march itself is still in the tree and still runs: every point and spot light uses it, and so
+would a second directional light. Only the first one is amortized, because there is one ladder of
+boxes and it is aligned to one direction.
+
+## Measuring, rather than eyeballing
+
+This pass is stochastic and temporally filtered, so most changes to it move the image by less than
+the frame-to-frame noise. A screenshot pair is not evidence. Four traps, each of which produced a
+confident wrong answer during the work above:
+
+- **Auto exposure.** It keeps adapting for seconds after any change, so two captures of the
+  *identical* setting differed in mean luminance by more than the change being judged. Off by
+  default here; `renderer.exposure_compensation` sets the fixed value.
+- **Per-frame jitter.** The column jitter and the sample RNG both key on `view.frame_index`, so
+  consecutive frames genuinely differ. Average 18+ frames per capture.
+- **No noise floor, no result.** Capture the *same* setting twice and difference those first. If the
+  change's delta is not clearly above that, nothing has been shown.
+- **The noise floor has to pay the same costs the signal does.** Anything that calls
+  `indicate_view_change()` resets temporal accumulation, so a capture taken right after one carries
+  a re-convergence transient that a back-to-back capture does not. Measuring the floor without that
+  in the middle inflates every result — it made C-04 fail a test it should have passed. Capture as
+  *change → settle ~45 frames → average*, and take the floor by making an identical no-op change so
+  both paths cost the same.
+
+- **Frame time here is presentation-throttled, not GPU-bound.** At 1920×1080 every setting reads
+  ~16.5 ms, including settings that do obviously different amounts of work — `ms_octaves` at 1 and at
+  8 come back within noise of each other, which is the tell. The swap chain is pacing the
+  measurement. Raise `renderer.pixel_ratio` until the GPU is the bottleneck (3 gives 3840×2160 and
+  ~10 ms of real work here), interleave the settings round-robin so drift hits all of them equally,
+  and take medians. Remember the froxel grid scales with resolution, so a per-froxel cost measured at
+  4× the pixels is 4× the one you will pay.
+
+Prefer the **signed mean** when the change has a direction; it discriminates far better than the
+mean-absolute, which is dominated by noise. C-01b read −0.148 at 60° FOV against a floor of ±0.05,
+and −1.071 at 110°: same fix, and that 7× is the `1/cos θ` scaling it predicts.
+
+Also: mutating `light.intensity` does not mark the light buffer dirty, so a sweep of it renders
+identically. Remove and re-add the light instead.
+
+### measure.js
+
+`measure.js` is that protocol as code, loaded from the console rather than by the page:
+
+```js
+const m = await (await import('./measure.js')).attach();
+const r = await m.ab(v => globalThis.__VOL_TAA_ENABLED = v, false, true);
+```
+
+`attach` pauses the page's loop — which matters for a reason beyond frame counting: that loop
+assigns `renderer.pixel_ratio = window.devicePixelRatio` on every tick, ahead of its own pause check,
+so a raised pixel ratio is undone before the next frame unless the loop is stopped. `set_pixel_ratio`
+replaces the property for the same reason.
+
+Everything renders into a texture the module owns, through `Renderer.render_to_target`, which shares
+the view context and therefore all the temporal history with the canvas path. That is not a
+refinement: a canvas texture is configured by the presentation path, cannot carry `COPY_SRC`, and is
+rotated away the moment the frame is presented, so a `drawImage` off it a task later returns an empty
+bitmap — and a comparison of two blanks reports perfect agreement. Driving the frames from here also
+takes the swap chain out of the timing entirely, which is the presentation-throttling trap above.
+
+`ab` runs the two settings interleaved and takes its own floor from a repeat of each. `fly`,
+`converge_at` and `series_stats` are the camera-path half: a structure fitted to the camera can be
+perfectly correct standing still and swim under motion, and neither swimming nor the ghosting the
+0.95-blend TAA turns it into is visible in a still. `time` and `profile` answer different questions and
+`profile` is the one to believe — at 1080p, whole-frame timing of Q-04 came back with the wrong sign
+three runs in a row while the per-pass capture read it cleanly.
+
+`profile` records a `WORKLOAD` session and decodes it in the page, so a cost number does not need a
+downloaded `.sgpt` and a second tool. It returns the median duration per pass label over the frames
+it recorded. Interleave the settings and take medians across rounds even so — the run-to-run spread
+on this machine moves a pass by more than most changes to it do:
+
+```js
+const p = await m.profile({ frames: 24 });
+p['Volumetrics / build sun shadow volume 0'];
+```
+
+## Recording a GPU profile
+
+**T** starts a recording, **T** again stops it and downloads a `.sgpt` capture. The engine side is
+already there — `Renderer.profile_session` is a nullable field and the null checks around it are the
+whole integration — so this page is only the two imports, the key handler, and the metadata a capture
+needs in order to mean anything later: adapter, engine version, device features, and a note carrying
+the viewpoint, FOV, pixel ratio and volumetric TAA setting that were in force when you pressed the
+key.
+
+Level is `WORKLOAD`: pass spans, the frame graph, and dispatch/draw counts. Measured on this page it
+runs about 11 KB a frame — roughly 660 KB/s at 60 Hz, and around 393 spans per frame — with the frame
+graph topology stored once and shared by every frame. `VERBOSE` above it adds bind group contents at
+about seven times the rate and wants a frame limit set; `PROFILE_LEVEL` in `main.js` is the one line
+to change.
+
+Two things to know. Stopping does not end the recording immediately: a frame is committed when its
+timestamp readback lands, a `mapAsync` a frame or two behind submit, so the handler drains the queue
+and waits for the frame count to settle before it writes the file — otherwise the last frames, the
+ones you were probably looking at, are the ones missing. And the browser asks before letting a page
+save more than one file, so a second capture may never appear; the filename goes to the console
+either way.
+
+Frames only accumulate while the page is rendering, so a recording taken while paused stays at zero.
+
+## Scene
+
+`flying_world_-_battle_of_the_trash_god/v2`, six participating-media volumes, a low sun, and the
+Venice sunset environment. Both the volumes and most of the camera placements are carried over from
+the sibling repo's playground, where they were found by hand against this exact model — keeping the
+numbers means a before/after pair is taken from the same place to the pixel.
+
+Assets live under `test_assets/`, which is gitignored; `test_assets/README.md` has how they get
+there. This page needs:
+
+```bash
+mkdir -p "test_assets/flying_world_-_battle_of_the_trash_god/v2"
+cp "H:/git/meep-renderer-deferred-algo/public/flying_world_-_battle_of_the_trash_god/v2/scene.gltf" "H:/git/meep-renderer-deferred-algo/public/flying_world_-_battle_of_the_trash_god/v2/scene.bin" "test_assets/flying_world_-_battle_of_the_trash_god/v2/"
+cp "H:/git/meep-renderer-deferred-algo/public/environments/octahedral/venice_sunset_2k.hdr" test_assets/environments/octahedral/
+```
+
+Only `scene.gltf` and `scene.bin` are needed from that directory — about 26 MB. glTF rather than the
+`.shade` sitting beside it: that export's header reads format version 1 and `deserialize_scene`
+accepts version 2 only, deliberately and with no backward compatibility.
+
+## Notes
+
+Two viewpoints from the sibling repo (`v_volumetrics_light_extinction_0` and `_1`) sit inside
+geometry here and were replaced with placements verified against this build. Two more —
+*Beside the fog box* and *Beside the fog box, deeper* — were added for Q-04: they are the only
+placements in the scene where the sun's path through the medium is short enough for the 16-step
+march to miss it, which makes them the ones any change to that path has to be judged at. *Log camera* writes the
+current placement to the console in the form the `VIEWS` table takes, which is how to add more.
+
+Frame time settles around 28 ms at 1920×1080 on a 4070-class part. That is the whole frame, not the
+volumetrics pass — separating it out needs a timestamp query. It is the baseline the performance
+findings (P-01 … P-06) would move.

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

@@ -0,0 +1,270 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — froxel volumetrics</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --panel: rgba(20, 22, 26, 0.88);
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+            --tag: #c98b3f;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; overflow: hidden; background: #0d0f12; }
+
+        /* body carries tabindex so the camera controller's keyboard device has something focusable
+           to listen on; the focus ring around the whole viewport is not wanted */
+        body:focus { outline: none; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            width: 330px;
+            max-height: calc(100vh - 24px);
+            overflow-y: auto;
+            padding: 12px 14px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            backdrop-filter: blur(6px);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #panel h1 { font-size: 13px; font-weight: 600; margin: 0 0 8px; }
+
+        h2 {
+            font-size: 11px;
+            font-weight: 600;
+            text-transform: uppercase;
+            letter-spacing: 0.06em;
+            color: var(--muted);
+            margin: 0 0 6px;
+        }
+
+        label { display: flex; align-items: center; gap: 8px; padding: 3px 0; cursor: pointer; }
+        label input[type="checkbox"] { margin: 0; }
+        label .hint { color: var(--muted); font-size: 11.5px; }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 10px 0; }
+
+        button {
+            font: inherit;
+            padding: 5px 11px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+            cursor: pointer;
+        }
+
+        button:hover { border-color: #3d4552; }
+        button:focus-visible { outline: 2px solid var(--tag); outline-offset: 2px; }
+
+        #views { display: flex; flex-direction: column; gap: 4px; }
+
+        button.view {
+            text-align: left;
+            display: flex;
+            align-items: baseline;
+            gap: 8px;
+            padding: 4px 9px;
+            font-size: 12.5px;
+        }
+
+        .tag {
+            font: 10px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--tag);
+            border: 1px solid currentColor;
+            border-radius: 3px;
+            padding: 0 4px;
+            flex: 0 0 auto;
+        }
+
+        .slider {
+            display: grid;
+            grid-template-columns: 1fr auto;
+            align-items: center;
+            gap: 2px 8px;
+            padding: 4px 0;
+        }
+
+        .slider .name { font-size: 12px; }
+        .slider .value {
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--muted);
+            text-align: right;
+            min-width: 44px;
+        }
+        .slider input[type="range"] { grid-column: 1 / -1; width: 100%; margin: 0; }
+
+        .row { display: flex; gap: 6px; align-items: center; }
+        .row button { flex: 1 1 auto; }
+
+        #status { font-size: 12px; color: var(--muted); word-break: break-word; margin-top: 6px; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #stats, #profile_status {
+            margin-top: 4px;
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--text);
+        }
+
+        #profile_status.recording { color: var(--fail); }
+
+        p.note { margin: 6px 0 0; font-size: 11.5px; color: var(--muted); }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>Froxel volumetrics</h1>
+
+    <h2>Viewpoints</h2>
+    <div id="views"></div>
+
+    <hr>
+
+    <h2>Sun</h2>
+
+    <div class="row">
+        <button id="sun_into_view">Sun into view</button>
+        <button id="sun_behind">Sun behind</button>
+    </div>
+    <p class="note">
+        Places the sun on the camera's forward axis, or directly opposite it. Media self-shadowing
+        depends on the shadow ray's path through the grid, so swinging the sun through the frustum
+        is the quickest way to exercise it.
+    </p>
+
+    <div class="slider">
+        <span class="name">Azimuth</span>
+        <span class="value" id="sun_azimuth_value">200°</span>
+        <input type="range" id="sun_azimuth" min="0" max="359" step="1" value="200">
+    </div>
+
+    <div class="slider">
+        <span class="name">Elevation</span>
+        <span class="value" id="sun_elevation_value">12°</span>
+        <input type="range" id="sun_elevation" min="1" max="80" step="1" value="12">
+    </div>
+
+    <hr>
+
+    <h2>Camera</h2>
+
+    <div class="slider">
+        <span class="name">Field of view</span>
+        <span class="value" id="fov_value">60°</span>
+        <input type="range" id="fov" min="30" max="110" step="1" value="60">
+    </div>
+    <p class="note">
+        Froxel geometry is angle-dependent — the planar depth curve and the ray it is walked along
+        diverge as cos&nbsp;θ. A wide FOV is where anything that confuses the two shows up, so open
+        this to 110° when judging a change to the grid.
+    </p>
+
+    <hr>
+
+    <h2>Volumetrics</h2>
+
+    <label>
+        <input type="checkbox" id="vol_taa" checked>
+        <span>Volumetric TAA <span class="hint">— off exposes the raw per-frame noise</span></span>
+    </label>
+
+    <label>
+        <input type="checkbox" id="taa" checked>
+        <span>Renderer TAA</span>
+    </label>
+
+    <label>
+        <input type="checkbox" id="auto_exposure">
+        <span>Auto exposure <span class="hint">— off: A/B is meaningless with it on</span></span>
+    </label>
+    <p class="note">
+        Eye adaptation drifts for seconds after any change, so two captures of the same setting can
+        differ by more than the change being judged. It starts off here for that reason; turn it on
+        only to see how something reads in a normally-exposed frame.
+    </p>
+
+    <div class="slider">
+        <span class="name">Froxel far</span>
+        <span class="value" id="froxel_far_value">off</span>
+        <input type="range" id="froxel_far" min="20" max="120" step="5" value="120">
+    </div>
+    <p class="note">
+        Packs the froxel grid into a shorter range than <code>camera.far</code>, so the near field
+        gets more slices and the aerial pass ray-marches the volumes beyond it. At <em>off</em> the
+        grid spans the whole range and the two depth curves coincide.
+    </p>
+
+    <div class="slider">
+        <span class="name">Multiscatter octaves</span>
+        <span class="value" id="ms_octaves_value">6</span>
+        <input type="range" id="ms_octaves" min="1" max="8" step="1" value="6">
+    </div>
+
+    <hr>
+
+    <h2>Profiling</h2>
+
+    <div id="profile_status">idle</div>
+    <p class="note">
+        <strong>T</strong> starts a GPU profile recording; <strong>T</strong> again stops it and
+        downloads the <code>.sgpt</code> capture. Level is <code>WORKLOAD</code> — pass spans, the
+        frame graph, and dispatch/draw counts, which measures around 11 KB a frame on this page.
+        Frames only accumulate while the page is rendering, so a recording taken while paused stays
+        at zero.
+    </p>
+    <p class="note">
+        The browser asks before letting a page save more than one file. If a second capture never
+        appears, that prompt is why — allow it, and the filename is on the console either way.
+    </p>
+
+    <hr>
+
+    <div class="row">
+        <button id="pause">Pause</button>
+        <button id="log_camera">Log camera</button>
+    </div>
+
+    <div id="status"></div>
+    <div id="stats"></div>
+
+    <p class="note">
+        Drag to orbit, wheel to zoom, WASD to move. <em>Log camera</em> writes the current placement
+        to the console in the form the <code>VIEWS</code> table takes.
+    </p>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+
+</body>
+</html>

package/src/shade/playground/volumetrics_froxel/main.d.ts

@@ -0,0 +1,2 @@
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map