@woosh/meep-engine 3.3.0 → 3.5.0

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

@@ -0,0 +1,502 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+import { add_floor } from "./add_floor.js";
+import { grid_position, place_character } from "./place_character.js";
+
+/**
+ * A dancing character under the path tracer — the browser tier for the per-frame BLAS refit.
+ *
+ * Every device-free tier can say the refit is *recorded*: the right dispatches, the right offsets,
+ * the counters cleared. None of them can say the tree that comes out is the shape of the mesh,
+ * because none of them run a shader. This page is where that question gets answered, and it answers
+ * it by putting two readings of the same geometry side by side.
+ *
+ * Rasterization reads the clone's deformed vertices directly. The path tracer reads the clone's
+ * BLAS. If the refit works the two silhouettes are the same silhouette, and toggling between them
+ * changes the lighting and nothing else. If it does not, the traced figure stands in bind pose
+ * while the rasterized one dances — and casts shadows from a body that is not there, which is the
+ * more legible half of the failure.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/` and resolves the one bare
+ * specifier the renderer reaches for.
+ */
+
+/**
+ * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
+ * `test_assets/README.md`.
+ *
+ * A Mixamo character with one skin and a looping dance — which is the whole requirement: joints
+ * that move far enough, fast enough, that a tree fitted to the bind pose is visibly the wrong tree.
+ *
+ * @type {string}
+ */
+const CHARACTER_URL = '/test_assets/Michelle.glb';
+
+/**
+ * How far apart dancers stand, in character heights.
+ *
+ * @type {number}
+ */
+const SPACING = 1.1;
+
+/**
+ * A frame-time readout, kept as a rolling mean so the number is readable rather than jittering.
+ */
+class FrameTimer {
+    #samples = new Float64Array(60);
+    #count = 0;
+    #cursor = 0;
+
+    /**
+     * @param {number} seconds
+     */
+    add(seconds) {
+        this.#samples[this.#cursor] = seconds * 1000;
+        this.#cursor = (this.#cursor + 1) % this.#samples.length;
+        this.#count = Math.min(this.#count + 1, this.#samples.length);
+    }
+
+    reset() {
+        this.#count = 0;
+        this.#cursor = 0;
+    }
+
+    /**
+     * @returns {number} mean frame time in milliseconds, or 0 before there is anything to average
+     */
+    get mean_ms() {
+        if (this.#count === 0) {
+            return 0;
+        }
+
+        let total = 0;
+        for (let i = 0; i < this.#count; i++) {
+            total += this.#samples[i];
+        }
+
+        return total / this.#count;
+    }
+}
+
+/**
+ * Every {@link SkinnedMesh} a bundle's skins deform.
+ *
+ * Off the skins rather than by walking the scene roots: a skin already lists exactly the meshes
+ * that bind to it, which is what `register_skin` uses, so this cannot disagree with what actually
+ * gets deformed.
+ *
+ * @param {SceneBundle} bundle
+ * @returns {SkinnedMesh[]}
+ */
+function skinned_meshes_of(bundle) {
+    const meshes = new Set();
+
+    for (const skin of bundle.skins) {
+        for (const mesh of skin.meshes) {
+            meshes.add(mesh);
+        }
+    }
+
+    return [...meshes];
+}
+
+/**
+ * Load one dancer, place it, and set it going.
+ *
+ * A whole load per dancer rather than one load and N instances: a second dancer needs a second
+ * joint hierarchy to pose, and those are scene nodes. The asset framework caches the bytes, so the
+ * repeat is parse work rather than transfer.
+ *
+ * @param {Scene} scene
+ * @param {GPUSceneContext} scene_context
+ * @param {AssetManager} asset_manager
+ * @param {number} index which dancer this is, used to place it
+ * @param {number} count how many there are in total
+ * @returns {Promise<SkinnedMesh[]>}
+ */
+async function add_dancer(scene, scene_context, asset_manager, index, count) {
+    const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
+
+    const meshes = skinned_meshes_of(bundle);
+
+    if (meshes.length === 0) {
+        throw new Error(`${CHARACTER_URL} has no skinned mesh — nothing here has a BLAS to refit`);
+    }
+
+    // A grid, centred on the origin. The offset goes on a fresh parent above the character's own
+    // roots rather than on the mesh node: a skinned mesh's own transform cancels out of both the
+    // vertex the renderer draws and the box it publishes, so the joints are what has to move. See
+    // `place_character`.
+    const { x, z } = grid_position(index, count, SPACING);
+
+    place_character(scene, bundle, x, z);
+
+    const animations = scene_context.animation_manager;
+
+    for (const skin of bundle.skins) {
+        animations.register_skin(skin);
+    }
+
+    // One clip, looping, at full weight. The pose accumulator sums every *bound* clip whatever its
+    // weight, so binding the T-pose alongside the dance would blend the two rather than leave the
+    // dance alone — only what should play is registered.
+    const clip = bundle.clips.find(candidate => /samba|dance/i.test(candidate.name ?? ''))
+        ?? bundle.clips[0];
+
+    if (clip !== undefined) {
+        const clip_id = animations.register_clip(clip);
+
+        animations.set_playback_weight(clip_id, 1);
+        animations.set_flags(clip_id, AnimationClipFlags.Loop);
+        animations.start(clip_id);
+    }
+
+    return meshes;
+}
+
+/**
+ * The world-space box the renderer itself culls and traces this mesh by.
+ *
+ * Not `mesh.bounding_box`, which is the CPU-side box of the *source* geometry under the mesh
+ * transform — the rest pose, and for a glTF character whose node carries the file's centimetre
+ * scale, a box a couple of centimetres across. Framing a camera on that puts it inside the
+ * character, where a rasterized image and a traced one have no reason to look alike and neither
+ * says anything about the tree.
+ *
+ * The `meshes` table row is the deformed box: the skinning pass's bounds-refresh chain rewrites it
+ * every frame from the vertices it just moved. It is only right once that chain has run, so this
+ * is worth nothing before a few frames have gone by.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {Mesh} mesh
+ * @returns {Promise<{low: Vector3, high: Vector3, radius: number}>}
+ */
+async function world_bounds_of(scene_context, mesh) {
+    const row = scene_context.mesh_row_of(mesh);
+
+    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+
+    const box = record.bounding_box;
+
+    const low = new Vector3(box[0], box[1], box[2]);
+    const high = new Vector3(box[3], box[4], box[5]);
+
+    return {
+        low,
+        high,
+        radius: Math.hypot(high.x - low.x, high.y - low.y, high.z - low.z) * 0.5,
+    };
+}
+
+/**
+ * Stand the prototype up. Called by the page rather than run on import, so that nothing here
+ * touches the DOM until there is one.
+ *
+ * @returns {Promise<void>}
+ */
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const status_element = element('status');
+    const stats_element = element('stats');
+
+    /**
+     * @param {string} text
+     * @param {string} [kind]
+     */
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    const canvas = element('view');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        set_status('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
+        return;
+    }
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    if (!renderer.graphics.device.features.has('subgroups')) {
+        set_status('device has no `subgroups`, which this engine takes as a baseline', 'warn');
+    }
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.01;
+    camera.far = 200;
+    camera.fov = 50 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element can receive key events — body carries tabindex for exactly that.
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // handy from the console
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.controller = controller;
+
+    // The numeric half of what this page checks by eye: `verify()` in the console holds the tree's
+    // root box against the bounds-refresh chain's box over the same deformed vertices. Useful when
+    // the page cannot be looked at — a browser stops calling `requestAnimationFrame` for a page it
+    // is not compositing, so a hidden tab renders no frames to look at in the first place.
+    globalThis.verify = async () => {
+        const { verify_skinned_blas_refit } = await import('./verify_skinned_blas_refit.js');
+
+        return verify_skinned_blas_refit({ renderer, camera, scene, mesh: globalThis.dancers[0] });
+    };
+
+    // The half `verify()` is blind to: whether each leaf's box belongs to the triangle that leaf
+    // names. Run against the character's *source* geometry — skinning deforms the clone's vertex
+    // region and leaves the source's alone, so the tree the builder wrote for it is still the right
+    // answer and is there to compare against.
+    globalThis.verify_leaves = async () => {
+        const { verify_leaf_correspondence } = await import('./verify_skinned_blas_refit.js');
+
+        return verify_leaf_correspondence({ renderer, geometry: globalThis.dancers[0].geometry });
+    };
+
+    const frame_timer = new FrameTimer();
+
+    // Tracing by default — it is the reading of the scene this page exists to check.
+    renderer.feature_path_tracing_enabled = element('path_tracing').checked;
+    renderer.feature_taa_enabled = element('taa').checked;
+
+    element('path_tracing').addEventListener('change', event => {
+        renderer.feature_path_tracing_enabled = event.target.checked;
+
+        // Two temporal filters over one image is nonsense; the tracer accumulates on its own.
+        if (event.target.checked) {
+            element('taa').checked = false;
+            renderer.feature_taa_enabled = false;
+        }
+
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    });
+
+    element('taa').addEventListener('change', event => {
+        renderer.feature_taa_enabled = event.target.checked;
+        renderer.indicate_view_change();
+    });
+
+    let animating = true;
+
+    element('animation').addEventListener('click', () => {
+        animating = !animating;
+
+        element('animation').textContent = animating ? 'Freeze pose' : 'Resume dance';
+
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    });
+
+    let diff_showing = false;
+
+    // Held while the diff captures. The frame loop draws to the same canvas the capture reads back
+    // from, and a frame presented between a render and its `drawImage` leaves the read with an
+    // empty bitmap — a comparison of two blanks, which agrees with itself perfectly.
+    let frame_loop_suspended = false;
+
+    element('diff').addEventListener('click', async () => {
+        const { clear_diff_overlay, diff_traced_against_rasterized } =
+            await import('./diff_traced_against_rasterized.js');
+
+        if (diff_showing) {
+            clear_diff_overlay();
+
+            diff_showing = false;
+
+            set_status('diff cleared', '');
+
+            return;
+        }
+
+        set_status('rendering both ways…');
+
+        try {
+            const result = await diff_traced_against_rasterized({
+                renderer,
+                camera,
+                scene,
+                suspend: held => {
+                    frame_loop_suspended = held;
+                },
+            });
+
+            diff_showing = true;
+
+            set_status(result.verdict, result.verdict.startsWith('edge') ? 'pass' : 'fail');
+        } catch (error) {
+            set_status(error.message, 'fail');
+
+            console.error(error);
+        }
+    });
+
+    element('reset_accumulation').addEventListener('click', () => {
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    });
+
+    const parameters = new URLSearchParams(location.search);
+
+    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
+
+    element('character_count').value = String(count);
+
+    // A Scene has no teardown, so changing the cast reloads the page rather than emptying one in
+    // place.
+    element('respawn').addEventListener('click', () => {
+        const next = new URLSearchParams(location.search);
+
+        next.set('count', element('character_count').value);
+
+        location.search = next.toString();
+    });
+
+    // ---- the scene ------------------------------------------------------------------------
+
+    set_status(`loading ${count} × ${CHARACTER_URL} …`);
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    /** @type {SkinnedMesh[]} */
+    const dancers = [];
+
+    try {
+        const asset_manager = await make_playground_asset_manager();
+
+        for (let i = 0; i < count; i++) {
+            dancers.push(...await add_dancer(scene, scene_context, asset_manager, i, count));
+        }
+    } catch (error) {
+        set_status(
+            `could not load the character (${error.message}). Put it under test_assets/ — `
+            + `see test_assets/README.md.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
+        // a glTF character carries no light of its own
+        scene.lights.add(make_sunlight({ intensity: 6 }));
+    }
+
+    // Frames enough for skinning to run and its bounds-refresh chain to publish a deformed box,
+    // which is the only box worth framing on — see `world_bounds_of`. The camera is parked at the
+    // origin until then, so nothing is worth looking at yet either.
+    for (let i = 0; i < 8; i++) {
+        renderer.render(camera, scene, 1 / 60);
+
+        await renderer.graphics.device.queue.onSubmittedWorkDone();
+    }
+
+    // union over every dancer, so a crowd is framed rather than whoever loaded first
+    let low = null;
+    let high = null;
+
+    for (const dancer of dancers) {
+        const bounds = await world_bounds_of(scene_context, dancer);
+
+        low = low === null ? bounds.low : new Vector3(
+            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
+        );
+
+        high = high === null ? bounds.high : new Vector3(
+            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
+        );
+    }
+
+    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
+
+    globalThis.floor = add_floor(scene, Math.max(span.x, span.z) * 6, low.y);
+
+    const radius = Math.hypot(span.x, span.y, span.z) * 0.5;
+
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
+    );
+
+    controller.movement_speed_scale = radius * 0.2;
+
+    // a metre-scale subject, so the default 0.01 near plane is far too tight to be worth keeping
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    load_default_environment(scene).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    globalThis.dancers = dancers;
+
+    set_status(`loaded — ${count} dancing, ${scene.instances.instances.length} instances`, 'pass');
+
+    renderer.indicate_view_change();
+
+    // ---- frame loop -----------------------------------------------------------------------
+
+    const FRAME_RATE_LIMIT = 60;
+
+    create_frame_loop(time_delta_s => {
+        if (frame_loop_suspended) {
+            // the diff owns the canvas until it has both captures
+            return;
+        }
+
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+
+        // A frozen pose is a still scene, which is the only condition under which the accumulator
+        // converges — so time stops rather than the frame loop stopping, and the camera stays live.
+        renderer.render(camera, scene, animating ? time_delta_s : 0);
+
+        frame_timer.add(time_delta_s);
+
+        const mean = frame_timer.mean_ms;
+
+        stats_element.textContent =
+            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps  ·  `
+            + `${count} dancer${count === 1 ? '' : 's'}`
+            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : '  ·  rasterized'}`;
+    }, FRAME_RATE_LIMIT);
+}

package/src/shade/playground/skinned_blas_refit/place_character.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Stand one loaded character on the floor at `(x, 0, z)`.
+ *
+ * ## Why the mesh node is not the placement point
+ *
+ * It is tempting, and it is what this page used to do: the mesh is the visible thing, so move the
+ * mesh. For a {@link SkinnedMesh} that is a no-op, and the reason is the glTF skinning formula
+ * itself. A skinned vertex lands at
+ *
+ * ```
+ * mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
+ * ```
+ *
+ * — `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the
+ * rasterizer re-applies `mesh.global` afterwards, so the mesh node's own transform **cancels
+ * exactly** and the vertex is at `joint.global × inverse_bind × v`. `compute_skin_world_bounds`
+ * composes the published box the same way and does not read the mesh node either. So a skinned
+ * character is placed by its **joints**, and the only thing that moves them is an ancestor they
+ * actually sit under.
+ *
+ * Michelle is the shape that makes this concrete. Her file is one root carrying the centimetre
+ * scale and the up-axis rotation (+90° about x, the file's Z-up into the renderer's Y-up), with the
+ * mesh node and the joint root as *siblings* beneath it:
+ *
+ * ```
+ * "Character"            R=(0.70711, 0, 0, 0.70711)  S=(0.01, 0.01, 0.01)
+ * ├── "Ch03"             mesh 0, skin 0 — no local transform of its own
+ * └── "mixamorig:Hips"   the joint root
+ * ```
+ *
+ * Nothing under `Ch03` drives a joint, so writing a grid offset there — to either transform —
+ * moves nothing at all.
+ *
+ * ## Why a placement node rather than the character's own root
+ *
+ * `"Character"`'s local transform is the file's, and it is load-bearing twice over: the 0.01 scale
+ * is what makes the inverse-bind matrices agree with the vertex positions, and a `Transform64`
+ * composes as `T · R · S`, so a translation written there is *not* the world offset — it is an
+ * offset the file's own rotation and scale then act on. A fresh parent keeps the two apart: the
+ * grid offset is this node's whole transform, the file's is untouched below it, and the
+ * composition happens where it always happens.
+ *
+ * A node under {@link TransformAuthority.GPU} still follows a CPU-driven parent — the hierarchy
+ * pass composes `global` from the node's own TRS and the parent chain — so the joints the pose
+ * accumulator owns are carried by this without anyone writing to their rows.
+ *
+ * ## Why the local transform
+ *
+ * The same reason the floor is placed that way, and it is worth restating because this page has
+ * now been bitten by it twice. `Node3D.transform_global` is **derived** — its doc comment says so
+ * — and `updateMatrices` recomputes it from the local transform and the parent chain. The GPU is
+ * handed the node's local TRS and composes `node.global` from it, so a placement that only ever
+ * reached `transform_global` is discarded at both ends. See `add_floor` for the version of this
+ * where the two ends disagreed and produced two different pictures; here they agreed on the wrong
+ * answer, which is quieter and took longer to see.
+ *
+ * @param {Scene} scene
+ * @param {SceneBundle} bundle a freshly loaded character — its roots must not be parented yet
+ * @param {number} x
+ * @param {number} z
+ * @returns {Node3D} the placement node, now the parent of every root in `bundle.scenes`
+ */
+export function place_character(scene: Scene, bundle: SceneBundle, x: number, z: number): Node3D;
+/**
+ * Where the `index`-th of `count` characters stands: a square-ish grid centred on the origin, laid
+ * out in rows along +x.
+ *
+ * Centred rather than growing from the origin so that `?count=N` frames the same way for every N —
+ * the camera is aimed at the union of the cast, and a grid that walks away from the origin as it
+ * grows pushes that union off with it.
+ *
+ * @param {number} index
+ * @param {number} count
+ * @param {number} spacing distance between neighbours
+ * @returns {{x: number, z: number}}
+ */
+export function grid_position(index: number, count: number, spacing: number): {
+    x: number;
+    z: number;
+};
+import { Node3D } from "../../renderer/scene/Node3D.js";
+//# sourceMappingURL=place_character.d.ts.map

package/src/shade/playground/skinned_blas_refit/place_character.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place_character.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/place_character.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,sEAJW,MAAM,KACN,MAAM,GACJ,MAAM,CA+BlB;AAED;;;;;;;;;;;;GAYG;AACH,qCALW,MAAM,SACN,MAAM,WACN,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAUlC;uBApHsB,gCAAgC"}