@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/scene/Mesh.js

@@ -1,168 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
-import { aabb3_from_v3_array_transformed } from "../../../core/geom/3d/aabb/aabb3_from_v3_array_transformed.js";
-import { aabb3_matrix4_project } from "../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { sphere_matrix4_transform } from "../../../core/geom/3d/sphere/sphere_matrix4_transform.js";
-import { epsilonEquals } from "../../../core/math/epsilonEquals.js";
-import { optional_equality } from "../../../core/model/object/optional_equality.js";
-import { StandardAttributes } from "../geometry/StandardAttributes.js";
-import { Node3D } from "./Node3D.js";
-
-/**
- * @typedef {import("../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
- * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
- */
-
-export class Mesh extends Node3D {
-    /**
-     * @type {MeshletGeometry}
-     */
-    geometry;
-
-    /**
-     * @type {ShadeMaterial}
-     */
-    material;
-
-    /**
-     * World-space AABB
-     * @type {Float32Array}
-     */
-    bounding_box = new Float32Array(6);
-
-    /**
-     *
-     * @type {Float32Array}
-     */
-    bounding_sphere = new Float32Array(4);
-
-    /**
-     *
-     * @returns {Mesh}
-     */
-    clone() {
-        const r = new Mesh();
-
-        r.copy(this);
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {Mesh} other
-     */
-    copy(other) {
-
-        if (this === other) {
-            // special case
-            return;
-        }
-
-        super.copy(other);
-
-        this.geometry = other.geometry;
-        this.material = other.material;
-        this.name = other.name;
-
-        this.bounding_box.set(other.bounding_box);
-        this.bounding_sphere.set(other.bounding_sphere);
-    }
-
-    /**
-     *
-     * @param {Mesh} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.name === other.name
-            && optional_equality(this.geometry, other.geometry)
-            && optional_equality(this.material, other.material)
-            && this.transform_global.equals(other.transform_global)
-            ;
-    }
-
-    updateMatrices() {
-        super.updateMatrices();
-
-        this.updateBoundsBasic();
-    }
-
-    updateBoundsBasic() {
-        // a Transform64's matrix starts at element 0, so the transform is its own mat4 argument —
-        // going through `.matrix` would allocate a view per call for nothing
-        const m = this.transform_global;
-
-        aabb3_matrix4_project(this.bounding_box, this.geometry.bounding_box, m);
-        sphere_matrix4_transform(this.bounding_sphere, this.geometry.bounding_sphere, m);
-    }
-
-    updateBoundsTight() {
-
-        const t = this.transform_global;
-
-        const unrotated = epsilonEquals(t.rotation_x, 0)
-            && epsilonEquals(t.rotation_y, 0)
-            && epsilonEquals(t.rotation_z, 0)
-            && epsilonEquals(t.rotation_w, 1);
-
-        if (unrotated) {
-            // no rotation component, can safely scale/translate geometry bounds to get tight fit
-            this.updateBoundsBasic();
-
-        } else {
-
-            throw new Error('not implemented');
-
-            const position_attribute = this.geometry.getAttribute(StandardAttributes.Position);
-            const position_array = position_attribute.data;
-
-            {
-                const bounds = new AABB3();
-
-                aabb3_from_v3_array_transformed(
-                    bounds,
-                    position_array, position_array.length,
-                    this.transform_global
-                );
-
-                bounds.writeToArray(this.bounding_box, 0);
-            }
-
-            {
-                // todo do a tight sphere bounds
-                sphere_matrix4_transform(this.bounding_sphere, this.geometry.bounding_sphere, this.transform_global);
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @param {ShadeMaterial} material
-     * @param {number[]|Float32Array|Float64Array} [transform] 4x4 affine matrix, column-major
-     * @return {Mesh}
-     */
-    static from(geometry, material, transform) {
-        assert.defined(geometry, 'geometry');
-        assert.defined(material, 'material');
-
-        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
-
-        const r = new Mesh();
-
-        r.geometry = geometry;
-        r.material = material;
-
-        if (transform !== undefined) {
-            r.transform_local.fromMatrix(transform);
-        }
-
-        r.updateMatrices();
-
-        return r;
-    }
-}
-
-
-Mesh.prototype.isMesh = true;

package/src/shade/renderer/scene/Node3D.js

@@ -1,263 +0,0 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
-import { t64_transform_direction } from "../../../engine/ecs/transform/t64_transform_direction.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { TransformAuthority } from "./TransformAuthority.js";
-
-let id_counter = 0;
-
-/**
- * Note that hierarchy only exists on the CPU side
- * The only transform that GPU will see is the {@link transform_global}
- */
-export class Node3D {
-
-    /**
-     * Stable numeric id, unique across every Node3D instance (meshes,
-     * lights, scenes, anchors). Used as the key in
-     * `GPUSceneContext.id_mapping` to look up the node's row in the
-     * GPU `transforms` table — the binding survives table compaction
-     * or rebuild because it's tied to the JS object's identity, not
-     * its position in any array.
-     *
-     * @type {number}
-     * @readonly
-     */
-    id = id_counter++;
-
-    /**
-     * Human-readable name
-     * @type {string}
-     */
-    name = ""
-
-    /**
-     * @type {number}
-     */
-    #version = 0;
-
-    /**
-     * Bumped by {@link updateMatrices}. The renderer compares it against the version it last
-     * uploaded for this node's row, so a node that has not moved since the previous frame costs
-     * nothing beyond the comparison — that is what keeps per-frame scene upkeep proportional to
-     * what changed rather than to scene size.
-     *
-     * A caller that mutates `transform_local` without calling {@link updateMatrices} leaves
-     * `transform_global` stale, and this counter says so: both are derived, and neither is
-     * refreshed until the call is made.
-     *
-     * @returns {number}
-     */
-    get version() {
-        return this.#version;
-    }
-
-    /**
-     * @param {boolean} v
-     */
-    set needsUpdate(v) {
-        if (v) {
-            this.#version++;
-        }
-    }
-
-    /**
-     * Who writes this node's TRS in the GPU `transforms` table. Declared, never inferred — see
-     * {@link TransformAuthority} for what each side owns and why guessing does not work.
-     *
-     * @type {TransformAuthority}
-     */
-    transform_authority = TransformAuthority.CPU;
-
-    /**
-     * World transform, **derived** — {@link updateMatrices} recomputes it from
-     * {@link transform_local} and the parent chain, so writing it directly is undone the moment
-     * anything refreshes. Place a node through its local transform.
-     *
-     * @type {Transform64}
-     */
-    transform_global = new Transform64();
-
-    /**
-     * Local transform, and the node's own truth. Passive: setting a component does not refresh the
-     * matrix, and nothing downstream sees the change until {@link updateMatrices} runs.
-     *
-     * @type {Transform64}
-     */
-    transform_local = new Transform64();
-
-    parent = null;
-
-    /**
-     *
-     * @type {Node3D[]}
-     */
-    children = []
-
-    /**
-     * Orientation vector — `(0,0,1)` rotated by the node's global transform. Freshly allocated;
-     * hold on to it rather than reading this in a loop.
-     *
-     * @return {Vector3}
-     */
-    get forward() {
-        return t64_transform_direction(new Vector3(), this.transform_global, 0, 0, 1);
-    }
-
-    /**
-     * Orient this node so its local +Z axis points along `v`. Preserves
-     * position. A zero-length input is a no-op. Recomputes
-     * `transform_global` so the new orientation is visible immediately.
-     *
-     * @param {Vector3|number[]} v
-     */
-    set forward(v) {
-        const fx = v[0], fy = v[1], fz = v[2];
-        if (fx === 0 && fy === 0 && fz === 0) return;
-
-        t64_look_rotation(this.transform_local, fx, fy, fz, 0, 1, 0);
-        this.updateMatrices();
-    }
-
-    /**
-     * Orientation vector — `(1,0,0)` rotated by the node's global transform. Freshly allocated;
-     * hold on to it rather than reading this in a loop.
-     *
-     * @return {Vector3}
-     */
-    get right() {
-        return t64_transform_direction(new Vector3(), this.transform_global, 1, 0, 0);
-    }
-
-    /**
-     * @param {Vector3|number[]} v
-     */
-    set position(v) {
-        this.transform_local.setTranslation(v[0], v[1], v[2]);
-    }
-
-    /**
-     * Live view over the local transform's own storage, freshly allocated on every access. Writing
-     * through it does not refresh anything — {@link updateMatrices} still has to run.
-     *
-     * @returns {Float64Array}
-     */
-    get position() {
-        return this.transform_local.translation;
-    }
-
-    copy(other) {
-        this.transform_local.copy(other.transform_local);
-        this.transform_global.copy(other.transform_global);
-
-        this.#version++;
-    }
-
-    clone() {
-
-        const r = new Node3D();
-
-        r.copy(this);
-
-        const children = this.children;
-        const child_count = children.length;
-
-        for (let i = 0; i < child_count; i++) {
-            const clone = children[i].clone();
-
-            clone.parent = r;
-
-            r.children.push(clone);
-
-        }
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {function(Node3D)} callback
-     * @param {*} [thisArg]
-     */
-    traverse(callback, thisArg) {
-        callback.call(thisArg, this);
-
-        for (const child of this.children) {
-            child.traverse(callback, thisArg);
-        }
-    }
-
-    /**
-     * Recompose this node's world transform and every descendant's.
-     *
-     * The local matrix is refreshed first because nothing else will: a `Transform64` does not track
-     * its own components, and {@link Transform64.multiplyTransforms} composes through matrices. Skip
-     * it and the node would be placed where it was the last time someone asked.
-     */
-    updateMatrices() {
-
-        const transform_local = this.transform_local;
-
-        transform_local.updateMatrix();
-
-        const parent = this.parent;
-
-        if (parent === null) {
-            this.transform_global.copy(transform_local);
-        } else {
-            this.transform_global.multiplyTransforms(parent.transform_global, transform_local);
-        }
-
-        this.#version++;
-
-        const children = this.children;
-
-        const length = children.length;
-
-        for (let i = 0; i < length; i++) {
-
-            const child = children[i];
-
-            child.updateMatrices();
-        }
-    }
-
-    /**
-     *
-     * @param {Node3D[]} children
-     */
-    addChildren(children) {
-        const length = children.length;
-        for (let i = 0; i < length; i++) {
-            this.addChild(children[i]);
-        }
-    }
-
-    /**
-     *
-     * @param {Node3D} child
-     */
-    addChild(child) {
-        if (child === this) {
-            throw new Error(`Can't add to self`);
-        }
-
-        if (child.parent !== null) {
-            throw new Error(`node already attached to something`);
-        }
-
-        child.parent = this;
-
-        this.children.push(child);
-    }
-
-}
-
-/**
- * Type tag — lets `instanceof`-free callers (e.g. `InstanceBatch.add`)
- * accept anything that conforms to the Node3D shape.
- *
- * @readonly
- * @type {boolean}
- */
-Node3D.prototype.isNode3D = true;

package/src/shade/renderer/scene/SceneNodeBinding.js

@@ -1,56 +0,0 @@
-import { TransformAuthority } from "./TransformAuthority.js";
-
-/**
- * What one {@link Node3D} owns inside a {@link GPUSceneContext}'s scene database: a row in the
- * `transforms` table, and — when the node is a {@link Mesh} — a row in the `meshes` table too.
- *
- * **Rows are stable for the lifetime of the binding.** Removing a node frees its rows and leaves a
- * hole rather than compacting the table, because rows are addresses: GPU animation targets a node
- * by row index, `meshes.node` points at one, and every `transforms.parent` is one. Compaction would
- * silently re-point all of them, so the tables tolerate holes instead and the passes that walk them
- * consult occupancy.
- */
-export class SceneNodeBinding {
-    /**
-     * Row in the scene database's `transforms` table.
-     *
-     * @type {number}
-     */
-    transform_row = 0;
-
-    /**
-     * Row in the scene database's `meshes` table. Meaningful only for a node that is a mesh —
-     * `node.isMesh` is what says whether to read it, not this value.
-     *
-     * @type {number}
-     */
-    mesh_row = -1;
-
-    /**
-     * The {@link Node3D.version} that the rows above were last written from. A node whose version
-     * still matches this has not moved since, and costs nothing but the comparison.
-     *
-     * @type {number}
-     */
-    version = -1;
-
-    /**
-     * The {@link TransformAuthority} in force when the rows were last written.
-     *
-     * Kept because handing a row back to the CPU has to be acted on rather than waited for: while
-     * the GPU owned the row the node's own version stood still, so nothing would ever mark it as
-     * needing a write, and the CPU would take over a row it never wrote to.
-     *
-     * @type {TransformAuthority}
-     */
-    authority = TransformAuthority.CPU;
-
-    /**
-     * Membership-sweep marker. Set to the current sweep's number every time the node is found in
-     * the scene; a binding still carrying an older number after a sweep belongs to a node that has
-     * left, and its rows are freed.
-     *
-     * @type {number}
-     */
-    epoch = -1;
-}

package/src/shade/renderer/scene/SkinnedMesh.js

@@ -1,170 +0,0 @@
-import { compute_skin_world_bounds } from "../animation/compute_skin_world_bounds.js";
-import { Mesh } from "./Mesh.js";
-
-/**
- * @typedef {import("../animation/Skin.js").Skin} Skin
- */
-
-/**
- * A mesh whose vertices are deformed each frame by joint transforms.
- *
- * On the CPU side, a `SkinnedMesh` is just a {@link Mesh} that points at
- * the *unmodified* source {@link MeshletGeometry} — the same way every
- * other instance of that mesh would. Multiple `SkinnedMesh` instances
- * share the source geometry; no per-instance CPU clones happen.
- *
- * The GPU side makes the deformation possible by allocating a
- * per-instance vertex/metadata clone of the source geometry inside the
- * existing meshlet buffers (see
- * {@link GPUMeshletManager#clone_batch_allocation}). The clone is
- * registered as a separate geometry id (see
- * {@link GPUGeometryManager#add_clone}); the instance record this mesh
- * produces points at the clone, not at the source. Rasterization then
- * sees the clone like any other geometry.
- *
- * Per-frame, a skinning compute pass reads the source's vertex data and
- * the joint matrices and writes the deformed result into the clone's
- * vertex region — leaving every other instance pointed at the source
- * untouched. The skin matrices are computed per the glTF spec formula
- * `inverse(meshNode.worldMatrix) × jointNode.worldMatrix ×
- * inverseBindMatrix`, and the rasterizer re-applies
- * `mesh.transform_global` to the result — so the mesh node's own
- * transform cancels out of the rendered position exactly, which is what
- * the glTF spec asks for. The leftmost factor is taken live from the
- * mesh's own transforms row inside {@link shader_meshlet_apply_skinning};
- * see {@link chunk_skin_blend_mesh_local} for why it goes into each
- * matrix rather than onto the blended position.
- *
- * **`transform_global` on a skinned mesh is the engine's, not the
- * asset's.** It cancels out of the rendered position, so glTF declares
- * it meaningless — and the one meaning it does have is the frame the
- * clone's vertices are written in, which the fold above requires to be
- * rigid against the skin. {@link GPUAnimationManager#register_skin}
- * therefore overwrites it, by way of
- * {@link skin_normalize_mesh_frame}, with the skin's own bind
- * transform. Whatever the file put there is discarded, and anything
- * reading this expecting the file's value is reading the wrong thing.
- * See `renderer/animation/SKINNING_FRAME_PLAN.md`.
- *
- * The mesh's **skin id** — a row in a GPU table — lives in
- * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
- * {@link Skin} it was registered with is a different thing, pure data
- * that knows nothing about the GPU, and this mesh holds a reference to
- * it in {@link skin} so its bounds can be worked out without asking the
- * GPU anything. Bind the mesh to a skin via
- * `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
- * {@link GPUAnimationManager#register_skin} to do it for every entry
- * in `Skin.meshes` — which is also what populates {@link skin}. Until
- * bound, the clone routes through the rendering path but its vertices
- * stay at the source's bind-pose values — useful as an intermediate
- * verification state, and the state in which this mesh bounds itself
- * exactly like a regular {@link Mesh}.
- *
- * A note on which bounds to believe. {@link Mesh#bounding_box} here is
- * derived from whatever pose the *CPU* can see, and for a character
- * animated by the pose accumulator that is the rest pose — the joints
- * are {@link TransformAuthority.GPU} and their `transform_global` is
- * never advanced. It is the right size and in the right place, and it
- * is what seeds the scene database's `meshes` row. The deformed world
- * box, refreshed every frame from the vertices the skinning pass just
- * moved, is that row — read it from there when the silhouette is what
- * matters.
- */
-export class SkinnedMesh extends Mesh {
-
-    /**
-     * The skin whose formula places this mesh's vertices, or `null` while none does.
-     *
-     * Not "is the deformation running" — {@link GPUMeshSkinningContext#unbind} can stop the
-     * skinning pass without this changing, and a mesh whose pass has stopped still holds vertices
-     * the skin put there. So {@link GPUAnimationManager#register_skin} writes it and nothing
-     * clears it: once a skin has taken a mesh over, its formula stays the right basis for
-     * {@link updateBoundsBasic} whether or not a pass runs this frame. Clear it by hand to hand
-     * the mesh back to {@link Mesh}'s composition.
-     *
-     * CPU data throughout (see {@link Skin}). The GPU-side skin *id* is a table row and lives in
-     * {@link GPUMeshSkinningContext}; this does not expose it.
-     *
-     * Nothing refreshes derived state on assignment — set this and the bounds go on describing
-     * the previous basis until {@link updateMatrices} or {@link updateBoundsBasic} runs.
-     *
-     * A clone shares the reference, exactly as {@link Skin#copy} shares its joint and mesh
-     * references: retargeting a cloned character means replacing this alongside the skin's own
-     * arrays, which {@link instantiate_scene_bundle} gets for free by re-registering the
-     * corresponded skin.
-     *
-     * @type {Skin|null}
-     */
-    skin = null;
-
-    /**
-     * @returns {SkinnedMesh}
-     */
-    clone() {
-        const r = new SkinnedMesh();
-        r.copy(this);
-        return r;
-    }
-
-    /**
-     * @param {SkinnedMesh} other
-     */
-    copy(other) {
-
-        if (this === other) {
-            // special case
-            return;
-        }
-
-        super.copy(other);
-
-        this.skin = other.skin;
-    }
-
-    /**
-     * World bounds of the deformed mesh, in whatever pose {@link skin}'s joints currently hold.
-     *
-     * `Mesh`'s version puts the rest-pose geometry under `transform_global`, and for a skinned mesh
-     * that is the wrong composition rather than an imprecise one: the renderer *cancels*
-     * `transform_global` out of a skinned vertex's position (see the class docs), so applying it to
-     * the bounds applies a transform the vertices never see. On a glTF character whose root node
-     * carries the file's centimetre→metre scale — the shape every FBX-derived asset has, with
-     * vertex positions in metres and inverse-bind matrices in centimetres — the result is a box
-     * 100× too small, small enough that frustum culling and TLAS extraction see a point where a
-     * character stands.
-     *
-     * So a bound mesh goes through {@link compute_skin_world_bounds}, which composes the bound the
-     * same way the renderer composes the vertex. An unbound one keeps `Mesh`'s composition, because
-     * an unbound clone really is drawn as `transform_global × source vertices`. A skin with no
-     * joints deforms nothing and is treated the same way.
-     *
-     * **Reads the skeleton, so call it when the skeleton is settled.** The joints are outside this
-     * mesh's own subtree — a glTF character's joint root is the mesh node's sibling — and
-     * {@link Node3D#updateMatrices} walks pre-order, so the inherited call this gets mid-walk can
-     * read joints that have not been visited yet and land the mesh where the character was before
-     * the move. That is why {@link GPUSceneContext} re-derives it on the way to writing the
-     * `meshes` row, which is where the value is actually consumed and where every walk is over.
-     */
-    updateBoundsBasic() {
-        const skin = this.skin;
-
-        if (skin === null || skin.joints.length === 0) {
-            super.updateBoundsBasic();
-            return;
-        }
-
-        const geometry = this.geometry;
-
-        compute_skin_world_bounds(
-            skin,
-            geometry.bounding_box, geometry.bounding_sphere,
-            this.bounding_box, this.bounding_sphere
-        );
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-SkinnedMesh.prototype.isSkinnedMesh = true;

package/src/shade/renderer/scene/TransformAuthority.js

@@ -1,33 +0,0 @@
-/**
- * Who writes a node's `local_translation` / `local_rotation` / `local_scale` in the scene
- * database's `transforms` table.
- *
- * Both sides can reach those fields — the CPU through {@link GPUSceneContext}, the GPU through the
- * pose accumulator's resolve pass — and neither can tell that the other wrote. Without a stated
- * owner the two race, and the race is not hypothetical: {@link Node3D.updateMatrices} recurses into
- * children, so moving a character's root marks every joint under it as changed, and the CPU would
- * push its own idea of each joint's pose over whatever the animation had just resolved.
- *
- * `global` and `prev_global` are not covered by this — they are GPU-derived for every node, whoever
- * owns the TRS they are composed from.
- *
- * @enum {number}
- */
-export const TransformAuthority = {
-    /**
-     * The CPU owns the TRS. Its scene-graph node is the truth, and changes to it are pushed to the
-     * row as they happen. This is the default, and it is what entity placement wants.
-     */
-    CPU: 0,
-
-    /**
-     * The GPU owns the TRS — animation clips, effects, anything writing through the pose
-     * accumulator. The CPU allocates and seeds the row, then never writes to it again, so the
-     * node's own `transform_local` stops describing it and should not be read as if it did.
-     *
-     * A node under GPU authority still follows a CPU-driven parent: the hierarchy pass composes
-     * `global` from this node's TRS and the parent chain, so the parent moving carries the child
-     * without anyone writing to the child's row.
-     */
-    GPU: 1,
-};