@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/src/math/Mat4x4.js

@@ -18,6 +18,12 @@
 import { Vec4 } from './Vec4.js';
 
 export class Mat4x4 {
+    /**
+     * Internal token to skip initialization during construction
+     * @private
+     */
+    static UNINITIALIZED = {};
+
     /**
      * Create a new 4x4 matrix
      * Default is identity matrix
@@ -26,6 +32,8 @@ export class Mat4x4 {
     constructor(elements = null) {
         this.data = new Float32Array(16);
 
+        if (elements === Mat4x4.UNINITIALIZED) return;
+
         if (elements) {
             if (elements.length !== 16) {
                 throw new Error('Mat4x4 requires exactly 16 elements');
@@ -45,12 +53,7 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static identity() {
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            0, 0, 0, 1
-        ]);
+        return new Mat4x4();
     }
 
     /**
@@ -58,7 +61,7 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static zero() {
-        return new Mat4x4(new Float32Array(16));
+        return new Mat4x4(Mat4x4.UNINITIALIZED);
     }
 
     /**
@@ -157,24 +160,46 @@ export class Mat4x4 {
     /**
      * Multiply two matrices
      * @param {Mat4x4} m - Right operand
+     * @param {Mat4x4} [target=null] - Optional target matrix to store result
      * @returns {Mat4x4} New matrix = this * m
      */
-    multiply(m) {
+    multiply(m, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
         const a = this.data;
         const b = m.data;
-        const result = new Float32Array(16);
-
-        for (let col = 0; col < 4; col++) {
-            for (let row = 0; row < 4; row++) {
-                let sum = 0;
-                for (let k = 0; k < 4; k++) {
-                    sum += a[k * 4 + row] * b[col * 4 + k];
-                }
-                result[col * 4 + row] = sum;
-            }
-        }
 
-        return new Mat4x4(result);
+        const a00 = a[0], a01 = a[4], a02 = a[8], a03 = a[12];
+        const a10 = a[1], a11 = a[5], a12 = a[9], a13 = a[13];
+        const a20 = a[2], a21 = a[6], a22 = a[10], a23 = a[14];
+        const a30 = a[3], a31 = a[7], a32 = a[11], a33 = a[15];
+
+        const b00 = b[0], b01 = b[4], b02 = b[8], b03 = b[12];
+        const b10 = b[1], b11 = b[5], b12 = b[9], b13 = b[13];
+        const b20 = b[2], b21 = b[6], b22 = b[10], b23 = b[14];
+        const b30 = b[3], b31 = b[7], b32 = b[11], b33 = b[15];
+
+        r[0] = a00 * b00 + a01 * b10 + a02 * b20 + a03 * b30;
+        r[1] = a10 * b00 + a11 * b10 + a12 * b20 + a13 * b30;
+        r[2] = a20 * b00 + a21 * b10 + a22 * b20 + a23 * b30;
+        r[3] = a30 * b00 + a31 * b10 + a32 * b20 + a33 * b30;
+
+        r[4] = a00 * b01 + a01 * b11 + a02 * b21 + a03 * b31;
+        r[5] = a10 * b01 + a11 * b11 + a12 * b21 + a13 * b31;
+        r[6] = a20 * b01 + a21 * b11 + a22 * b21 + a23 * b31;
+        r[7] = a30 * b01 + a31 * b11 + a32 * b21 + a33 * b31;
+
+        r[8] = a00 * b02 + a01 * b12 + a02 * b22 + a03 * b32;
+        r[9] = a10 * b02 + a11 * b12 + a12 * b22 + a13 * b32;
+        r[10] = a20 * b02 + a21 * b12 + a22 * b22 + a23 * b32;
+        r[11] = a30 * b02 + a31 * b12 + a32 * b22 + a33 * b32;
+
+        r[12] = a00 * b03 + a01 * b13 + a02 * b23 + a03 * b33;
+        r[13] = a10 * b03 + a11 * b13 + a12 * b23 + a13 * b33;
+        r[14] = a20 * b03 + a21 * b13 + a22 * b23 + a23 * b33;
+        r[15] = a30 * b03 + a31 * b13 + a32 * b23 + a33 * b33;
+
+        return out;
     }
 
     /**
@@ -183,8 +208,44 @@ export class Mat4x4 {
      * @returns {Mat4x4} this
      */
     multiplyInPlace(m) {
-        const result = this.multiply(m);
-        this.data.set(result.data);
+        const a = this.data;
+        const b = m.data;
+
+        // Cache values to avoid aliasing issues and repeated array access
+        const a00 = a[0], a01 = a[4], a02 = a[8], a03 = a[12];
+        const a10 = a[1], a11 = a[5], a12 = a[9], a13 = a[13];
+        const a20 = a[2], a21 = a[6], a22 = a[10], a23 = a[14];
+        const a30 = a[3], a31 = a[7], a32 = a[11], a33 = a[15];
+
+        const b00 = b[0], b01 = b[4], b02 = b[8], b03 = b[12];
+        const b10 = b[1], b11 = b[5], b12 = b[9], b13 = b[13];
+        const b20 = b[2], b21 = b[6], b22 = b[10], b23 = b[14];
+        const b30 = b[3], b31 = b[7], b32 = b[11], b33 = b[15];
+
+        // Column 0
+        a[0] = a00 * b00 + a01 * b10 + a02 * b20 + a03 * b30;
+        a[1] = a10 * b00 + a11 * b10 + a12 * b20 + a13 * b30;
+        a[2] = a20 * b00 + a21 * b10 + a22 * b20 + a23 * b30;
+        a[3] = a30 * b00 + a31 * b10 + a32 * b20 + a33 * b30;
+
+        // Column 1
+        a[4] = a00 * b01 + a01 * b11 + a02 * b21 + a03 * b31;
+        a[5] = a10 * b01 + a11 * b11 + a12 * b21 + a13 * b31;
+        a[6] = a20 * b01 + a21 * b11 + a22 * b21 + a23 * b31;
+        a[7] = a30 * b01 + a31 * b11 + a32 * b21 + a33 * b31;
+
+        // Column 2
+        a[8] = a00 * b02 + a01 * b12 + a02 * b22 + a03 * b32;
+        a[9] = a10 * b02 + a11 * b12 + a12 * b22 + a13 * b32;
+        a[10] = a20 * b02 + a21 * b12 + a22 * b22 + a23 * b32;
+        a[11] = a30 * b02 + a31 * b12 + a32 * b22 + a33 * b32;
+
+        // Column 3
+        a[12] = a00 * b03 + a01 * b13 + a02 * b23 + a03 * b33;
+        a[13] = a10 * b03 + a11 * b13 + a12 * b23 + a13 * b33;
+        a[14] = a20 * b03 + a21 * b13 + a22 * b23 + a23 * b33;
+        a[15] = a30 * b03 + a31 * b13 + a32 * b23 + a33 * b33;
+
         return this;
     }
 
@@ -202,16 +263,22 @@ export class Mat4x4 {
     /**
      * Transform a Vec4 by this matrix
      * @param {Vec4} v
+     * @param {Vec4} [target=null] - Optional target vector to store result
      * @returns {Vec4} Transformed vector
      */
-    multiplyVec4(v) {
+    multiplyVec4(v, target = null) {
         const m = this.data;
-        return new Vec4(
-            m[0] * v.x + m[4] * v.y + m[8] * v.z + m[12] * v.w,
-            m[1] * v.x + m[5] * v.y + m[9] * v.z + m[13] * v.w,
-            m[2] * v.x + m[6] * v.y + m[10] * v.z + m[14] * v.w,
-            m[3] * v.x + m[7] * v.y + m[11] * v.z + m[15] * v.w
-        );
+        const out = target || new Vec4();
+
+        // Cache components to support aliasing (target === v)
+        const x = v.x, y = v.y, z = v.z, w = v.w;
+
+        out.x = m[0] * x + m[4] * y + m[8] * z + m[12] * w;
+        out.y = m[1] * x + m[5] * y + m[9] * z + m[13] * w;
+        out.z = m[2] * x + m[6] * y + m[10] * z + m[14] * w;
+        out.w = m[3] * x + m[7] * y + m[11] * z + m[15] * w;
+
+        return out;
     }
 
     /**
@@ -253,27 +320,36 @@ export class Mat4x4 {
     /**
      * Add another matrix
      * @param {Mat4x4} m
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New matrix
      */
-    add(m) {
-        const result = new Float32Array(16);
+    add(m, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        const a = this.data;
+        const b = m.data;
+
         for (let i = 0; i < 16; i++) {
-            result[i] = this.data[i] + m.data[i];
+            r[i] = a[i] + b[i];
         }
-        return new Mat4x4(result);
+        return out;
     }
 
     /**
      * Multiply by scalar
      * @param {number} s
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New matrix
      */
-    scale(s) {
-        const result = new Float32Array(16);
+    scale(s, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        const a = this.data;
+
         for (let i = 0; i < 16; i++) {
-            result[i] = this.data[i] * s;
+            r[i] = a[i] * s;
         }
-        return new Mat4x4(result);
+        return out;
     }
 
     /**
@@ -282,12 +358,13 @@ export class Mat4x4 {
      */
     transpose() {
         const m = this.data;
-        return new Mat4x4([
-            m[0], m[4], m[8], m[12],
-            m[1], m[5], m[9], m[13],
-            m[2], m[6], m[10], m[14],
-            m[3], m[7], m[11], m[15]
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = m[0]; r[4] = m[1]; r[8] = m[2]; r[12] = m[3];
+        r[1] = m[4]; r[5] = m[5]; r[9] = m[6]; r[13] = m[7];
+        r[2] = m[8]; r[6] = m[9]; r[10] = m[10]; r[14] = m[11];
+        r[3] = m[12]; r[7] = m[13]; r[11] = m[14]; r[15] = m[15];
+        return out;
     }
 
     /**
@@ -342,7 +419,8 @@ export class Mat4x4 {
      */
     inverse() {
         const m = this.data;
-        const inv = new Float32Array(16);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const inv = out.data;
 
         inv[0] = m[5] * m[10] * m[15] - m[5] * m[11] * m[14] - m[9] * m[6] * m[15] +
             m[9] * m[7] * m[14] + m[13] * m[6] * m[11] - m[13] * m[7] * m[10];
@@ -403,7 +481,7 @@ export class Mat4x4 {
             inv[i] *= invDet;
         }
 
-        return new Mat4x4(inv);
+        return out;
     }
 
     /**
@@ -490,6 +568,122 @@ export class Mat4x4 {
         return new Mat4x4(json.data);
     }
 
+    // ========== IN-PLACE ROTATIONS ==========
+
+    /**
+     * Rotate in XY plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateXY(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a0 = m[i];      // Col 0
+            const a1 = m[i + 4];  // Col 1
+            m[i]     = a0 * c + a1 * s;
+            m[i + 4] = -a0 * s + a1 * c;
+        }
+        return this;
+    }
+
+    /**
+     * Rotate in XZ plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateXZ(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a0 = m[i];      // Col 0
+            const a2 = m[i + 8];  // Col 2
+            m[i]     = a0 * c - a2 * s;
+            m[i + 8] = a0 * s + a2 * c;
+        }
+        return this;
+    }
+
+    /**
+     * Rotate in YZ plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateYZ(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a1 = m[i + 4];  // Col 1
+            const a2 = m[i + 8];  // Col 2
+            m[i + 4] = a1 * c + a2 * s;
+            m[i + 8] = -a1 * s + a2 * c;
+        }
+        return this;
+    }
+
+    /**
+     * Rotate in XW plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateXW(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a0 = m[i];       // Col 0
+            const a3 = m[i + 12];  // Col 3
+            m[i]      = a0 * c + a3 * s;
+            m[i + 12] = -a0 * s + a3 * c;
+        }
+        return this;
+    }
+
+    /**
+     * Rotate in YW plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateYW(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a1 = m[i + 4];   // Col 1
+            const a3 = m[i + 12];  // Col 3
+            m[i + 4]  = a1 * c + a3 * s;
+            m[i + 12] = -a1 * s + a3 * c;
+        }
+        return this;
+    }
+
+    /**
+     * Rotate in ZW plane in place
+     * @param {number} angle
+     * @returns {Mat4x4} this
+     */
+    rotateZW(angle) {
+        const c = Math.cos(angle);
+        const s = Math.sin(angle);
+        const m = this.data;
+
+        for (let i = 0; i < 4; i++) {
+            const a2 = m[i + 8];   // Col 2
+            const a3 = m[i + 12];  // Col 3
+            m[i + 8]  = a2 * c + a3 * s;
+            m[i + 12] = -a2 * s + a3 * c;
+        }
+        return this;
+    }
+
     // ========== ROTATION MATRICES FOR ALL 6 PLANES ==========
 
     /**
@@ -500,12 +694,13 @@ export class Mat4x4 {
     static rotationXY(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, s, 0, 0,
-            -s, c, 0, 0,
-            0, 0, 1, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[1] = s;
+        r[4] = -s; r[5] = c;
+        r[10] = 1;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -516,12 +711,13 @@ export class Mat4x4 {
     static rotationXZ(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, 0, -s, 0,
-            0, 1, 0, 0,
-            s, 0, c, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[2] = -s;
+        r[5] = 1;
+        r[8] = s; r[10] = c;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -532,12 +728,13 @@ export class Mat4x4 {
     static rotationYZ(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, c, s, 0,
-            0, -s, c, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = c; r[6] = s;
+        r[9] = -s; r[10] = c;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -549,12 +746,13 @@ export class Mat4x4 {
     static rotationXW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, 0, 0, s,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            -s, 0, 0, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[3] = s;
+        r[5] = 1;
+        r[10] = 1;
+        r[12] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -565,12 +763,13 @@ export class Mat4x4 {
     static rotationYW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, c, 0, s,
-            0, 0, 1, 0,
-            0, -s, 0, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = c; r[7] = s;
+        r[10] = 1;
+        r[13] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -581,12 +780,13 @@ export class Mat4x4 {
     static rotationZW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, c, s,
-            0, 0, -s, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = 1;
+        r[10] = c; r[11] = s;
+        r[14] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -624,12 +824,12 @@ export class Mat4x4 {
     static rotationFromAngles(angles) {
         let result = Mat4x4.identity();
 
-        if (angles.xy) result = result.multiply(Mat4x4.rotationXY(angles.xy));
-        if (angles.xz) result = result.multiply(Mat4x4.rotationXZ(angles.xz));
-        if (angles.yz) result = result.multiply(Mat4x4.rotationYZ(angles.yz));
-        if (angles.xw) result = result.multiply(Mat4x4.rotationXW(angles.xw));
-        if (angles.yw) result = result.multiply(Mat4x4.rotationYW(angles.yw));
-        if (angles.zw) result = result.multiply(Mat4x4.rotationZW(angles.zw));
+        if (angles.xy) result.rotateXY(angles.xy);
+        if (angles.xz) result.rotateXZ(angles.xz);
+        if (angles.yz) result.rotateYZ(angles.yz);
+        if (angles.xw) result.rotateXW(angles.xw);
+        if (angles.yw) result.rotateYW(angles.yw);
+        if (angles.zw) result.rotateZW(angles.zw);
 
         return result;
     }
@@ -658,12 +858,13 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static uniformScale(s) {
-        return new Mat4x4([
-            s, 0, 0, 0,
-            0, s, 0, 0,
-            0, 0, s, 0,
-            0, 0, 0, s
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = s;
+        r[5] = s;
+        r[10] = s;
+        r[15] = s;
+        return out;
     }
 
     /**
@@ -675,12 +876,13 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static scale(sx, sy, sz, sw = 1) {
-        return new Mat4x4([
-            sx, 0, 0, 0,
-            0, sy, 0, 0,
-            0, 0, sz, 0,
-            0, 0, 0, sw
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = sx;
+        r[5] = sy;
+        r[10] = sz;
+        r[15] = sw;
+        return out;
     }
 
     /**
@@ -696,12 +898,13 @@ export class Mat4x4 {
     static translation(tx, ty, tz, tw = 0) {
         // For true 4D translation, you need 5D homogeneous coordinates
         // This is a placeholder that adds the translation to the W column
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            tx, ty, tz, 1 + tw
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = 1;
+        r[10] = 1;
+        r[12] = tx; r[13] = ty; r[14] = tz; r[15] = 1 + tw;
+        return out;
     }
 }