@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/scene/optimization/scene_optimize.js

@@ -1,230 +1,266 @@
-import { assert } from "../../../../core/assert.js";
-import { geometry_build_from_meshlet_geometry } from "../../geometry/geometry_build_from_meshlet_geometry.js";
-import { geometry_deduplicate_vertices } from "../../geometry/geometry_deduplicate_vertices.js";
-import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
-import { Mesh } from "../Mesh.js";
-import { deduplicate_geometries } from "./deduplicate_geometries.js";
-import { geometry_deduplicate } from "./geometry/geometry_deduplicate.js";
-import { optimize_texture_set } from "./optimize_texture_set.js";
-
-/**
- *
- * @param {Set<MeshletGeometry>} geometries
- * @param {Mesh[]} instances
- */
-function optimize_geometry_set(geometries, instances) {
-    const removed = deduplicate_geometries(Array.from(geometries));
-
-    if (removed.length > 0) {
-        console.log(`scene_optimize: removed ${removed.length} exact-duplicate geometries`);
-
-        const replace_map = new Map();
-        for (const [victim, master] of removed) {
-            replace_map.set(victim, master);
-        }
-
-        for (const instance of instances) {
-            if (replace_map.has(instance.geometry)) {
-                instance.geometry = replace_map.get(instance.geometry);
-                instance.needsUpdate = true;
-            }
-        }
-    }
-}
-
-/**
- * Detect equivalent triangle subsets across the surviving geometries (after
- * exact dedup) and replace meshes with shared canonical pieces.
- *
- *  - Single-piece replacement with identity transform: just swap geometry.
- *  - Single-piece with non-identity transform: swap geometry, premultiply
- *    `transform_local` by the piece's transform.
- *  - Multi-piece replacement: remove the original mesh and add one new
- *    mesh per piece, each with transform_local baked from the original's
- *    transform_global so the result is parent-independent.
- *
- * @param {Scene} scene
- */
-function optimize_geometry_pieces(scene) {
-    const instances = scene.instances.instances;
-
-    /** @type {Map<MeshletGeometry, Geometry>} */
-    const mg_to_geom = new Map();
-    /** @type {Map<Geometry, MeshletGeometry>} canonical (input-derived) Geometry → its source MG */
-    const geom_to_source_mg = new Map();
-
-    for (const instance of instances) {
-        if (mg_to_geom.has(instance.geometry)) {
-            continue;
-        }
-
-        let geom = geometry_build_from_meshlet_geometry(instance.geometry);
-
-        // undo meshlet damage
-        geom = geometry_deduplicate_vertices(geom);
-
-        mg_to_geom.set(instance.geometry, geom);
-        geom_to_source_mg.set(geom, instance.geometry);
-    }
-
-    const geometries = Array.from(mg_to_geom.values());
-    const triangles_before = sum_unique_triangles(instances);
-
-    if (geometries.length < 2) {
-        console.log(`scene_optimize: only ${geometries.length} unique geometries, skipping piece-level dedup`);
-        return;
-    }
-
-    const replacement_map = geometry_deduplicate({
-        geometries,
-        min_primitives: 64
-    });
-
-    /** @type {Map<Geometry, MeshletGeometry>} memoised MGs for newly-built piece Geometries */
-    const built_mg_for_geom = new Map();
-
-    const get_mg_for_geom = (geom) => {
-        const source = geom_to_source_mg.get(geom);
-        if (source !== undefined) return source;
-        let mg = built_mg_for_geom.get(geom);
-        if (mg === undefined) {
-            mg = meshlet_geometry_build_from_geometry(geom);
-            built_mg_for_geom.set(geom, mg);
-        }
-        return mg;
-    };
-
-    let instances_swapped = 0;
-    let instances_removed = 0;
-    let instances_added = 0;
-
-    // Snapshot since we mutate scene.instances mid-loop
-    const original_instances = instances.slice();
-
-    for (const instance of original_instances) {
-        const source_geom = mg_to_geom.get(instance.geometry);
-        const entries = replacement_map.get(source_geom);
-        if (entries === undefined || entries.length === 0) continue;
-
-        if (entries.length === 1) {
-            const [transform, geom] = entries[0];
-            const new_mg = get_mg_for_geom(geom);
-
-            if (new_mg !== instance.geometry) {
-                if (!transform.isIdentity()) {
-                    instance.transform_local.multiply(transform);
-                }
-                instance.geometry = new_mg;
-                instance.needsUpdate = true;
-                instance.updateMatrices();
-                instances_swapped++;
-            }
-            continue;
-        }
-
-        // Multi-piece: replace this mesh with N new meshes
-        scene.instances.remove(instance);
-        instances_removed++;
-
-        // Re-parent any Node3D children of the replaced mesh onto the scene root
-        // (parent = null resolves to the scene row on the GPU side), baking the
-        // removed parent's world transform into each child's transform_local so
-        // the child's world transform is preserved. The children themselves stay
-        // in the instance batch — Scene.add registered them individually.
-        const orphans = instance.children;
-        for (const child of orphans) {
-            assert.equal(child.parent, instance, 'child.parent !== replaced mesh — unsupported hierarchy shape');
-
-            // child world = parent global ⊗ child local — same composition updateMatrices uses
-            child.transform_local.multiplyTransforms(instance.transform_global, child.transform_local);
-            child.parent = null;
-            child.updateMatrices();
-        }
-        orphans.length = 0;
-
-        for (const [transform, geom] of entries) {
-            const new_mesh = new Mesh();
-            new_mesh.material = instance.material;
-            new_mesh.geometry = get_mg_for_geom(geom);
-            new_mesh.name = instance.name;
-
-            // Bake the original world transform into this piece's transform_local — the new
-            // mesh has no parent, so transform_global == transform_local after updateMatrices.
-            new_mesh.transform_local.multiplyTransforms(instance.transform_global, transform);
-            new_mesh.updateMatrices();
-
-            scene.instances.add(new_mesh);
-            instances_added++;
-        }
-    }
-
-    const triangles_after = sum_unique_triangles(scene.instances.instances);
-    const unique_geoms_after = count_unique_geometries(scene.instances.instances);
-
-    console.log(
-        `scene_optimize: piece-level dedup — `
-        + `${instances_swapped} swapped, ${instances_removed} removed, ${instances_added} added; `
-        + `unique geometries ${geometries.length} → ${unique_geoms_after}; `
-        + `unique-geometry triangles ${triangles_before} → ${triangles_after} `
-        + `(saved ${triangles_before - triangles_after})`
-    );
-
-    // TODO rebuild meshlet BLASs, using high quality settings
-}
-
-function count_unique_geometries(instances) {
-    const set = new Set();
-    for (const i of instances) set.add(i.geometry);
-    return set.size;
-}
-
-/**
- *
- * @param {Mesh[]} instances
- * @returns {number}
- */
-function sum_unique_triangles(instances) {
-    const seen = new Set();
-    let total = 0;
-    for (const i of instances) {
-        if (seen.has(i.geometry)) continue;
-        seen.add(i.geometry);
-        total += i.geometry.primitive_count;
-    }
-    return total;
-}
-
-/**
- *
- * @param {Scene} scene
- */
-export function scene_optimize(scene) {
-
-    // extract materials
-    const materials = new Set();
-    const geometries = new Set();
-
-    for (const instance of scene.instances.instances) {
-        materials.add(instance.material);
-        geometries.add(instance.geometry);
-    }
-
-    optimize_geometry_set(geometries, scene.instances.instances);
-
-    optimize_geometry_pieces(scene);
-
-    /**
-     *
-     * @type {Set<ShadeTexture>}
-     */
-    const textures = new Set();
-
-    for (const material of materials) {
-        for (const t of material.textures) {
-            textures.add(t);
-        }
-    }
-
-    optimize_texture_set(textures);
-
-}
+import { assert } from "../../../../core/assert.js";
+import { geometry_build_from_meshlet_geometry } from "../../geometry/geometry_build_from_meshlet_geometry.js";
+import { geometry_deduplicate_vertices } from "../../geometry/geometry_deduplicate_vertices.js";
+import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
+import { SceneNode } from "../../loader/SceneNode.js";
+import { deduplicate_geometries } from "./deduplicate_geometries.js";
+import { geometry_deduplicate } from "./geometry/geometry_deduplicate.js";
+import { optimize_texture_set } from "./optimize_texture_set.js";
+
+/**
+ * @typedef {import("../../loader/SceneBundle.js").SceneBundle} SceneBundle
+ * @typedef {import("../../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../../geometry/Geometry.js").Geometry} Geometry
+ */
+
+/**
+ * The nodes of a bundle that draw.
+ *
+ * @param {SceneBundle} bundle
+ * @returns {SceneNode[]}
+ */
+function primitives_of(bundle) {
+    return bundle.nodes.filter(node => node.geometry !== null);
+}
+
+/**
+ * @param {Set<MeshletGeometry>} geometries
+ * @param {SceneNode[]} primitives
+ */
+function optimize_geometry_set(geometries, primitives) {
+    const removed = deduplicate_geometries(Array.from(geometries));
+
+    if (removed.length > 0) {
+        console.log(`scene_optimize: removed ${removed.length} exact-duplicate geometries`);
+
+        const replace_map = new Map();
+
+        for (const [victim, master] of removed) {
+            replace_map.set(victim, master);
+        }
+
+        for (const primitive of primitives) {
+            if (replace_map.has(primitive.geometry)) {
+                primitive.geometry = replace_map.get(primitive.geometry);
+            }
+        }
+    }
+}
+
+/**
+ * Detect equivalent triangle subsets across the surviving geometries (after exact dedup) and
+ * replace primitives with shared canonical pieces.
+ *
+ *  - Single-piece replacement with identity transform: just swap geometry.
+ *  - Single-piece with non-identity transform: swap geometry, premultiply the node's local by
+ *    the piece's transform.
+ *  - Multi-piece replacement: the node stops drawing and gains one child per piece, each at the
+ *    piece's transform under it — so the node's own place, and anything already under it, is
+ *    left exactly where it was.
+ *
+ * @param {SceneBundle} bundle
+ */
+function optimize_geometry_pieces(bundle) {
+    const primitives = primitives_of(bundle);
+
+    /** @type {Map<MeshletGeometry, Geometry>} */
+    const mg_to_geom = new Map();
+    /** @type {Map<Geometry, MeshletGeometry>} canonical (input-derived) Geometry → its source MG */
+    const geom_to_source_mg = new Map();
+
+    for (const primitive of primitives) {
+        if (mg_to_geom.has(primitive.geometry)) {
+            continue;
+        }
+
+        let geom = geometry_build_from_meshlet_geometry(primitive.geometry);
+
+        // undo meshlet damage
+        geom = geometry_deduplicate_vertices(geom);
+
+        mg_to_geom.set(primitive.geometry, geom);
+        geom_to_source_mg.set(geom, primitive.geometry);
+    }
+
+    const geometries = Array.from(mg_to_geom.values());
+    const triangles_before = sum_unique_triangles(primitives);
+
+    if (geometries.length < 2) {
+        console.log(`scene_optimize: only ${geometries.length} unique geometries, skipping piece-level dedup`);
+        return;
+    }
+
+    const replacement_map = geometry_deduplicate({
+        geometries,
+        min_primitives: 64
+    });
+
+    /** @type {Map<Geometry, MeshletGeometry>} memoised MGs for newly-built piece Geometries */
+    const built_mg_for_geom = new Map();
+
+    const get_mg_for_geom = (geom) => {
+        const source = geom_to_source_mg.get(geom);
+
+        if (source !== undefined) return source;
+
+        let mg = built_mg_for_geom.get(geom);
+
+        if (mg === undefined) {
+            mg = meshlet_geometry_build_from_geometry(geom);
+            built_mg_for_geom.set(geom, mg);
+        }
+
+        return mg;
+    };
+
+    let primitives_swapped = 0;
+    let primitives_split = 0;
+    let primitives_added = 0;
+
+    const nodes = bundle.nodes;
+
+    // the bundle grows below; walk what was there
+    const node_count = nodes.length;
+
+    for (let index = 0; index < node_count; index++) {
+        const node = nodes[index];
+
+        if (node.geometry === null) {
+            continue;
+        }
+
+        const source_geom = mg_to_geom.get(node.geometry);
+        const entries = replacement_map.get(source_geom);
+
+        if (entries === undefined || entries.length === 0) continue;
+
+        if (entries.length === 1) {
+            const [transform, geom] = entries[0];
+            const new_mg = get_mg_for_geom(geom);
+
+            if (new_mg !== node.geometry) {
+                if (!transform.isIdentity()) {
+                    node.local.multiply(transform);
+                    node.local.updateMatrix();
+                }
+
+                node.geometry = new_mg;
+
+                primitives_swapped++;
+            }
+
+            continue;
+        }
+
+        // Multi-piece: the node keeps its place and stops drawing; each piece draws under it
+        const material = node.material;
+        const name = node.name;
+
+        node.geometry = null;
+        node.material = null;
+
+        primitives_split++;
+
+        for (const [transform, geom] of entries) {
+            const piece = new SceneNode();
+
+            piece.name = name;
+            piece.parent = index;
+            piece.geometry = get_mg_for_geom(geom);
+            piece.material = material;
+            piece.local.copy(transform);
+            piece.local.updateMatrix();
+
+            bundle.add_node(piece);
+
+            primitives_added++;
+        }
+    }
+
+    const after = primitives_of(bundle);
+    const triangles_after = sum_unique_triangles(after);
+    const unique_geoms_after = count_unique_geometries(after);
+
+    console.log(
+        `scene_optimize: piece-level dedup — `
+        + `${primitives_swapped} swapped, ${primitives_split} split, ${primitives_added} added; `
+        + `unique geometries ${geometries.length} → ${unique_geoms_after}; `
+        + `unique-geometry triangles ${triangles_before} → ${triangles_after} `
+        + `(saved ${triangles_before - triangles_after})`
+    );
+
+    // TODO rebuild meshlet BLASs, using high quality settings
+}
+
+/**
+ * @param {SceneNode[]} primitives
+ * @returns {number}
+ */
+function count_unique_geometries(primitives) {
+    const set = new Set();
+
+    for (const p of primitives) set.add(p.geometry);
+
+    return set.size;
+}
+
+/**
+ * @param {SceneNode[]} primitives
+ * @returns {number}
+ */
+function sum_unique_triangles(primitives) {
+    const seen = new Set();
+
+    let total = 0;
+
+    for (const p of primitives) {
+        if (seen.has(p.geometry)) continue;
+
+        seen.add(p.geometry);
+
+        total += p.geometry.primitive_count;
+    }
+
+    return total;
+}
+
+/**
+ * Make a loaded model cheaper to draw without changing what it looks like: exact-duplicate
+ * geometries collapse to one, equivalent pieces of different geometries are shared, and the
+ * textures the materials reach are deduplicated and downscaled where that loses nothing.
+ *
+ * The bundle is rewritten in place — it is the tool's, not a shared asset's.
+ *
+ * @param {SceneBundle} bundle
+ */
+export function scene_optimize(bundle) {
+    assert.defined(bundle, 'bundle');
+    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
+
+    const primitives = primitives_of(bundle);
+
+    // extract materials
+    const materials = new Set();
+    const geometries = new Set();
+
+    for (const primitive of primitives) {
+        materials.add(primitive.material);
+        geometries.add(primitive.geometry);
+    }
+
+    optimize_geometry_set(geometries, primitives);
+    optimize_geometry_pieces(bundle);
+
+    /**
+     * @type {Set<ShadeTexture>}
+     */
+    const textures = new Set();
+
+    for (const material of materials) {
+        for (const t of material.textures) {
+            textures.add(t);
+        }
+    }
+
+    optimize_texture_set(textures);
+}

package/src/shade/renderer/scene/rows/GPUEntityBoundsReadback.d.ts

@@ -0,0 +1,53 @@
+/**
+ * An entity's world bounds as the GPU holds them, read back.
+ *
+ * The box the renderer culls a primitive by is derived on the GPU from its geometry under the
+ * `global` the hierarchy pass composed — which for a subtree the GPU drives is a matrix the CPU
+ * never sees, and for a skinned primitive is the deformed clone's box rather than the rest pose's.
+ * A consumer that wants the box that is drawn — an editor's selection outline, a framing camera —
+ * asks here: {@link request} once a frame for each entity it cares about, and {@link get} for the
+ * last box that landed. A box lands a frame or two after it was asked for, at the head of a frame,
+ * never mid-update; until the first lands there is no answer, and a request that was dropped —
+ * the row changed hands — leaves the last answer standing.
+ *
+ * One request per entity per frame is the intended use; the readback service batches a frame's
+ * requests into one copy, or one gather dispatch past its threshold.
+ */
+export class GPUEntityBoundsReadback {
+    /**
+     * @param {import("../../buffer/table/GPUDatabaseReadback.js").GPUDatabaseReadback} readback the
+     *        scene database's
+     * @param {import("./GPUSceneRows.js").GPUSceneRows} rows
+     */
+    constructor(readback: import("../../buffer/table/GPUDatabaseReadback.js").GPUDatabaseReadback, rows: import("./GPUSceneRows.js").GPUSceneRows);
+    /**
+     * How many entities have a box here, delivered or awaited.
+     *
+     * @returns {number}
+     */
+    get tracked_count(): number;
+    /**
+     * Ask for an entity's box as the GPU holds it this frame. Nothing is asked for an entity with
+     * no mesh row — no primitive is drawn for it, so there is no box to read.
+     *
+     * @param {number} entity
+     * @returns {boolean} whether a row was asked for
+     */
+    request(entity: number): boolean;
+    /**
+     * The last box that landed for an entity.
+     *
+     * @param {number} entity
+     * @param {ArrayLike<number>|Float32Array|Float64Array|number[]} target aabb3, `x0,y0,z0,x1,y1,z1`
+     * @returns {boolean} whether one has; `false` leaves `target` alone
+     */
+    get(entity: number, target: ArrayLike<number> | Float32Array | Float64Array | number[]): boolean;
+    /**
+     * Stop keeping an entity's box. A request already on the device lands in memory nothing reads.
+     *
+     * @param {number} entity
+     */
+    forget(entity: number): void;
+    #private;
+}
+//# sourceMappingURL=GPUEntityBoundsReadback.d.ts.map

package/src/shade/renderer/scene/rows/GPUEntityBoundsReadback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUEntityBoundsReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUEntityBoundsReadback.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH;IA8BI;;;;OAIG;IACH,sBAJW,OAAO,2CAA2C,EAAE,mBAAmB,QAEvE,OAAO,mBAAmB,EAAE,YAAY,EAUlD;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,OAAO,CAyBnB;IAED;;;;;;OAMG;IACH,YAJW,MAAM,UACN,UAAU,MAAM,CAAC,GAAC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAClD,OAAO,CAgBnB;IAED;;;;OAIG;IACH,eAFW,MAAM,QAIhB;;CACJ"}