@woosh/meep-engine 3.11.1 → 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

@@ -30,6 +30,36 @@ Those fixes are in the permanent path now and there is nothing left to A/B. What
 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
@@ -50,6 +80,14 @@ confident wrong answer during the work above:
   *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.
@@ -57,6 +95,68 @@ and −1.071 at 110°: same fix, and that 7× is the `1/cos θ` scaling it predi
 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
@@ -80,7 +180,10 @@ 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. *Log camera* writes the
+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

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

@@ -117,12 +117,14 @@
         #status.fail { color: var(--fail); }
         #status.warn { color: var(--warn); }
 
-        #stats {
+        #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>
@@ -220,6 +222,23 @@
 
     <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>

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA+TA,uCA2SC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA8ZA,uCAsfC"}