@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,399 @@
+import { Color } from "../../../core/color/Color.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+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 { VGEO_CUT_STAT } from "../../renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
+import { VGeoFeedbackLoop } from "../../renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VirtualGeometry } from "../../renderer/geometry/virtual/runtime/VirtualGeometry.js";
+import {
+    VGeoContainerReader
+} from "../../renderer/geometry/virtual/format/read/VGeoContainerReader.js";
+import {
+    VGeoReadOptions
+} from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
+import {
+    VGeoResidencyManager
+} from "../../renderer/geometry/virtual/residency/VGeoResidencyManager.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { vgeo_sample_source } from "../vgeo_viewer/sample_asset.js";
+
+/**
+ * A `.vgeo` container drawn **through the meshlet pipeline**, by a cut selected on the GPU.
+ *
+ * This is the other half of what `playground/vgeo_viewer/` proves, and the two are worth keeping
+ * apart. The viewer draws a CPU cut through Shade's direct geometry path: it proves the DAG, the
+ * format and the clamp, and by construction it proves nothing about the engine. This page draws
+ * nothing itself. It puts an ordinary mesh row in an ordinary `Scene` with an ordinary material,
+ * and every triangle on screen arrives because the compute cut appended `MESHLET_DEFINITION_STRUCT`
+ * records into the same collection a static mesh's meshlets go into — through the HZB meshlet
+ * filter, the material bucket, the indirect draw and the G-buffer, none of which know that virtual
+ * geometry exists.
+ *
+ * So the interesting readings here are the ones about the engine rather than about the DAG:
+ *
+ * - **drawn triangles track τ and the resolution, not the source.** Design §1's whole claim. Move
+ *   the slider and watch the cut, not the asset.
+ * - **clamped falls to zero as pages arrive.** The cut starts against a container holding only its
+ *   root page, so the first frames are a coarse but watertight surface, and the wants the cut emits
+ *   are what fetch the rest.
+ * - **nothing is drawn twice.** `drawn` against the triangle count the rasterizer reports.
+ *
+ * `__state()` is what a headless session asserts on; everything the panel shows comes from it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const element = id => document.getElementById(id);
+
+/**
+ * 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 = "vgeo/frame start";
+
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @param {VGeoPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.begin(frame);
+    }
+}
+
+/**
+ * Schedules the readback and closes the frame, after everything that could have cut has cut.
+ */
+class VGeoFrameEnd extends RenderExtension {
+    name = "vgeo/frame end";
+
+    phase = FramePhase.BeforePresent;
+
+    /**
+     * @param {VGeoPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.finish(frame);
+    }
+}
+
+class VGeoPlayground {
+    /**
+     * @type {VGeoContainerReader}
+     */
+    reader;
+
+    /**
+     * @type {GPUVirtualGeometryRuntime}
+     */
+    runtime;
+
+    /**
+     * @type {VGeoFeedbackLoop}
+     */
+    feedback;
+
+    /**
+     * @type {VGeoResidencyManager}
+     */
+    residency;
+
+    /**
+     * @type {number}
+     */
+    frames = 0;
+
+    /**
+     * @type {number}
+     */
+    canvas_height = 600;
+
+    /**
+     * @type {number}
+     */
+    fov_y = 50 * DEG_TO_RAD;
+
+    /**
+     * @param {FrameContext} frame
+     */
+    begin(frame) {
+        this.runtime.begin_frame(frame.graph, {
+            screen_height: this.canvas_height,
+            fov_y: this.fov_y,
+        });
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    finish(frame) {
+        // the RAM tier's clock moves inside this: a host that drives the loop gets a bounded
+        // second tier without having to know it had one to wind
+        this.feedback.read(frame.graph);
+
+        this.runtime.end_frame();
+
+        this.frames++;
+    }
+
+    /**
+     * Everything a headless session needs, and everything the panel shows.
+     *
+     * @returns {object}
+     */
+    state() {
+        const stats = this.feedback.stats;
+        const pool = this.runtime.pool;
+
+        return {
+            frames: this.frames,
+            tau: this.runtime.tau,
+            feedback_reads: this.feedback.read_count,
+            feedback_skipped: this.feedback.skipped_frames,
+            cut: {
+                drawn: stats[VGEO_CUT_STAT.DRAWN],
+                clamped: stats[VGEO_CUT_STAT.CLAMPED],
+                clamped_on_activation: stats[VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION],
+                pages: stats[VGEO_CUT_STAT.PAGES],
+                items: stats[VGEO_CUT_STAT.ITEMS],
+                clusters_tested: stats[VGEO_CUT_STAT.CLUSTERS_TESTED],
+                culled_frustum: stats[VGEO_CUT_STAT.CULLED_FRUSTUM],
+                culled_lod: stats[VGEO_CUT_STAT.CULLED_LOD],
+                meshlets_dropped: stats[VGEO_CUT_STAT.MESHLETS_DROPPED],
+                wants_dropped: stats[VGEO_CUT_STAT.WANTS_DROPPED],
+                queue_dropped: stats[VGEO_CUT_STAT.QUEUE_DROPPED],
+                instances_dropped: stats[VGEO_CUT_STAT.INSTANCES_DROPPED],
+                wavefronts: stats[VGEO_CUT_STAT.WAVEFRONTS],
+                queue_remaining: stats[VGEO_CUT_STAT.QUEUE_REMAINING],
+            },
+            wants: this.feedback.last_want_count,
+            touches: this.feedback.last_touch_count,
+            vram: {
+                pages: pool.resident_page_count,
+                bytes: pool.resident_bytes,
+                evicted: pool.evicted_page_count,
+                refused: pool.refused_install_count,
+            },
+            ram: {
+                pages: this.reader.resident_page_count,
+                bytes: this.reader.resident_bytes,
+                total_pages: this.reader.header.total_pages,
+            },
+        };
+    }
+}
+
+async function start() {
+    const canvas = element('view');
+
+    const status = text => {
+        element('status').textContent = text;
+    };
+
+    const renderer = new Renderer();
+
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+
+    renderer.feature_taa_enabled = false;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    renderer.resize(canvas.width, canvas.height);
+
+    status('building a container in the page…');
+
+    /*
+     One number for the asset and for the tier that holds it. A page size is a bound the container
+     states (FORMAT §11.14) and the pool holds pages at exactly one, so a mismatch here is a refusal
+     at `register` rather than something that limps.
+     */
+    const page_size = 64 * 1024;
+
+    const { source, build_ms } = vgeo_sample_source(128, 48, page_size);
+
+    /*
+     Frame verification on, because this reader is a runtime's rather than a tool's — format §10
+     leaves it off by default precisely because a tool reading a file it just built is not
+     defending against a network, and a runtime is.
+     */
+    const options = new VGeoReadOptions();
+
+    options.verify_frames = true;
+
+    const reader = await VGeoContainerReader.open(source, options);
+
+    const page = new VGeoPlayground();
+
+    page.reader = reader;
+    page.canvas_height = canvas.height;
+
+    page.residency = new VGeoResidencyManager();
+    page.residency.register(reader);
+
+    const scene = new Scene();
+
+    // the sun stands at an entity, and so does the torus, so the scene names a dataset
+    scene.dataset = new EntityComponentDataset();
+
+    // a light stands at an entity of the dataset now, like everything else the scene holds
+    place_light(scene, make_sunlight());
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.02;
+    camera.far = 200;
+    camera.fov = page.fov_y;
+    camera.aspect = canvas.width / canvas.height;
+
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    controller.look(new Vector3(0, 1.6, 3.6), new Vector3(0, 0, 0));
+
+    // one frame to let the renderer build its scene context, which is what owns the geometry manager
+    renderer.render(camera, scene, 1 / 60);
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const runtime = scene_context.enable_virtual_geometry({ page_size });
+
+    page.runtime = runtime;
+
+    /*
+     Only the root page is resident. Everything else arrives because the cut asked for it, which is
+     the loop this page exists to show — and it means the first frames draw a coarse, watertight
+     surface rather than nothing at all.
+     */
+    const geometry_row = runtime.pool.register(reader);
+
+    const geometry = new VirtualGeometry(reader);
+
+    geometry.vg_row = geometry_row;
+
+    const material = new StandardShadeMaterial();
+
+    material.diffuse_color.copy(new Color(0.72, 0.74, 0.78));
+    material.roughness_factor = 0.55;
+    material.metallic_factor = 0;
+
+    place_primitive(
+        scene_context, geometry, material, new Transform64(), { name: 'virtual torus' }
+    );
+
+    page.feedback = new VGeoFeedbackLoop({ runtime, residency: page.residency });
+
+    /*
+     The loop's only teardown caller anywhere, and worth having for the same reason M12's clock was:
+     `abort()` existed and nothing pulled it, so the one thing the `AbortSignal` was added for was
+     never exercised outside a spec. Nothing in the engine constructs a feedback loop yet — a scene
+     context gives you a runtime and a pool, and the host wires the loop — so this page is the whole
+     population of hosts, and it is what a real one should do on the way out.
+     */
+    globalThis.addEventListener('pagehide', () => page.feedback.destroy());
+
+    renderer.add_extension(new VGeoFrameStart(page));
+    renderer.add_extension(new VGeoFrameEnd(page));
+
+    element('tau').addEventListener('input', event => {
+        runtime.tau = Number(event.target.value);
+
+        element('tau-value').textContent = runtime.tau.toFixed(2);
+    });
+
+    globalThis.__state = () => page.state();
+    globalThis.__page = page;
+
+    status(`container built in ${build_ms.toFixed(0)} ms · ${reader.header.total_pages} pages`);
+
+    let stopped = false;
+    let last_time;
+
+    function paint() {
+        const state = page.state();
+
+        element('cut').innerHTML = [
+            ['drawn clusters', state.cut.drawn],
+            ['clamped', state.cut.clamped],
+            ['pages visited', state.cut.pages],
+            ['clusters tested', state.cut.clusters_tested],
+            ['subtrees culled', state.cut.culled_frustum + state.cut.culled_lod],
+            ['wants', state.wants],
+        ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+            .join('');
+
+        const dropped = state.cut.meshlets_dropped + state.cut.queue_dropped
+            + state.cut.instances_dropped;
+
+        element('residency').innerHTML = [
+            ['VRAM pages', `${state.vram.pages}`],
+            ['VRAM bytes', `${(state.vram.bytes / 1024).toFixed(0)} KB`],
+            ['RAM pages', `${state.ram.pages} / ${state.ram.total_pages}`],
+            ['evicted', state.vram.evicted],
+            ['dropped', `<span class="${dropped > 0 ? 'bad' : 'good'}">${dropped}</span>`],
+        ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+            .join('');
+    }
+
+    function tick(time) {
+        if (stopped) {
+            return;
+        }
+
+        const dt = last_time === undefined ? 1 / 60 : Math.min((time - last_time) / 1000, 0.05);
+
+        last_time = time;
+
+        try {
+            controller.update(dt);
+
+            renderer.render(camera, scene, dt);
+        } catch (error) {
+            stopped = true;
+
+            status(error.message ?? String(error));
+            element('status').classList.add('error');
+
+            console.error(error);
+
+            return;
+        }
+
+        paint();
+
+        requestAnimationFrame(tick);
+    }
+
+    requestAnimationFrame(tick);
+}
+
+start().catch(error => {
+    element('status').textContent = error.message ?? String(error);
+    element('status').classList.add('error');
+
+    globalThis.__state = () => ({ error: error.message ?? String(error) });
+
+    console.error(error);
+});

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

@@ -32,6 +32,8 @@ import {
     vgeo_install_all_pages
 } from "../../renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
 import { Renderer } from "../../renderer/Renderer.js";
 import { DynamicMesh } from "../../renderer/scene/DynamicMesh.js";
 import { DynamicMeshBatch } from "../../renderer/scene/DynamicMeshBatch.js";
@@ -435,6 +437,9 @@ class VGeoViewer {
         this.camera = new PerspectiveCamera();
         this.scene = new Scene();
 
+        // the sun stands at an entity, so the scene names a dataset for it
+        this.scene.dataset = new EntityComponentDataset();
+
         this.#dynamic.opaque = true;
     }
 
@@ -501,7 +506,7 @@ class VGeoViewer {
         this.renderer.feature_lpv_enabled = false;
         this.renderer.pixel_ratio = 1;
 
-        this.scene.lights.add(make_sunlight({ intensity: 3 }));
+        place_light(this.scene, make_sunlight({ intensity: 3 }));
 
         this.camera.near = 0.05;
         this.camera.far = 500;
@@ -716,7 +721,6 @@ class VGeoViewer {
         }
 
         this.#mesh = DynamicMesh.from(this.#cut_geometry.geometry);
-        this.#mesh.updateMatrices();
 
         this.#batch.add(this.#mesh);
 

package/src/shade/playground/vgeo_viewer/sample_asset.js

@@ -99,7 +99,7 @@ function torus(major, minor) {
  * @param {number} [page_size] target decoded bytes per page
  * @returns {{source: VGeoByteSource, build_ms: number}}
  */
-export function vgeo_sample_source(major = 128, minor = 48, page_size = 8 * 1024) {
+export function vgeo_sample_source(major = 128, minor = 48, page_size = 16 * 1024) {
     const options = new VGeoBuildOptions();
 
     options.nominal_page_size = page_size;

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":"AAmaA,uCAsfC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA2aA,uCA4fC"}