@woosh/meep-engine 3.21.0 → 3.22.0

package/src/engine/physics/cloth/solver/ClothState.d.ts

@@ -0,0 +1,323 @@
+/**
+ * # ClothState — the whole simulated cloth, SoA, over one buffer
+ *
+ * Every array the step touches is a view into a single `ArrayBuffer`: particle
+ * state, the constraint tables, the per-particle incidence lists, and the
+ * duals. One allocation per cloth, one object to hand across a worker boundary
+ * (§12 puts a region per instance inside one shared buffer; this is that region
+ * with its views already cut), and no object dereference anywhere in the step.
+ * `SolverBodyState` is the same idea for rigid bodies and reads the same way.
+ *
+ * `Float32` throughout, per §12: the simulation runs in the cloth's local
+ * frame, so coordinates are garment-sized rather than world-sized and f32 has
+ * ample precision, and the payoff is half the bandwidth in the loop that
+ * dominates. JavaScript arithmetic is f64 regardless — only the *storage* is
+ * narrow, so a vertex update computes in double and rounds once on the way
+ * out.
+ *
+ * ## Particles are stored in colour order
+ *
+ * The sweep is "for each colour, for each particle in it" (§5.4). Rather than
+ * indirect through a colour membership list every iteration, {@link from}
+ * **permutes the particles** so each colour is a contiguous span, rewrites
+ * every row's particle indices into the new numbering, and stores one offset
+ * per colour. The sweep is then a pair of counted loops over adjacent indices
+ * and the runtime never sees a graph. {@link source_of_particle} carries the
+ * inverse permutation for a caller that has to map back to the mesh vertex it
+ * came from.
+ *
+ * ## Rows are stored per kind, and reached from the particle
+ *
+ * §6's row model is one table of `(C, f_min, f_max, stiffness)`, but the rows
+ * are *visited from the particle side* — a vertex update needs every row that
+ * touches particle `i`, not every row. So each kind carries a CSR incidence
+ * list: `*_adjacency_offset[i] .. [i + 1]` indexes into `*_adjacency`, whose
+ * entries pack the row index together with which slot of that row the particle
+ * occupies. Keeping the kinds in separate lists rather than one polymorphic
+ * table is what lets each accumulation loop stay monomorphic; a new row type
+ * is a new module and a new pair of arrays, not a branch inside the old loop.
+ *
+ * M0 carried the two persistent kinds the solver core is proved on — stretch
+ * and bend. M1 adds the third, the **leash**: §6's slack row and its tether
+ * row, which have the same `C` and differ only in where their centre and
+ * radius come from (`cloth_leash_row.js`). §6's strain-limit row needed no new
+ * storage at all — it is a stretch row with a longer rest length and a
+ * one-sided clamp, which the stretch table already carries. Backstop,
+ * collision, friction and self-collision are the same shape and land with
+ * their milestones; transient contact rows never enter this structure at all
+ * (§5.4 keeps them in a per-particle scratch applied Jacobi-style).
+ *
+ * A leash row is **unary** — one particle against a point — which has two
+ * pleasant consequences. It adds no edge to the particle graph, so the
+ * colouring is untouched by however many leashes a cloth carries. And its
+ * incidence list needs no slot bits: an entry is a row index and nothing else.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothState {
+    /**
+     * Build a cloth from a rest configuration and its rows.
+     *
+     * Colours the particle graph, permutes the particles into colour order,
+     * rewrites the rows into that numbering, builds the incidence lists and
+     * cuts every view from one buffer. Nothing here runs per step.
+     *
+     * Rest lengths and bending weights are taken from the caller rather than
+     * derived, because a proxy bakes them (§11.3) and a rest length is not
+     * always the distance between the rest positions — a garment authored
+     * pre-stretched wants the authored value.
+     *
+     * @param {object} description
+     * @param {Float32Array|number[]} description.position rest positions, 3 per particle
+     * @param {Float32Array|number[]} description.mass_inverse inverse mass per particle, 0 pins
+     * @param {Int32Array|number[]} [description.stretch_particle] endpoint pairs
+     * @param {Float32Array|number[]} [description.stretch_rest] rest length per stretch row
+     * @param {Float32Array|number[]} [description.stretch_stiffness] material stiffness per stretch row
+     * @param {Float32Array|number[]} [description.stretch_force_min] lower clamp per stretch row, default `−Infinity`
+     * @param {Float32Array|number[]} [description.stretch_force_max] upper clamp per stretch row, default `+Infinity`
+     * @param {Int32Array|number[]} [description.bend_particle] stencil quads
+     * @param {Float32Array|number[]} [description.bend_weight] stencil weights, 4 per bend row
+     * @param {Float32Array|number[]} [description.bend_stiffness] material stiffness per bend row
+     * @param {Int32Array|number[]} [description.leash_particle] the particle each leash row holds
+     * @param {Float32Array|number[]} [description.leash_radius] leash radius per row; its length is
+     *   the row count, and the leash centres are written per step rather than here
+     * @returns {ClothState}
+     */
+    static from({ position, mass_inverse, stretch_particle, stretch_rest, stretch_stiffness, stretch_force_min, stretch_force_max, bend_particle, bend_weight, bend_stiffness, leash_particle, leash_radius }: {
+        position: Float32Array | number[];
+        mass_inverse: Float32Array | number[];
+        stretch_particle?: Int32Array | number[];
+        stretch_rest?: Float32Array | number[];
+        stretch_stiffness?: Float32Array | number[];
+        stretch_force_min?: Float32Array | number[];
+        stretch_force_max?: Float32Array | number[];
+        bend_particle?: Int32Array | number[];
+        bend_weight?: Float32Array | number[];
+        bend_stiffness?: Float32Array | number[];
+        leash_particle?: Int32Array | number[];
+        leash_radius?: Float32Array | number[];
+    }): ClothState;
+    /**
+     * The single allocation every view below is cut from.
+     * @type {ArrayBuffer}
+     */
+    buffer: ArrayBuffer;
+    /**
+     * @type {number}
+     */
+    particle_count: number;
+    /**
+     * @type {number}
+     */
+    stretch_count: number;
+    /**
+     * @type {number}
+     */
+    bend_count: number;
+    /**
+     * @type {number}
+     */
+    leash_count: number;
+    /**
+     * @type {number}
+     */
+    colour_count: number;
+    /**
+     * Current particle positions, cloth-local, 3 per particle. This is the
+     * variable the descent moves.
+     * @type {Float32Array}
+     */
+    position: Float32Array;
+    /**
+     * Position at the start of the current substep. `v = (x − x_prev)/h` is
+     * the whole of the integration step (§5.2), which is what makes every
+     * position constraint an implicit velocity constraint for free.
+     * @type {Float32Array}
+     */
+    position_previous: Float32Array;
+    /**
+     * @type {Float32Array}
+     */
+    velocity: Float32Array;
+    /**
+     * The inertial target `y = x + h·v + h²·a_ext`. The mass term of the
+     * per-vertex energy pulls towards this and nothing else; every other force
+     * in the system is a row.
+     * @type {Float32Array}
+     */
+    inertial: Float32Array;
+    /**
+     * Inverse mass, one per particle. **Zero pins the particle**: it is an
+     * immovable anchor that still exerts its rows on its neighbours, and the
+     * sweep skips it entirely rather than dividing by zero.
+     * @type {Float32Array}
+     */
+    mass_inverse: Float32Array;
+    /**
+     * VBD's adaptive-initialisation scale, one per particle, in `[0, 1]`.
+     * Written at integration from how much of the last step's acceleration was
+     * the external one: `1` means the particle was in free fall and the next
+     * step should be seeded with the full `h²·a_ext`, `0` means it was held
+     * (resting on a constraint) and seeding it with gravity would only make
+     * the first iteration undo it. §5.2.
+     * @type {Float32Array}
+     */
+    inertia_blend: Float32Array;
+    /**
+     * Start of each colour in the permuted particle order, `colour_count + 1`
+     * entries. Colour `c` is `[colour_offset[c], colour_offset[c + 1])`.
+     * @type {Int32Array}
+     */
+    colour_offset: Int32Array;
+    /**
+     * Mesh vertex each particle came from, before the colour permutation.
+     * Build-time provenance — the step never reads it.
+     * @type {Int32Array}
+     */
+    source_of_particle: Int32Array;
+    /**
+     * Endpoint particle indices, 2 per stretch row.
+     * @type {Int32Array}
+     */
+    stretch_particle: Int32Array;
+    /**
+     * Rest length `L₀`, one per stretch row.
+     * @type {Float32Array}
+     */
+    stretch_rest: Float32Array;
+    /**
+     * Material stiffness cap, one per stretch row — the value the `β` ramp
+     * drives the penalty towards, subject to the global `k_max`.
+     * @type {Float32Array}
+     */
+    stretch_stiffness: Float32Array;
+    /**
+     * Lower force clamp, one per stretch row. `−Infinity` for the bilateral
+     * fabric row; `0` would make it push-only. §6.
+     * @type {Float32Array}
+     */
+    stretch_force_min: Float32Array;
+    /**
+     * Upper force clamp, one per stretch row. `+Infinity` for the bilateral
+     * fabric row; `0` makes it pull-only, which with `L_max` in
+     * {@link stretch_rest} is exactly §6's strain-limit row.
+     * @type {Float32Array}
+     */
+    stretch_force_max: Float32Array;
+    /**
+     * Augmented-Lagrangian multiplier, one per stretch row, carried across
+     * steps and decayed at warm start.
+     * @type {Float32Array}
+     */
+    stretch_lambda: Float32Array;
+    /**
+     * Penalty stiffness `k_c`, one per stretch row. Ramps by `β·|C|` towards
+     * `min(k_max, stiffness)` and decays by `γ` at warm start.
+     * @type {Float32Array}
+     */
+    stretch_penalty: Float32Array;
+    /**
+     * CSR offsets into {@link stretch_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    stretch_adjacency_offset: Int32Array;
+    /**
+     * Packed `(row << 1) | slot` — the stretch rows touching each particle and
+     * which endpoint it is. Two entries per row.
+     * @type {Int32Array}
+     */
+    stretch_adjacency: Int32Array;
+    /**
+     * Stencil particle indices, 4 per bend row: the two ends of the shared
+     * edge followed by the two opposite wing vertices.
+     * @type {Int32Array}
+     */
+    bend_particle: Int32Array;
+    /**
+     * Quadratic bending stencil weights, 4 per bend row, precomputed from the
+     * rest shape. `C = Σ w_k·x_k` is linear in `x`, so these *are* the
+     * gradient — §6's reason bending costs almost nothing per iteration.
+     * @type {Float32Array}
+     */
+    bend_weight: Float32Array;
+    /**
+     * Material stiffness cap, one per bend row.
+     * @type {Float32Array}
+     */
+    bend_stiffness: Float32Array;
+    /**
+     * Augmented-Lagrangian multiplier, **3 per bend row**. `C` for a bending
+     * stencil is a vector — the discrete mean-curvature vector — so its
+     * multiplier is one too. The row is bilateral in each component, so no
+     * clamp is stored: a bending moment has no sign to be one-sided about.
+     * @type {Float32Array}
+     */
+    bend_lambda: Float32Array;
+    /**
+     * Penalty stiffness `k_c`, one per bend row, shared by the three
+     * components.
+     * @type {Float32Array}
+     */
+    bend_penalty: Float32Array;
+    /**
+     * CSR offsets into {@link bend_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    bend_adjacency_offset: Int32Array;
+    /**
+     * Packed `(row << 2) | slot` — the bend rows touching each particle and
+     * which stencil position it occupies. Four entries per row.
+     * @type {Int32Array}
+     */
+    bend_adjacency: Int32Array;
+    /**
+     * Particle each leash row holds, one per row.
+     * @type {Int32Array}
+     */
+    leash_particle: Int32Array;
+    /**
+     * The point each leash row is measured from, 3 per row, in the cloth's own
+     * local frame.
+     *
+     * **Written per step by the caller, not baked.** A slack row's centre is
+     * the particle's animated position and a tether row's is the anchor's, and
+     * neither is a property of the rest shape. Storing a point per row rather
+     * than an index into a shared table costs three floats a row and removes an
+     * indirection from the inner loop, which is the trade this structure makes
+     * everywhere else too.
+     * @type {Float32Array}
+     */
+    leash_target: Float32Array;
+    /**
+     * Leash radius, one per row: `slack·d_geo,i` for a slack row, `d_geo,i` for
+     * a tether. Zero is a weld (§3.4 — the pin is a leash of no radius, not a
+     * separate row).
+     * @type {Float32Array}
+     */
+    leash_radius: Float32Array;
+    /**
+     * Augmented-Lagrangian multiplier, one per leash row. Every leash row is
+     * hard, so unlike the stretch table there is no soft branch to skip: each
+     * one carries a multiplier and each one is enforced almost exactly at one
+     * iteration.
+     * @type {Float32Array}
+     */
+    leash_lambda: Float32Array;
+    /**
+     * Penalty stiffness `k_c`, one per leash row.
+     * @type {Float32Array}
+     */
+    leash_penalty: Float32Array;
+    /**
+     * CSR offsets into {@link leash_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    leash_adjacency_offset: Int32Array;
+    /**
+     * Row indices — no slot bits, because a leash row has one particle.
+     * @type {Int32Array}
+     */
+    leash_adjacency: Int32Array;
+}
+//# sourceMappingURL=ClothState.d.ts.map

package/src/engine/physics/cloth/solver/ClothState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAoQI;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH;QAf8C,QAAQ,EAA3C,YAAY,GAAC,MAAM,EAAE;QACc,YAAY,EAA/C,YAAY,GAAC,MAAM,EAAE;QACa,gBAAgB,GAAlD,UAAU,GAAC,MAAM,EAAE;QACiB,YAAY,GAAhD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACe,iBAAiB,GAArD,YAAY,GAAC,MAAM,EAAE;QACa,aAAa,GAA/C,UAAU,GAAC,MAAM,EAAE;QACiB,WAAW,GAA/C,YAAY,GAAC,MAAM,EAAE;QACe,cAAc,GAAlD,YAAY,GAAC,MAAM,EAAE;QACa,cAAc,GAAhD,UAAU,GAAC,MAAM,EAAE;QACiB,YAAY,GAAhD,YAAY,GAAC,MAAM,EAAE;QAEnB,UAAU,CAmItB;IA/ZD;;;OAGG;IACH,QAFU,WAAW,CAEP;IAEd;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,mBAFU,YAAY,CAEG;IAEzB;;OAEG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,UAFU,YAAY,CAEN;IAEhB;;;;;OAKG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;;;OAQG;IACH,eAFU,YAAY,CAED;IAErB;;;;OAIG;IACH,eAFU,UAAU,CAEC;IAErB;;;;OAIG;IACH,oBAFU,UAAU,CAEM;IAE1B;;;OAGG;IACH,kBAFU,UAAU,CAEI;IAExB;;;OAGG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;OAIG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;OAIG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;;OAKG;IACH,mBAFU,YAAY,CAEG;IAEzB;;;;OAIG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;OAIG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;OAGG;IACH,0BAFU,UAAU,CAEY;IAEhC;;;;OAIG;IACH,mBAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,eAFU,UAAU,CAEC;IAErB;;;;;OAKG;IACH,aAFU,YAAY,CAEH;IAEnB;;;OAGG;IACH,gBAFU,YAAY,CAEA;IAEtB;;;;;;OAMG;IACH,aAFU,YAAY,CAEH;IAEnB;;;;OAIG;IACH,cAFU,YAAY,CAEF;IAEpB;;;OAGG;IACH,uBAFU,UAAU,CAES;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEE;IAEtB;;;OAGG;IACH,gBAFU,UAAU,CAEE;IAEtB;;;;;;;;;;;OAWG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;OAKG;IACH,cAFU,YAAY,CAEF;IAEpB;;;;;;OAMG;IACH,cAFU,YAAY,CAEF;IAEpB;;;OAGG;IACH,eAFU,YAAY,CAED;IAErB;;;OAGG;IACH,wBAFU,UAAU,CAEU;IAE9B;;;OAGG;IACH,iBAFU,UAAU,CAEG;CAgK1B"}