@woosh/meep-engine 3.33.0 → 3.35.0

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

@@ -5,8 +5,6 @@ import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDatas
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
 import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
-import { FramePhase } from "../../renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
 import { meshlet_geometry_from_bytes } from "../../renderer/geometry/meshlet_geometry_transfer.js";
 import {
     vgeo_byte_source_over_url
@@ -173,6 +171,25 @@ const ROWS_LAST_KNOWN_GOOD = 2_200_000;
  */
 const HEAD_PREFIX_BYTES = 8 * 1024;
 
+/**
+ * How far the camera's far plane may reach, in multiples of the distance to the orbit's target.
+ *
+ * The far plane clips nothing — the projection is infinite reverse-Z — but the renderer spreads what
+ * it slices by depth over it: the sun's three shadow cascades (`DirectionalLightShadowmap` takes
+ * `camera.far` as its shadow distance), the light clusters, OIT's depth curve and the volumetric
+ * froxels. It was `distance × 2000` and **no shadow reached the screen**: framed on the first
+ * district that is 1,580 km, so the nearest cascade spanned 0–214 km.
+ *
+ * The far side of the world's bounding sphere is the other bound, and here it is not the one that
+ * binds: the world box is 26 by 28 km because `map_vista` is, a backdrop around an island whose
+ * ground is three kilometres across, so the sphere reaches twenty kilometres from anywhere on it.
+ * The same figure `vgeo_scene` settled on for the same shape of scene — at twenty, the nearest
+ * cascade reaches about two and a half times the distance to the target.
+ *
+ * @type {number}
+ */
+const FAR_PER_DISTANCE = 20;
+
 /**
  * @type {Record<string, ShadeDrawSide>}
  */
@@ -183,54 +200,6 @@ const DRAW_SIDES = Object.freeze({
 });
 
 
-/**
- * Opens the VG frame before anything records a rasterization pass, because the seam inside those
- * passes writes into the feedback buffer this creates.
- */
-class VGeoFrameStart extends RenderExtension {
-    name = "caldera/vgeo frame start";
-
-    phase = FramePhase.FrameStart;
-
-    /**
-     * @param {CalderaPlayground} page
-     */
-    constructor(page) {
-        super();
-
-        this.page = page;
-    }
-
-    record(frame) {
-        this.page.runtime.begin_frame({ graph: frame.graph });
-    }
-}
-
-
-/**
- * Schedules the readback and closes the frame, after everything that could have cut has cut.
- */
-class VGeoFrameEnd extends RenderExtension {
-    name = "caldera/vgeo frame end";
-
-    phase = FramePhase.BeforePresent;
-
-    /**
-     * @param {CalderaPlayground} page
-     */
-    constructor(page) {
-        super();
-
-        this.page = page;
-    }
-
-    record(frame) {
-        this.page.feedback.read(frame.graph);
-        this.page.runtime.end_frame();
-    }
-}
-
-
 class CalderaPlayground {
 
     /** @type {Renderer} */
@@ -366,9 +335,15 @@ class CalderaPlayground {
     /** @type {GPUVirtualGeometryFeedback|undefined} */
     feedback;
 
-    /** @type {number} half the diagonal of the whole map, which sets the far plane */
+    /** @type {number} half the diagonal of the whole map, which bounds the far plane */
     world_radius = 1000;
 
+    /**
+     * The centre of the whole map's box.
+     * @type {Vector3}
+     */
+    world_center = new Vector3();
+
     /**
      * What the virtual-geometry tables were sized to, kept so a session can read back the numbers
      * the page chose rather than infer them.
@@ -397,8 +372,8 @@ class CalderaPlayground {
      *
      * The near and far planes are the part that matters here: Caldera is three kilometres across and
      * a viewer stands centimetres from a wall inside it, so a fixed pair of planes either z-fights
-     * everything close or clips everything far. Deriving them from the distance is what lets one
-     * page do both.
+     * everything close or spreads the sun's shadow over kilometres. Deriving them from the distance
+     * is what lets one page do both: the near plane here, the far plane in {@link fit_far}.
      *
      * @param {ArrayLike<number>} eye
      * @param {ArrayLike<number>} target
@@ -410,7 +385,6 @@ class CalderaPlayground {
         const distance = Math.max(Vector3.distance(from, to), 1e-3);
 
         this.camera.near = distance * 0.002;
-        this.camera.far = Math.max(distance * 2000, this.world_radius * 4);
 
         this.controller.distanceLimits.min = distance * 0.01;
         this.controller.distanceLimits.max = Math.max(distance * 2000, this.world_radius * 4);
@@ -418,11 +392,32 @@ class CalderaPlayground {
 
         this.controller.look(from, to);
 
+        this.fit_far();
+
         // the pixels the camera is about to cover have no correspondence in a TAA history written
         // from where it was standing
         this.renderer.indicate_view_change();
     }
 
+    /**
+     * Set the far plane from where the camera stands now: the far side of the world's bounding
+     * sphere, and no further than {@link FAR_PER_DISTANCE} times the distance to the target.
+     *
+     * Every frame rather than in {@link look}, because the orbit moves the eye between them.
+     */
+    fit_far() {
+        const eye = this.camera.transform;
+        const center = this.world_center;
+
+        const beyond_world = Math.hypot(
+            eye.translation_x - center.x,
+            eye.translation_y - center.y,
+            eye.translation_z - center.z
+        ) + this.world_radius;
+
+        this.camera.far = Math.min(beyond_world, this.controller.distance * FAR_PER_DISTANCE);
+    }
+
     /**
      * @param {string} text
      * @param {boolean} [error]
@@ -962,7 +957,9 @@ class CalderaPlayground {
                 instances_dropped: stats[VGEO_CUT_STAT.INSTANCES_DROPPED],
                 queue_dropped: stats[VGEO_CUT_STAT.QUEUE_DROPPED],
                 queue_remaining: stats[VGEO_CUT_STAT.QUEUE_REMAINING],
-                max_iterations: this.runtime.max_iterations,
+                // the main view's own bound: every view raises its own from its own readings
+                max_iterations: this.runtime.frame_view?.iterations_under(this.runtime)
+                    ?? this.runtime.max_iterations,
             },
             vram: pool === undefined ? undefined : {
                 pages: pool.resident_page_count,
@@ -1156,6 +1153,7 @@ async function start() {
     const box = manifest.world_bounds;
 
     page.world_radius = 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+    page.world_center.set(0.5 * (box[0] + box[3]), 0.5 * (box[1] + box[4]), 0.5 * (box[2] + box[5]));
 
     const renderer = new Renderer();
 
@@ -1223,6 +1221,25 @@ async function start() {
 
     page.scene_context = scene_context;
 
+    /*
+     The renderer's teardown reaches the scene context, which releases the virtual geometry it
+     built, and the device takes whatever the renderer does not release. Declared here rather than
+     beside the frame loop so the handler can stop the loop from the moment it exists.
+    */
+    let stopped = false;
+
+    globalThis.addEventListener('pagehide', () => {
+        stopped = true;
+
+        renderer.destroy();
+        renderer.graphics.device.destroy();
+    });
+    globalThis.addEventListener('pageshow', event => {
+        if (event.persisted) {
+            location.reload();
+        }
+    });
+
     if (has_virtual) {
         enable_virtual_geometry(page, manifest, parameters);
     }
@@ -1289,7 +1306,6 @@ async function start() {
     globalThis.__state = () => page.state();
     globalThis.__look = (eye, target) => page.look(eye, target);
 
-    let stopped = false;
     let last_time;
 
     const tick = time => {
@@ -1309,6 +1325,7 @@ async function start() {
 
         try {
             page.controller.update(dt);
+            page.fit_far();
 
             renderer.render(camera, scene, dt);
         } catch (error) {
@@ -1449,10 +1466,6 @@ function enable_virtual_geometry(page, manifest, parameters) {
     page.residency = page.scene_context.virtual_geometry_residency;
     page.feedback = page.scene_context.virtual_geometry_feedback;
 
-    globalThis.addEventListener('pagehide', () => page.feedback.destroy());
-
-    page.renderer.add_extension(new VGeoFrameStart(page));
-    page.renderer.add_extension(new VGeoFrameEnd(page));
 
     const tau = element('tau');
 

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

@@ -115,8 +115,13 @@ Two things to know before editing one:
 - **The flame does not darken what is behind it.** Additive emitters write the emission accumulator,
   which the resolve adds outside the coverage normalization — so the fire lights the frame instead of
   taking coverage from it. The smoke, which is matter, does cover.
-- **The soot flakes cross in front of the flame and are lit by nothing**, and still read, because
-  they are dark against something bright. That is the cheapest depth cue in the set.
+- **The smoke is lit, not painted.** Its gradient is an albedo — tar-brown near the fire, paling to
+  grey as it thins — and `EMITTER_FLAG.LIGHTING` does the rest: the firelight warms its underside,
+  the moon greys the column above, both shadowed, both read out of the froxel volume that lights
+  the fog. Orbit until the moon is behind it: the thin edges pass moonlight through (back-face
+  transmission) and the dense core holds it back.
+- **The soot flakes cross in front of the flame** and read because they are near-black — lit like the
+  smoke, with an albedo to match. That is the cheapest depth cue in the set.
 - **Orbit around it.** The particles and the transparent surfaces composite against each other with
   no order between them — both write extinction into one voxel volume and both resolve out of the
   same accumulators. Switch the renderer to MBOIT and the particles vanish while everything else
@@ -140,11 +145,8 @@ ask for it.
 
 ## What it deliberately does not do
 
-- **No emitter opts into `EMITTER_FLAG.LIGHTING`.** The shipped hook is
-  `chunk_particle_lighting_unlit`, a pass-through, so the flag would cost a bit in a record and
-  change no pixel. The smoke and the soot are *painted* lit instead: their gradients carry the fire's
-  warmth low down and the moon's blue higher up, over the particle's own age. When a lit hook lands,
-  those gradients are the thing to reconsider.
+- **The flame and the embers are not lit.** They are additive and they are the light; the firelight
+  is a point light at the fire, because a particle does not light anything.
 - **No emitter opts into culling.** One fire, always on screen; the frustum test in the tick pass
   would never be taken. The measured bounds are still published every frame and still read by the
   occupancy pass.
@@ -201,3 +203,7 @@ The four programs are around 620 VM instructions each in UPDATE, most of which i
 is twelve of them for a divergence-free field: over a metre of flame nobody can tell, and the four
 effects share the register budget above — the editor's toolbar reports both numbers after every
 recompile, which is the cheapest way to notice an edit that has gone past them.
+
+Lighting the smoke and the soot costs the particle draw +200..275 us at 1898x926 and +0.8..1.2 ms at
+3818x2006 on an RTX 4090, over ~450 us and ~2.1 ms unlit; `renderer/particles/DESIGN.md` has how that was
+measured and where it goes.

package/src/shade/playground/particle_ecs/bonfire_effects.d.ts

@@ -115,11 +115,11 @@ export function bonfire_sprite_urls(textures?: object): {
  *
  * ## Lighting
  *
- * None of these opt into `EMITTER_FLAG.LIGHTING`, and that is not an oversight: the shipped lighting
- * hook is `chunk_particle_lighting_unlit`, a pass-through, so the flag would cost a bit in a record
- * and change no pixel. The smoke and the soot are *painted* lit instead — their gradients carry the
- * fire's warmth low down where the fire would light them and the moon's blue higher up, over the
- * particle's own age. When the lit hook lands the gradients are what to reconsider.
+ * The smoke and the soot are lit (`EMITTER_FLAG.LIGHTING`), so their gradients are albedo: the smoke
+ * tar-brown at birth paling to grey as it thins, the soot near-black throughout — the alpha ramps are
+ * the same as when the gradients were painted lit, emitted colour carrying the fire's warmth low down
+ * and the moon's blue higher up. The fire and the moon now do that. The flame and the embers are
+ * additive and unlit: they are the light.
  */
 /**
  * The four saved documents, by the key the page knows them by.

package/src/shade/playground/particle_ecs/bonfire_effects.js

@@ -62,11 +62,11 @@ import soot_json from "./effects/soot.json";
  *
  * ## Lighting
  *
- * None of these opt into `EMITTER_FLAG.LIGHTING`, and that is not an oversight: the shipped lighting
- * hook is `chunk_particle_lighting_unlit`, a pass-through, so the flag would cost a bit in a record
- * and change no pixel. The smoke and the soot are *painted* lit instead — their gradients carry the
- * fire's warmth low down where the fire would light them and the moon's blue higher up, over the
- * particle's own age. When the lit hook lands the gradients are what to reconsider.
+ * The smoke and the soot are lit (`EMITTER_FLAG.LIGHTING`), so their gradients are albedo: the smoke
+ * tar-brown at birth paling to grey as it thins, the soot near-black throughout — the alpha ramps are
+ * the same as when the gradients were painted lit, emitted colour carrying the fire's warmth low down
+ * and the moon's blue higher up. The fire and the moon now do that. The flame and the embers are
+ * additive and unlit: they are the light.
  */
 
 /**