@woosh/meep-engine 3.14.4 → 3.14.5

package/src/shade/renderer/shader/chunk/geometry/quaternion/dual/chunk_dual_quat_from_m4.js

@@ -1,37 +1,58 @@
-import { CodeChunk } from "../../../../compiler/CodeChunk.js";
-import { chunk_sign_not_zero } from "../../../math/chunk_sign_not_zero.js";
-import { chunk_quat_multiply } from "../chunk_quat_multiply.js";
-
-/**
- * @see https://github.com/KosRud/DQ-skinning-for-Unity/blob/9d096e2db57677f0f67a823432f8b735ad622404/Code/DQ%20skinning/Shaders/Compute/DQ.cginc#L59
- * @see http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm
- * Alternative Method by Christian
- */
-export const chunk_dual_quat_from_m4 = CodeChunk.from(
-    //language=WGSL
-    `
-fn dual_quat_from_m4(m: mat4x4<f32>) -> mat2x4<f32> {
-
-    var dq: mat2x4<f32>;
-
-    dq[0].w = sqrt(max(0, 1.0 + m[0][0] + m[1][1] + m[2][2])) * 0.5;
-	dq[0].x = sqrt(max(0, 1.0 + m[0][0] - m[1][1] - m[2][2])) * 0.5;
-	dq[0].y = sqrt(max(0, 1.0 - m[0][0] + m[1][1] - m[2][2])) * 0.5;
-	dq[0].z = sqrt(max(0, 1.0 - m[0][0] - m[1][1] + m[2][2])) * 0.5;
-	
-	dq[0].x *= sign_not_zero(m[1][2] - m[2][1]);
-	dq[0].y *= sign_not_zero(m[2][0] - m[0][2]);
-	dq[0].z *= sign_not_zero(m[0][1] - m[1][0]);
-
-	dq[0] = normalize(dq[0]);	// ensure unit quaternion
-
-	dq[1] = vec4(m[3][0], m[3][1], m[3][2], 0);
-	dq[1] = quat_multiply(dq[1], dq[0]) * 0.5;
-
-    return dq;
-}
-    `,[
-        chunk_quat_multiply,
-        chunk_sign_not_zero
-    ]
-)
+import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+import { chunk_quat_from_m3 } from "../chunk_quat_from_m3.js";
+import { chunk_quat_multiply } from "../chunk_quat_multiply.js";
+
+/**
+ * A rigid transform as a dual quaternion: the rotation in the real part, the translation carried in
+ * the dual part as `0.5 · t · real`.
+ *
+ * The matrix's upper 3×3 is read as a rotation and its fourth column as a translation. Anything else
+ * in the matrix — a scale, a shear — has nowhere to go, and comes back as neither itself nor a
+ * warning: see {@link m4_rigidity_defect} for the number that says so and
+ * `renderer/animation/SKINNING_FRAME_PLAN.md` for the frame arrangement that keeps a skinning
+ * matrix rigid in the first place.
+ *
+ * ## Why the rotation goes through `quat_from_m3`
+ *
+ * This used to take all four quaternion components as `sqrt(max(0, 1 ± m00 ± m11 ± m22)) · 0.5` and
+ * recover their signs from the off-diagonal differences. That is exact in exact arithmetic and
+ * badly conditioned in floating point: near the identity three of those radicands are near zero, and
+ * a square root turns an input error of `e` into an output error of `sqrt(e)`. A matrix that is the
+ * identity to `1e-6` — which is what a skin's folded joint matrices are at bind pose — yielded
+ * quaternion components off by `9e-4`, an angular error of `1.8e-3` radians, and a millimetre and a
+ * half of vertex displacement on a 1.66 m character. Measured, on `Michelle.glb`.
+ *
+ * {@link chunk_quat_from_m3} is Shoemake's branch-picking form: it computes whichever component the
+ * matrix's diagonal says is largest, and derives the other three from it by division. Every branch
+ * divides by at least 2, so the components come out **linear** in the input error rather than as its
+ * square root — the same `1e-6` matrix now gives `2.5e-7`, three and a half orders better — and the
+ * near-180° case, where the trace form is ill-conditioned for the opposite reason, is a branch of its
+ * own. One `sqrt` and a reciprocal where there were four `sqrt`s.
+ *
+ * The normalize stays, on top of that. It is a no-op for the orthonormal input this is meant to be
+ * given; what it earns its rsqrt for is the input that is not — a degenerate 3×3 leaves
+ * `quat_from_m3` on a branch whose answer has length 0.5, and this is what keeps the documented
+ * postcondition, a unit real part, true anyway.
+ *
+ * @see https://gitlab.com/libeigen/eigen/-/blob/master/Eigen/src/Geometry/Quaternion.h#L813
+ * @type {CodeChunk}
+ */
+export const chunk_dual_quat_from_m4 = CodeChunk.from(
+    //language=WGSL
+    `
+fn dual_quat_from_m4(m: mat4x4<f32>) -> mat2x4<f32> {
+
+    var dq: mat2x4<f32>;
+
+    dq[0] = normalize(quat_from_m3(mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz)));
+
+	dq[1] = vec4(m[3][0], m[3][1], m[3][2], 0);
+	dq[1] = quat_multiply(dq[1], dq[0]) * 0.5;
+
+    return dq;
+}
+    `, [
+        chunk_quat_from_m3,
+        chunk_quat_multiply,
+    ]
+)

package/src/shade/renderer/particles/graph/ParticleGraph.d.ts

@@ -1,54 +0,0 @@
-/**
- * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id).
- * @param {...number} components
- * @returns {number[]}
- */
-export function literal(...components: number[]): number[];
-/**
- * A directed acyclic graph describing one lifecycle phase (SPAWN or UPDATE) of a particle effect.
- *
- * Nodes are value-producing operations (constants, builtins, attribute reads, math, curves, random)
- * or sinks (attribute writes, kill). Edges wire a producing node's single `out` port to a consuming
- * node's named input port. Inputs may also be literal `vec4` values, which the compiler lowers to
- * constant loads.
- *
- * The graph is pure data + a small builder; {@link ../graph/compile_particle_graph.js} lowers it to
- * VM bytecode.
- */
-export class ParticleGraph {
-    /** @type {Map<number, {id: number, type: string, params: object, inputs: Map<string, object>}>} */
-    nodes: Map<number, {
-        id: number;
-        type: string;
-        params: object;
-        inputs: Map<string, object>;
-    }>;
-    /** @type {number} */
-    next_id: number;
-    /**
-     * Add a node.
-     * @param {string} type a key in {@link PARTICLE_NODE_TYPES}
-     * @param {object} [params] static parameters (attribute name, builtin id, constant value, …)
-     * @returns {number} the new node id
-     */
-    add(type: string, params?: object): number;
-    /**
-     * Bind an input port of a node to a source.
-     *
-     * The source may be:
-     * - a node id (number) → that node's `out` port,
-     * - `{ node, port }` → an explicit port,
-     * - a number or array → a literal `vec4` (scalars broadcast is NOT applied; `5` means `[5,0,0,0]`).
-     *
-     * @param {number} node_id
-     * @param {string} port
-     * @param {number|number[]|{node: number, port?: string}} source
-     * @returns {ParticleGraph} this, for chaining
-     */
-    wire(node_id: number, port: string, source: number | number[] | {
-        node: number;
-        port?: string;
-    }): ParticleGraph;
-    #private;
-}
-//# sourceMappingURL=ParticleGraph.d.ts.map

package/src/shade/renderer/particles/graph/ParticleGraph.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ParticleGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleGraph.js"],"names":[],"mappings":"AA2FA;;;;GAIG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB;AA/FD;;;;;;;;;;GAUG;AACH;IAEQ,mGAAmG;IACnG,OADW,IAAI,MAAM,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,IAAI,MAAM,EAAE,MAAM,CAAC,CAAA;KAAC,CAAC,CACzE;IACtB,qBAAqB;IACrB,SADW,MAAM,CACD;IAGpB;;;;;OAKG;IACH,UAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;;;;;;;OAYG;IACH,cALW,MAAM,QACN,MAAM;cACiB,MAAM;eAAS,MAAM;QAC1C,aAAa,CAYzB;;CAQJ"}

package/src/shade/renderer/particles/graph/ParticleGraph.js

@@ -1,99 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import { PARTICLE_NODE_TYPES } from "./ParticleNodeRegistry.js";
-
-/**
- * A directed acyclic graph describing one lifecycle phase (SPAWN or UPDATE) of a particle effect.
- *
- * Nodes are value-producing operations (constants, builtins, attribute reads, math, curves, random)
- * or sinks (attribute writes, kill). Edges wire a producing node's single `out` port to a consuming
- * node's named input port. Inputs may also be literal `vec4` values, which the compiler lowers to
- * constant loads.
- *
- * The graph is pure data + a small builder; {@link ../graph/compile_particle_graph.js} lowers it to
- * VM bytecode.
- */
-export class ParticleGraph {
-    constructor() {
-        /** @type {Map<number, {id: number, type: string, params: object, inputs: Map<string, object>}>} */
-        this.nodes = new Map();
-        /** @type {number} */
-        this.next_id = 0;
-    }
-
-    /**
-     * Add a node.
-     * @param {string} type a key in {@link PARTICLE_NODE_TYPES}
-     * @param {object} [params] static parameters (attribute name, builtin id, constant value, …)
-     * @returns {number} the new node id
-     */
-    add(type, params = {}) {
-        const definition = PARTICLE_NODE_TYPES[type];
-        if (definition === undefined) {
-            throw new Error(`Unknown particle node type '${type}'`);
-        }
-
-        const id = this.next_id++;
-        this.nodes.set(id, { id, type, params, inputs: new Map() });
-        return id;
-    }
-
-    /**
-     * Bind an input port of a node to a source.
-     *
-     * The source may be:
-     * - a node id (number) → that node's `out` port,
-     * - `{ node, port }` → an explicit port,
-     * - a number or array → a literal `vec4` (scalars broadcast is NOT applied; `5` means `[5,0,0,0]`).
-     *
-     * @param {number} node_id
-     * @param {string} port
-     * @param {number|number[]|{node: number, port?: string}} source
-     * @returns {ParticleGraph} this, for chaining
-     */
-    wire(node_id, port, source) {
-        const node = this.#require(node_id);
-
-        const definition = PARTICLE_NODE_TYPES[node.type];
-        if (!definition.inputs.includes(port)) {
-            throw new Error(`Node '${node.type}' has no input port '${port}'`);
-        }
-
-        node.inputs.set(port, normalize_source(source));
-        return this;
-    }
-
-    /** @param {number} id @returns {{id, type, params, inputs}} */
-    #require(id) {
-        const node = this.nodes.get(id);
-        assert.defined(node, `node ${id}`);
-        return node;
-    }
-}
-
-/**
- * @param {number|number[]|{node:number,port?:string}} source
- * @returns {{kind: "node", node: number, port: string} | {kind: "literal", value: number[]}}
- */
-function normalize_source(source) {
-    if (typeof source === "number") {
-        // Could be a node id or a scalar literal — ambiguous, so require explicit forms for literals.
-        return { kind: "node", node: source, port: "out" };
-    }
-    if (Array.isArray(source)) {
-        const value = [source[0] ?? 0, source[1] ?? 0, source[2] ?? 0, source[3] ?? 0];
-        return { kind: "literal", value };
-    }
-    if (source !== null && typeof source === "object" && typeof source.node === "number") {
-        return { kind: "node", node: source.node, port: source.port ?? "out" };
-    }
-    throw new Error(`Invalid input source: ${JSON.stringify(source)}`);
-}
-
-/**
- * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id).
- * @param {...number} components
- * @returns {number[]}
- */
-export function literal(...components) {
-    return components;
-}