@woosh/meep-engine 2.169.2 → 2.169.3

package/src/engine/ecs/transform/Transform64.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Index of the first element of the 4x4 affine matrix inside a {@link Transform64}.
+ *
+ * It is 0, which means a `Transform64` can be passed to any `mat4` function directly,
+ * in place of the matrix - `m4_multiply(out, a_transform, b_transform)` and the like.
+ * @type {number}
+ */
+export const TRANSFORM64_MATRIX_OFFSET: number;
+/**
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_TRANSLATION_OFFSET: number;
+/**
+ * Index of the first element of the rotation quaternion (x, y, z, w) inside a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_ROTATION_OFFSET: number;
+/**
+ * Index of the first element of the scale (x, y, z) inside a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_SCALE_OFFSET: number;
+/**
+ * Number of elements in a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_SIZE: number;
+/**
+ * Position, rotation and scale of an object in 3D space, along with the affine matrix they compose into,
+ * packed into a single `Float64Array`.
+ *
+ * This is the passive counterpart of {@link Transform}. There are no signals, no flags and no change
+ * detection: setting the translation, rotation or scale does **not** refresh {@link matrix}, you call
+ * {@link updateMatrix} yourself once you are done mutating. What you get for that is one allocation of one
+ * contiguous buffer per transform, plain array stores instead of setter dispatch, and double precision
+ * throughout.
+ *
+ * Every element is addressable directly, and the layout is part of the contract, so hot code can read and
+ * write the buffer without going through the accessors:
+ * ```
+ * [ 0..15] matrix, column-major
+ * [16..18] translation  x, y, z
+ * [19..22] rotation     x, y, z, w
+ * [23..25] scale        x, y, z
+ * ```
+ *
+ * @example
+ *  const t = new Transform64();
+ *
+ *  t.setTranslation(1, 2, 3);
+ *  t.setScale(2, 2, 2);
+ *
+ *  // nothing has touched the matrix up to this point
+ *  t.updateMatrix();
+ *
+ * @example
+ *  // reading a component in a hot loop, without the accessors
+ *  const x = t[TRANSFORM64_TRANSLATION_OFFSET];
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64 extends Float64Array {
+    /**
+     * Build a transform from loose components, with {@link matrix} already composed from them
+     * @param {number} translation_x
+     * @param {number} translation_y
+     * @param {number} translation_z
+     * @param {number} rotation_x
+     * @param {number} rotation_y
+     * @param {number} rotation_z
+     * @param {number} rotation_w
+     * @param {number} scale_x
+     * @param {number} scale_y
+     * @param {number} scale_z
+     * @returns {Transform64}
+     */
+    static from(translation_x: number, translation_y: number, translation_z: number, rotation_x: number, rotation_y: number, rotation_z: number, rotation_w: number, scale_x: number, scale_y: number, scale_z: number): Transform64;
+    /**
+     * Build a transform from an affine matrix, see {@link fromMatrix}
+     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
+     * @returns {Transform64}
+     */
+    static fromMatrix(m4: number[] | Float32Array | Float64Array | mat4): Transform64;
+    /**
+     * Build a transform from its JSON form, see {@link fromJSON}
+     * @param json
+     * @returns {Transform64}
+     */
+    static fromJSON(json: any): Transform64;
+    /**
+     * Arrays derived from a transform (`slice`, `subarray`, `map`, ...) are plain `Float64Array`s
+     * @returns {Float64ArrayConstructor}
+     */
+    static get [Symbol.species](): Float64ArrayConstructor;
+    constructor();
+    /**
+     * Affine transform matrix, column-major.
+     *
+     * Unlike {@link Transform}, this is not maintained for you - it holds whatever {@link updateMatrix},
+     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set a component.
+     *
+     * NOTE: the returned array is a live view over the transform's own buffer, but a freshly allocated
+     * view on every access. Hold on to it rather than reading this property in a loop, or index the
+     * transform itself - the matrix starts at element 0.
+     * @returns {Float64Array}
+     */
+    get matrix(): Float64Array;
+    /**
+     * Reads 3 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set translation(arg: Float64Array);
+    /**
+     * Position in 3D space.
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get translation(): Float64Array;
+    get translation_x(): number;
+    get translation_y(): number;
+    get translation_z(): number;
+    /**
+     * Does not update {@link matrix}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setTranslation(x: number, y: number, z: number): void;
+    /**
+     * Reads 4 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} q
+     */
+    set rotation(arg: Float64Array);
+    /**
+     * Orientation, as a quaternion (x, y, z, w).
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get rotation(): Float64Array;
+    get rotation_x(): number;
+    get rotation_y(): number;
+    get rotation_z(): number;
+    get rotation_w(): number;
+    /**
+     * The quaternion is expected to be of unit length, nothing here normalizes it.
+     * Does not update {@link matrix}.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} w
+     */
+    setRotation(x: number, y: number, z: number, w: number): void;
+    /**
+     * Reads 3 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set scale(arg: Float64Array);
+    /**
+     * Size along each local axis.
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get scale(): Float64Array;
+    get scale_x(): number;
+    get scale_y(): number;
+    get scale_z(): number;
+    /**
+     * Does not update {@link matrix}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * Uniform scale. Does not update {@link matrix}.
+     * @param {number} s
+     */
+    setScaleScalar(s: number): void;
+    /**
+     * Write {@link matrix} from the current {@link translation}, {@link rotation} and {@link scale}.
+     * Nothing calls this for you, and until you do, the matrix is whatever it was before.
+     */
+    updateMatrix(): void;
+    /**
+     * Write {@link translation}, {@link rotation} and {@link scale} from the current {@link matrix}.
+     * The inverse of {@link updateMatrix}; call it after writing the matrix in place.
+     *
+     * A matrix carrying shear cannot be described by a translation, a rotation and a scale, so shear is
+     * dropped from the components. It survives in {@link matrix} until the next {@link updateMatrix}.
+     */
+    updateComponents(): void;
+    /**
+     * Set the whole transform, matrix and components both, from an affine matrix.
+     * See {@link updateComponents} for how shear is handled.
+     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
+     * @returns {this}
+     */
+    fromMatrix(m4: number[] | Float32Array | Float64Array | mat4): this;
+    /**
+     * Post-multiplication, `this = this * other`. See {@link multiplyTransforms}.
+     * @param {Transform64} other
+     * @returns {this}
+     */
+    multiply(other: Transform64): this;
+    /**
+     * Multiply two transforms, writing the result into this one. Either operand may be this transform.
+     *
+     * Both operands are read through their matrices, not their components, so a stale matrix on either
+     * side produces a stale result - {@link updateMatrix} them first if you have been setting components.
+     * Both the matrix and the components of the result are left up to date.
+     *
+     * @param {Transform64} a
+     * @param {Transform64} b
+     * @returns {this}
+     */
+    multiplyTransforms(a: Transform64, b: Transform64): this;
+    /**
+     * Reset to the identity transform, matrix included:
+     *      - translation: [0,0,0]
+     *      - rotation:    [0,0,0,1]
+     *      - scale:       [1,1,1]
+     */
+    makeIdentity(): void;
+    0: number;
+    5: number;
+    10: number;
+    15: number;
+    /**
+     * Whether the translation is exactly [0,0,0], the rotation exactly [0,0,0,1] and the scale exactly
+     * [1,1,1]. Says nothing about {@link matrix}, which only agrees after an {@link updateMatrix}.
+     * @returns {boolean}
+     */
+    isIdentity(): boolean;
+    /**
+     * Set this transform to match `other`, matrix included. The `other` is left unchanged.
+     * @param {Transform64} other
+     */
+    copy(other: Transform64): void;
+    /**
+     * A new transform equal to this one
+     * @returns {Transform64}
+     */
+    clone(): Transform64;
+    /**
+     * Strict equality across the whole transform, {@link matrix} included. Two transforms whose components
+     * match but whose matrices do not - because one of them is stale - are not equal.
+     * @param {Transform64} other
+     * @returns {boolean}
+     */
+    equals(other: Transform64): boolean;
+    /**
+     * Only the translation contributes, for speed - in most applications it is what varies the most.
+     *
+     * This is weaker than {@link equals}: transforms differing only in rotation, scale or matrix collide.
+     * Legal for a hash, but a poor key if your set varies along those axes alone.
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * Read the components from `{translation, rotation, scale}`, each of them optional and defaulting to
+     * identity. Composes {@link matrix} from the result.
+     *
+     * NOTE: the translation is keyed `translation`, where {@link Transform} keys the same thing
+     * `position`. The two JSON forms are not interchangeable.
+     * @param json
+     */
+    fromJSON(json: any): void;
+    /**
+     * Writes out the components only; {@link matrix} is recomposed from them on the way back in
+     * @returns {{translation:{x:number,y:number,z:number}, rotation:{x:number,y:number,z:number,w:number}, scale:{x:number,y:number,z:number}}}
+     */
+    toJSON(): {
+        translation: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        };
+        scale: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    /**
+     * Enables a fast type check, without having to import the class separately.
+     * @readonly
+     * @type {boolean}
+     * @example
+     *  if(t.isTransform64){
+     *      // t is a Transform64, do stuff
+     *  }
+     */
+    readonly isTransform64: boolean;
+}
+export namespace Transform64 {
+    let typeName: string;
+}
+//# sourceMappingURL=Transform64.d.ts.map

package/src/engine/ecs/transform/Transform64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,0CAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,uCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IA2bI;;;;;;;;;;;;;OAaG;IACH,2BAZW,MAAM,iBACN,MAAM,iBACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,GACJ,WAAW,CAgBvB;IAED;;;;OAIG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,OAAK,GACrC,WAAW,CAQvB;IAED;;;;OAIG;IACH,4BAFa,WAAW,CAQvB;IA/eD;;;OAGG;IACH,uDAIC;IAED,cAIC;IAED;;;;;;;;;;OAUG;IACH,2BAEC;IAWD;;;OAGG;IACH,mCAEC;IAfD;;;;OAIG;IACH,gCAEC;IAUD,4BAEC;IAED,4BAEC;IAED,4BAEC;IAED;;;;;OAKG;IACH,kBAJW,MAAM,KACN,MAAM,KACN,MAAM,QAUhB;IAWD;;;OAGG;IACH,gCAEC;IAfD;;;;OAIG;IACH,6BAEC;IAUD,yBAEC;IAED,yBAEC;IAED,yBAEC;IAED,yBAEC;IAED;;;;;;;OAOG;IACH,eALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAYhB;IAWD;;;OAGG;IACH,6BAEC;IAfD;;;;OAIG;IACH,0BAEC;IAUD,sBAEC;IAED,sBAEC;IAED,sBAEC;IAED;;;;;OAKG;IACH,YAJW,MAAM,KACN,MAAM,KACN,MAAM,QAUhB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,qBAgBC;IAED;;;;;;OAMG;IACH,yBAOC;IAED;;;;;OAKG;IACH,eAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,OAAK,GACrC,IAAI,CAWhB;IAED;;;;OAIG;IACH,gBAHW,WAAW,GACT,IAAI,CAIhB;IAED;;;;;;;;;;OAUG;IACH,sBAJW,WAAW,KACX,WAAW,GACT,IAAI,CAYhB;IAED;;;;;OAKG;IACH,qBAcC;IAVG,UAAW;IACX,UAAW;IACX,WAAY;IACZ,WAAY;IAShB;;;;OAIG;IACH,cAFa,OAAO,CAanB;IAED;;;OAGG;IACH,YAFW,WAAW,QAIrB;IAED;;;OAGG;IACH,SAFa,WAAW,CAQvB;IAED;;;;;OAKG;IACH,cAHW,WAAW,GACT,OAAO,CAInB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAwBlB;IAED;;;;;;;OAOG;IACH,0BA0BC;IAED;;;OAGG;IACH,UAFa;QAAC,WAAW,EAAC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC,CAAC;QAAC,QAAQ,EAAC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC,CAAC;QAAC,KAAK,EAAC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC,CAAA;KAAC,CAqB1I;IA2EL;;;;;;;;OAQG;IACH,wBANU,OAAO,CAMkB;CAjBlC;;kBAIS,MAAM"}