@vib3code/sdk 2.0.3-canary.91a95f3 → 2.0.3-canary.ae15579

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');
@@ -40,17 +48,25 @@ export class Mat4x4 {
         }
     }
 
+    /**
+     * Reset to identity matrix
+     * @returns {Mat4x4} this
+     */
+    identity() {
+        const d = this.data;
+        d[0] = 1; d[1] = 0; d[2] = 0; d[3] = 0;
+        d[4] = 0; d[5] = 1; d[6] = 0; d[7] = 0;
+        d[8] = 0; d[9] = 0; d[10] = 1; d[11] = 0;
+        d[12] = 0; d[13] = 0; d[14] = 0; d[15] = 1;
+        return this;
+    }
+
     /**
      * Create identity matrix
      * @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 +74,7 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static zero() {
-        return new Mat4x4(new Float32Array(16));
+        return new Mat4x4(Mat4x4.UNINITIALIZED);
     }
 
     /**
@@ -157,24 +173,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 +221,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 +276,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,41 +333,57 @@ 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;
     }
 
     /**
      * Transpose matrix
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New transposed matrix
      */
-    transpose() {
+    transpose(target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        // If target is same as source, use intermediate or careful swap
+        if (target === this) {
+            return this.transposeInPlace();
+        }
+
+        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;
     }
 
     /**
@@ -338,61 +434,85 @@ export class Mat4x4 {
 
     /**
      * Calculate inverse matrix
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4|null} Inverse matrix or null if singular
      */
-    inverse() {
+    inverse(target = null) {
         const m = this.data;
-        const inv = new Float32Array(16);
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const inv = out.data;
+
+        // Note: For in-place inversion (target === this), we need to be careful.
+        // The standard algorithm uses input values for every output cell.
+        // We can check for aliasing or use local variables if we wanted full safety,
+        // but simplest is to compute to temp if aliased, or just computing to the array directly works
+        // IF we cache everything first. But here we are writing to `inv` index by index.
+        // If inv === m, writing inv[0] destroys m[0] which is needed for inv[5] etc.
+        // So aliasing is NOT safe with this direct write approach.
+
+        // Handle aliasing by cloning first if needed, or using temp array.
+        // Since we want performance, let's detect aliasing.
+        let sourceData = m;
+        if (target === this) {
+            // Copy source data to temp array so we can write to 'this.data' safely
+            // We can't avoid allocation entirely in this specific edge case easily without unrolling everything into locals,
+            // which is huge for 4x4 inverse.
+            // Using a static temp buffer would be unsafe for threading/recursion (not an issue in JS single thread usually but still).
+            // Let's just clone the source data for the calculation.
+            sourceData = new Float32Array(m);
+        }
+
+        const s = sourceData;
 
-        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];
+        inv[0] = s[5] * s[10] * s[15] - s[5] * s[11] * s[14] - s[9] * s[6] * s[15] +
+            s[9] * s[7] * s[14] + s[13] * s[6] * s[11] - s[13] * s[7] * s[10];
 
-        inv[4] = -m[4] * m[10] * m[15] + m[4] * m[11] * m[14] + m[8] * m[6] * m[15] -
-            m[8] * m[7] * m[14] - m[12] * m[6] * m[11] + m[12] * m[7] * m[10];
+        inv[4] = -s[4] * s[10] * s[15] + s[4] * s[11] * s[14] + s[8] * s[6] * s[15] -
+            s[8] * s[7] * s[14] - s[12] * s[6] * s[11] + s[12] * s[7] * s[10];
 
-        inv[8] = m[4] * m[9] * m[15] - m[4] * m[11] * m[13] - m[8] * m[5] * m[15] +
-            m[8] * m[7] * m[13] + m[12] * m[5] * m[11] - m[12] * m[7] * m[9];
+        inv[8] = s[4] * s[9] * s[15] - s[4] * s[11] * s[13] - s[8] * s[5] * s[15] +
+            s[8] * s[7] * s[13] + s[12] * s[5] * s[11] - s[12] * s[7] * s[9];
 
-        inv[12] = -m[4] * m[9] * m[14] + m[4] * m[10] * m[13] + m[8] * m[5] * m[14] -
-            m[8] * m[6] * m[13] - m[12] * m[5] * m[10] + m[12] * m[6] * m[9];
+        inv[12] = -s[4] * s[9] * s[14] + s[4] * s[10] * s[13] + s[8] * s[5] * s[14] -
+            s[8] * s[6] * s[13] - s[12] * s[5] * s[10] + s[12] * s[6] * s[9];
 
-        inv[1] = -m[1] * m[10] * m[15] + m[1] * m[11] * m[14] + m[9] * m[2] * m[15] -
-            m[9] * m[3] * m[14] - m[13] * m[2] * m[11] + m[13] * m[3] * m[10];
+        inv[1] = -s[1] * s[10] * s[15] + s[1] * s[11] * s[14] + s[9] * s[2] * s[15] -
+            s[9] * s[3] * s[14] - s[13] * s[2] * s[11] + s[13] * s[3] * s[10];
 
-        inv[5] = m[0] * m[10] * m[15] - m[0] * m[11] * m[14] - m[8] * m[2] * m[15] +
-            m[8] * m[3] * m[14] + m[12] * m[2] * m[11] - m[12] * m[3] * m[10];
+        inv[5] = s[0] * s[10] * s[15] - s[0] * s[11] * s[14] - s[8] * s[2] * s[15] +
+            s[8] * s[3] * s[14] + s[12] * s[2] * s[11] - s[12] * s[3] * s[10];
 
-        inv[9] = -m[0] * m[9] * m[15] + m[0] * m[11] * m[13] + m[8] * m[1] * m[15] -
-            m[8] * m[3] * m[13] - m[12] * m[1] * m[11] + m[12] * m[3] * m[9];
+        inv[9] = -s[0] * s[9] * s[15] + s[0] * s[11] * s[13] + s[8] * s[1] * s[15] -
+            s[8] * s[3] * s[13] - s[12] * s[1] * s[11] + s[12] * s[3] * s[9];
 
-        inv[13] = m[0] * m[9] * m[14] - m[0] * m[10] * m[13] - m[8] * m[1] * m[14] +
-            m[8] * m[2] * m[13] + m[12] * m[1] * m[10] - m[12] * m[2] * m[9];
+        inv[13] = s[0] * s[9] * s[14] - s[0] * s[10] * s[13] - s[8] * s[1] * s[14] +
+            s[8] * s[2] * s[13] + s[12] * s[1] * s[10] - s[12] * s[2] * s[9];
 
-        inv[2] = m[1] * m[6] * m[15] - m[1] * m[7] * m[14] - m[5] * m[2] * m[15] +
-            m[5] * m[3] * m[14] + m[13] * m[2] * m[7] - m[13] * m[3] * m[6];
+        inv[2] = s[1] * s[6] * s[15] - s[1] * s[7] * s[14] - s[5] * s[2] * s[15] +
+            s[5] * s[3] * s[14] + s[13] * s[2] * s[7] - s[13] * s[3] * s[6];
 
-        inv[6] = -m[0] * m[6] * m[15] + m[0] * m[7] * m[14] + m[4] * m[2] * m[15] -
-            m[4] * m[3] * m[14] - m[12] * m[2] * m[7] + m[12] * m[3] * m[6];
+        inv[6] = -s[0] * s[6] * s[15] + s[0] * s[7] * s[14] + s[4] * s[2] * s[15] -
+            s[4] * s[3] * s[14] - s[12] * s[2] * s[7] + s[12] * s[3] * s[6];
 
-        inv[10] = m[0] * m[5] * m[15] - m[0] * m[7] * m[13] - m[4] * m[1] * m[15] +
-            m[4] * m[3] * m[13] + m[12] * m[1] * m[7] - m[12] * m[3] * m[5];
+        inv[10] = s[0] * s[5] * s[15] - s[0] * s[7] * s[13] - s[4] * s[1] * s[15] +
+            s[4] * s[3] * s[13] + s[12] * s[1] * s[7] - s[12] * s[3] * s[5];
 
-        inv[14] = -m[0] * m[5] * m[14] + m[0] * m[6] * m[13] + m[4] * m[1] * m[14] -
-            m[4] * m[2] * m[13] - m[12] * m[1] * m[6] + m[12] * m[2] * m[5];
+        inv[14] = -s[0] * s[5] * s[14] + s[0] * s[6] * s[13] + s[4] * s[1] * s[14] -
+            s[4] * s[2] * s[13] - s[12] * s[1] * s[6] + s[12] * s[2] * s[5];
 
-        inv[3] = -m[1] * m[6] * m[11] + m[1] * m[7] * m[10] + m[5] * m[2] * m[11] -
-            m[5] * m[3] * m[10] - m[9] * m[2] * m[7] + m[9] * m[3] * m[6];
+        inv[3] = -s[1] * s[6] * s[11] + s[1] * s[7] * s[10] + s[5] * s[2] * s[11] -
+            s[5] * s[3] * s[10] - s[9] * s[2] * s[7] + s[9] * s[3] * s[6];
 
-        inv[7] = m[0] * m[6] * m[11] - m[0] * m[7] * m[10] - m[4] * m[2] * m[11] +
-            m[4] * m[3] * m[10] + m[8] * m[2] * m[7] - m[8] * m[3] * m[6];
+        inv[7] = s[0] * s[6] * s[11] - s[0] * s[7] * s[10] - s[4] * s[2] * s[11] +
+            s[4] * s[3] * s[10] + s[8] * s[2] * s[7] - s[8] * s[3] * s[6];
 
-        inv[11] = -m[0] * m[5] * m[11] + m[0] * m[7] * m[9] + m[4] * m[1] * m[11] -
-            m[4] * m[3] * m[9] - m[8] * m[1] * m[7] + m[8] * m[3] * m[5];
+        inv[11] = -s[0] * s[5] * s[11] + s[0] * s[7] * s[9] + s[4] * s[1] * s[11] -
+            s[4] * s[3] * s[9] - s[8] * s[1] * s[7] + s[8] * s[3] * s[5];
 
-        inv[15] = m[0] * m[5] * m[10] - m[0] * m[6] * m[9] - m[4] * m[1] * m[10] +
-            m[4] * m[2] * m[9] + m[8] * m[1] * m[6] - m[8] * m[2] * m[5];
+        inv[15] = s[0] * s[5] * s[10] - s[0] * s[6] * s[9] - s[4] * s[1] * s[10] +
+            s[4] * s[2] * s[9] + s[8] * s[1] * s[6] - s[8] * s[2] * s[5];
 
-        const det = m[0] * inv[0] + m[1] * inv[4] + m[2] * inv[8] + m[3] * inv[12];
+        const det = s[0] * inv[0] + s[1] * inv[4] + s[2] * inv[8] + s[3] * inv[12];
 
         if (Math.abs(det) < 1e-10) {
             return null; // Singular matrix
@@ -403,7 +523,7 @@ export class Mat4x4 {
             inv[i] *= invDet;
         }
 
-        return new Mat4x4(inv);
+        return out;
     }
 
     /**
@@ -490,103 +610,279 @@ 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 ==========
 
     /**
      * Create XY plane rotation matrix (standard Z-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXY(angle) {
+    static rotationXY(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = c; r[1] = s; r[2] = 0; r[3] = 0;
+            r[4] = -s; r[5] = c; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = c; r[1] = s;
+            r[4] = -s; r[5] = c;
+            r[10] = 1;
+            r[15] = 1;
+        }
+        return out;
     }
 
     /**
      * Create XZ plane rotation matrix (standard Y-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXZ(angle) {
+    static rotationXZ(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = c; r[1] = 0; r[2] = -s; r[3] = 0;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = s; r[9] = 0; r[10] = c; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = c; r[2] = -s;
+            r[5] = 1;
+            r[8] = s; r[10] = c;
+            r[15] = 1;
+        }
+        return out;
     }
 
     /**
      * Create YZ plane rotation matrix (standard X-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationYZ(angle) {
+    static rotationYZ(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = c; r[6] = s; r[7] = 0;
+            r[8] = 0; r[9] = -s; r[10] = c; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = 1;
+            r[5] = c; r[6] = s;
+            r[9] = -s; r[10] = c;
+            r[15] = 1;
+        }
+        return out;
     }
 
     /**
      * Create XW plane rotation matrix (4D hyperspace rotation)
      * Creates "inside-out" effect when w approaches viewer
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXW(angle) {
+    static rotationXW(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = c; r[1] = 0; r[2] = 0; r[3] = s;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = -s; r[13] = 0; r[14] = 0; r[15] = c;
+        } else {
+            r[0] = c; r[3] = s;
+            r[5] = 1;
+            r[10] = 1;
+            r[12] = -s; r[15] = c;
+        }
+        return out;
     }
 
     /**
      * Create YW plane rotation matrix (4D hyperspace rotation)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationYW(angle) {
+    static rotationYW(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = c; r[6] = 0; r[7] = s;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = 0; r[13] = -s; r[14] = 0; r[15] = c;
+        } else {
+            r[0] = 1;
+            r[5] = c; r[7] = s;
+            r[10] = 1;
+            r[13] = -s; r[15] = c;
+        }
+        return out;
     }
 
     /**
      * Create ZW plane rotation matrix (4D hyperspace rotation)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationZW(angle) {
+    static rotationZW(angle, target = null) {
         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 = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = c; r[11] = s;
+            r[12] = 0; r[13] = 0; r[14] = -s; r[15] = c;
+        } else {
+            r[0] = 1;
+            r[5] = 1;
+            r[10] = c; r[11] = s;
+            r[14] = -s; r[15] = c;
+        }
+        return out;
     }
 
     /**
@@ -612,24 +908,58 @@ export class Mat4x4 {
      * Create combined rotation matrix from all 6 angles
      * Order: XY, XZ, YZ, XW, YW, ZW
      *
-     * @param {object} angles - Rotation angles
-     * @param {number} [angles.xy=0] - XY plane rotation
-     * @param {number} [angles.xz=0] - XZ plane rotation
-     * @param {number} [angles.yz=0] - YZ plane rotation
-     * @param {number} [angles.xw=0] - XW plane rotation
-     * @param {number} [angles.yw=0] - YW plane rotation
-     * @param {number} [angles.zw=0] - ZW plane rotation
+     * Supports two signatures:
+     * 1. rotationFromAngles(angles, target?)
+     * 2. rotationFromAngles(xy, xz, yz, xw, yw, zw, target?)
+     *
+     * @param {object|number} anglesOrXY - Rotation angles object OR XY angle
+     * @param {number|Mat4x4} [xzOrTarget] - XZ angle OR target matrix
+     * @param {number} [yz=0] - YZ angle
+     * @param {number} [xw=0] - XW angle
+     * @param {number} [yw=0] - YW angle
+     * @param {number} [zw=0] - ZW angle
+     * @param {Mat4x4} [target=null] - Target matrix (if using 6-arg signature)
      * @returns {Mat4x4}
      */
-    static rotationFromAngles(angles) {
-        let result = Mat4x4.identity();
+    static rotationFromAngles(anglesOrXY, xzOrTarget, yz, xw, yw, zw, target) {
+        let xy = 0, xz = 0;
+        let _yz = 0, _xw = 0, _yw = 0, _zw = 0;
+        let out = null;
+
+        if (typeof anglesOrXY === 'number') {
+            // Signature: (xy, xz, yz, xw, yw, zw, target)
+            xy = anglesOrXY;
+            xz = typeof xzOrTarget === 'number' ? xzOrTarget : 0;
+            _yz = yz || 0;
+            _xw = xw || 0;
+            _yw = yw || 0;
+            _zw = zw || 0;
+            out = target || null;
+        } else {
+            // Signature: (angles, target)
+            const angles = anglesOrXY || {};
+            xy = angles.xy || 0;
+            xz = angles.xz || 0;
+            _yz = angles.yz || 0;
+            _xw = angles.xw || 0;
+            _yw = angles.yw || 0;
+            _zw = angles.zw || 0;
+            // The second argument is the target in this case
+            // Use duck typing or check constructor name to avoid circular dependency issues if any
+            if (xzOrTarget && typeof xzOrTarget === 'object' && xzOrTarget.data) {
+                out = xzOrTarget;
+            }
+        }
+
+        const result = out || new Mat4x4(); // Default constructor is identity
+        if (out) result.identity(); // Reset if reused
 
-        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 (xy) result.rotateXY(xy);
+        if (xz) result.rotateXZ(xz);
+        if (_yz) result.rotateYZ(_yz);
+        if (_xw) result.rotateXW(_xw);
+        if (_yw) result.rotateYW(_yw);
+        if (_zw) result.rotateZW(_zw);
 
         return result;
     }
@@ -658,12 +988,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 +1006,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 +1028,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;
     }
 }