@vib3code/sdk 2.0.3-canary.590fbae → 2.0.3-canary.69d53b3

package/src/math/Vec4.js

@@ -2,7 +2,8 @@
  * Vec4 - 4D Vector Class
  *
  * Represents a point or direction in 4-dimensional space.
- * Uses Float32Array for GPU compatibility and potential SIMD optimization.
+ * Uses plain numeric properties internally for minimal allocation overhead.
+ * GPU-compatible Float32Array created on demand via toFloat32Array().
  *
  * @example
  * const v = new Vec4(1, 2, 3, 0.5);
@@ -19,26 +20,66 @@ export class Vec4 {
      * @param {number} w - W component (4th dimension)
      */
     constructor(x = 0, y = 0, z = 0, w = 0) {
-        // Use Float32Array for GPU compatibility
-        this.data = new Float32Array(4);
-        this.data[0] = x;
-        this.data[1] = y;
-        this.data[2] = z;
-        this.data[3] = w;
+        this._x = x;
+        this._y = y;
+        this._z = z;
+        this._w = w;
     }
 
-    // Property accessors for readability
-    get x() { return this.data[0]; }
-    set x(v) { this.data[0] = v; }
+    // Property accessors
+    get x() { return this._x; }
+    set x(v) { this._x = v; }
 
-    get y() { return this.data[1]; }
-    set y(v) { this.data[1] = v; }
+    get y() { return this._y; }
+    set y(v) { this._y = v; }
 
-    get z() { return this.data[2]; }
-    set z(v) { this.data[2] = v; }
+    get z() { return this._z; }
+    set z(v) { this._z = v; }
 
-    get w() { return this.data[3]; }
-    set w(v) { this.data[3] = v; }
+    get w() { return this._w; }
+    set w(v) { this._w = v; }
+
+    /**
+     * Backward-compatible .data getter.
+     * Returns a Float32Array snapshot of current values.
+     * Note: writes to the returned array do NOT propagate back.
+     * Use setComponent(index, value) for index-based mutation.
+     * @returns {Float32Array}
+     */
+    get data() {
+        return new Float32Array([this._x, this._y, this._z, this._w]);
+    }
+
+    /**
+     * Set a component by index (0=x, 1=y, 2=z, 3=w)
+     * @param {number} index - Component index (0-3)
+     * @param {number} value - New value
+     * @returns {Vec4} this
+     */
+    setComponent(index, value) {
+        switch (index) {
+            case 0: this._x = value; break;
+            case 1: this._y = value; break;
+            case 2: this._z = value; break;
+            case 3: this._w = value; break;
+        }
+        return this;
+    }
+
+    /**
+     * Get a component by index (0=x, 1=y, 2=z, 3=w)
+     * @param {number} index - Component index (0-3)
+     * @returns {number}
+     */
+    getComponent(index) {
+        switch (index) {
+            case 0: return this._x;
+            case 1: return this._y;
+            case 2: return this._z;
+            case 3: return this._w;
+            default: return 0;
+        }
+    }
 
     /**
      * Create a Vec4 from an array
@@ -54,7 +95,7 @@ export class Vec4 {
      * @returns {Vec4}
      */
     clone() {
-        return new Vec4(this.x, this.y, this.z, this.w);
+        return new Vec4(this._x, this._y, this._z, this._w);
     }
 
     /**
@@ -63,10 +104,10 @@ export class Vec4 {
      * @returns {Vec4} this (for chaining)
      */
     copy(v) {
-        this.data[0] = v.data[0];
-        this.data[1] = v.data[1];
-        this.data[2] = v.data[2];
-        this.data[3] = v.data[3];
+        this._x = v._x;
+        this._y = v._y;
+        this._z = v._z;
+        this._w = v._w;
         return this;
     }
 
@@ -79,24 +120,32 @@ export class Vec4 {
      * @returns {Vec4} this
      */
     set(x, y, z, w) {
-        this.data[0] = x;
-        this.data[1] = y;
-        this.data[2] = z;
-        this.data[3] = w;
+        this._x = x;
+        this._y = y;
+        this._z = z;
+        this._w = w;
         return this;
     }
 
     /**
-     * Add another vector (immutable)
+     * Add another vector (immutable unless target provided)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    add(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    add(v, target = null) {
+        if (target) {
+            target._x = this._x + v._x;
+            target._y = this._y + v._y;
+            target._z = this._z + v._z;
+            target._w = this._w + v._w;
+            return target;
+        }
         return new Vec4(
-            this.x + v.x,
-            this.y + v.y,
-            this.z + v.z,
-            this.w + v.w
+            this._x + v._x,
+            this._y + v._y,
+            this._z + v._z,
+            this._w + v._w
         );
     }
 
@@ -106,24 +155,32 @@ export class Vec4 {
      * @returns {Vec4} this
      */
     addInPlace(v) {
-        this.data[0] += v.data[0];
-        this.data[1] += v.data[1];
-        this.data[2] += v.data[2];
-        this.data[3] += v.data[3];
+        this._x += v._x;
+        this._y += v._y;
+        this._z += v._z;
+        this._w += v._w;
         return this;
     }
 
     /**
-     * Subtract another vector (immutable)
+     * Subtract another vector (immutable unless target provided)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    sub(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    sub(v, target = null) {
+        if (target) {
+            target._x = this._x - v._x;
+            target._y = this._y - v._y;
+            target._z = this._z - v._z;
+            target._w = this._w - v._w;
+            return target;
+        }
         return new Vec4(
-            this.x - v.x,
-            this.y - v.y,
-            this.z - v.z,
-            this.w - v.w
+            this._x - v._x,
+            this._y - v._y,
+            this._z - v._z,
+            this._w - v._w
         );
     }
 
@@ -133,24 +190,32 @@ export class Vec4 {
      * @returns {Vec4} this
      */
     subInPlace(v) {
-        this.data[0] -= v.data[0];
-        this.data[1] -= v.data[1];
-        this.data[2] -= v.data[2];
-        this.data[3] -= v.data[3];
+        this._x -= v._x;
+        this._y -= v._y;
+        this._z -= v._z;
+        this._w -= v._w;
         return this;
     }
 
     /**
-     * Multiply by scalar (immutable)
+     * Multiply by scalar (immutable unless target provided)
      * @param {number} s
-     * @returns {Vec4} New vector
-     */
-    scale(s) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    scale(s, target = null) {
+        if (target) {
+            target._x = this._x * s;
+            target._y = this._y * s;
+            target._z = this._z * s;
+            target._w = this._w * s;
+            return target;
+        }
         return new Vec4(
-            this.x * s,
-            this.y * s,
-            this.z * s,
-            this.w * s
+            this._x * s,
+            this._y * s,
+            this._z * s,
+            this._w * s
         );
     }
 
@@ -160,33 +225,49 @@ export class Vec4 {
      * @returns {Vec4} this
      */
     scaleInPlace(s) {
-        this.data[0] *= s;
-        this.data[1] *= s;
-        this.data[2] *= s;
-        this.data[3] *= s;
+        this._x *= s;
+        this._y *= s;
+        this._z *= s;
+        this._w *= s;
         return this;
     }
 
     /**
      * Component-wise multiply (Hadamard product)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    multiply(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    multiply(v, target = null) {
+        if (target) {
+            target._x = this._x * v._x;
+            target._y = this._y * v._y;
+            target._z = this._z * v._z;
+            target._w = this._w * v._w;
+            return target;
+        }
         return new Vec4(
-            this.x * v.x,
-            this.y * v.y,
-            this.z * v.z,
-            this.w * v.w
+            this._x * v._x,
+            this._y * v._y,
+            this._z * v._z,
+            this._w * v._w
         );
     }
 
     /**
-     * Negate vector (immutable)
-     * @returns {Vec4} New vector
+     * Negate vector (immutable unless target provided)
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
      */
-    negate() {
-        return new Vec4(-this.x, -this.y, -this.z, -this.w);
+    negate(target = null) {
+        if (target) {
+            target._x = -this._x;
+            target._y = -this._y;
+            target._z = -this._z;
+            target._w = -this._w;
+            return target;
+        }
+        return new Vec4(-this._x, -this._y, -this._z, -this._w);
     }
 
     /**
@@ -194,10 +275,10 @@ export class Vec4 {
      * @returns {Vec4} this
      */
     negateInPlace() {
-        this.data[0] = -this.data[0];
-        this.data[1] = -this.data[1];
-        this.data[2] = -this.data[2];
-        this.data[3] = -this.data[3];
+        this._x = -this._x;
+        this._y = -this._y;
+        this._z = -this._z;
+        this._w = -this._w;
         return this;
     }
 
@@ -207,7 +288,7 @@ export class Vec4 {
      * @returns {number}
      */
     dot(v) {
-        return this.x * v.x + this.y * v.y + this.z * v.z + this.w * v.w;
+        return this._x * v._x + this._y * v._y + this._z * v._z + this._w * v._w;
     }
 
     /**
@@ -215,7 +296,7 @@ export class Vec4 {
      * @returns {number}
      */
     lengthSquared() {
-        return this.x * this.x + this.y * this.y + this.z * this.z + this.w * this.w;
+        return this._x * this._x + this._y * this._y + this._z * this._z + this._w * this._w;
     }
 
     /**
@@ -245,15 +326,23 @@ export class Vec4 {
     }
 
     /**
-     * Normalize to unit length (immutable)
-     * @returns {Vec4} New normalized vector
+     * Normalize to unit length (immutable unless target provided)
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New normalized vector or target
      */
-    normalize() {
+    normalize(target = null) {
         const len = this.length();
         if (len < 1e-10) {
+            if (target) {
+                target._x = 0;
+                target._y = 0;
+                target._z = 0;
+                target._w = 0;
+                return target;
+            }
             return new Vec4(0, 0, 0, 0);
         }
-        return this.scale(1 / len);
+        return this.scale(1 / len, target);
     }
 
     /**
@@ -273,14 +362,22 @@ export class Vec4 {
      * Linear interpolation to another vector
      * @param {Vec4} v - Target vector
      * @param {number} t - Interpolation factor (0-1)
-     * @returns {Vec4} New interpolated vector
-     */
-    lerp(v, t) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New interpolated vector or target
+     */
+    lerp(v, t, target = null) {
+        if (target) {
+            target._x = this._x + (v._x - this._x) * t;
+            target._y = this._y + (v._y - this._y) * t;
+            target._z = this._z + (v._z - this._z) * t;
+            target._w = this._w + (v._w - this._w) * t;
+            return target;
+        }
         return new Vec4(
-            this.x + (v.x - this.x) * t,
-            this.y + (v.y - this.y) * t,
-            this.z + (v.z - this.z) * t,
-            this.w + (v.w - this.w) * t
+            this._x + (v._x - this._x) * t,
+            this._y + (v._y - this._y) * t,
+            this._z + (v._z - this._z) * t,
+            this._w + (v._w - this._w) * t
         );
     }
 
@@ -292,10 +389,10 @@ export class Vec4 {
      */
     equals(v, epsilon = 1e-6) {
         return (
-            Math.abs(this.x - v.x) < epsilon &&
-            Math.abs(this.y - v.y) < epsilon &&
-            Math.abs(this.z - v.z) < epsilon &&
-            Math.abs(this.w - v.w) < epsilon
+            Math.abs(this._x - v._x) < epsilon &&
+            Math.abs(this._y - v._y) < epsilon &&
+            Math.abs(this._z - v._z) < epsilon &&
+            Math.abs(this._w - v._w) < epsilon
         );
     }
 
@@ -321,10 +418,10 @@ export class Vec4 {
             d = options.distance ?? options.d ?? 2;
         }
         const epsilon = options.epsilon ?? 1e-5;
-        const denom = d - this.w;
+        const denom = d - this._w;
         const clamped = Math.abs(denom) < epsilon ? (denom >= 0 ? epsilon : -epsilon) : denom;
         const scale = 1 / clamped;
-        return new Vec4(this.x * scale, this.y * scale, this.z * scale, 0);
+        return new Vec4(this._x * scale, this._y * scale, this._z * scale, 0);
     }
 
     /**
@@ -335,10 +432,10 @@ export class Vec4 {
      */
     projectStereographic(options = {}) {
         const epsilon = options.epsilon ?? 1e-5;
-        const denom = 1 - this.w;
+        const denom = 1 - this._w;
         const clamped = Math.abs(denom) < epsilon ? (denom >= 0 ? epsilon : -epsilon) : denom;
         const scale = 1 / clamped;
-        return new Vec4(this.x * scale, this.y * scale, this.z * scale, 0);
+        return new Vec4(this._x * scale, this._y * scale, this._z * scale, 0);
     }
 
     /**
@@ -347,7 +444,7 @@ export class Vec4 {
      * @returns {Vec4} Projected point (w component is 0)
      */
     projectOrthographic() {
-        return new Vec4(this.x, this.y, this.z, 0);
+        return new Vec4(this._x, this._y, this._z, 0);
     }
 
     /**
@@ -355,7 +452,7 @@ export class Vec4 {
      * @returns {number[]}
      */
     toArray() {
-        return [this.x, this.y, this.z, this.w];
+        return [this._x, this._y, this._z, this._w];
     }
 
     /**
@@ -363,7 +460,7 @@ export class Vec4 {
      * @returns {Float32Array}
      */
     toFloat32Array() {
-        return new Float32Array(this.data);
+        return new Float32Array([this._x, this._y, this._z, this._w]);
     }
 
     /**
@@ -371,7 +468,7 @@ export class Vec4 {
      * @returns {number[]}
      */
     toArray3() {
-        return [this.x, this.y, this.z];
+        return [this._x, this._y, this._z];
     }
 
     /**
@@ -380,7 +477,7 @@ export class Vec4 {
      * @returns {string}
      */
     toString(precision = 3) {
-        return `Vec4(${this.x.toFixed(precision)}, ${this.y.toFixed(precision)}, ${this.z.toFixed(precision)}, ${this.w.toFixed(precision)})`;
+        return `Vec4(${this._x.toFixed(precision)}, ${this._y.toFixed(precision)}, ${this._z.toFixed(precision)}, ${this._w.toFixed(precision)})`;
     }
 
     /**
@@ -388,7 +485,7 @@ export class Vec4 {
      * @returns {object}
      */
     toJSON() {
-        return { x: this.x, y: this.y, z: this.z, w: this.w };
+        return { x: this._x, y: this._y, z: this._z, w: this._w };
     }
 
     // Static factory methods for common vectors

package/src/scene/Node4D.js

@@ -500,29 +500,74 @@ export class Node4D {
      * @private
      */
     _updateLocalMatrix() {
-        // Start with identity
-        this._localMatrix = Mat4x4.identity();
+        // Ensure matrix exists
+        if (!this._localMatrix) {
+            this._localMatrix = new Mat4x4();
+        }
+
+        const m = this._localMatrix.data;
+        const s = this._scale;
+        const p = this._position;
+
+        // 1. Write rotation directly to local matrix (No allocation)
+        this._rotation.toMatrix(m);
+
+        // 2. Apply scale (Diagonal matrix multiplication on the right)
+        // M = M * S
+        // Columns of M are scaled by s.x, s.y, s.z, s.w
+
+        // Col 0
+        m[0] *= s.x; m[1] *= s.x; m[2] *= s.x; m[3] *= s.x;
+        // Col 1
+        m[4] *= s.y; m[5] *= s.y; m[6] *= s.y; m[7] *= s.y;
+        // Col 2
+        m[8] *= s.z; m[9] *= s.z; m[10] *= s.z; m[11] *= s.z;
+        // Col 3
+        m[12] *= s.w; m[13] *= s.w; m[14] *= s.w; m[15] *= s.w;
+
+        // 3. Apply translation (Matrix multiplication on the left)
+        // M = T * M
+        // T is standard 3D translation:
+        // [ 1 0 0 px ]
+        // [ 0 1 0 py ]
+        // [ 0 0 1 pz ]
+        // [ 0 0 0 1  ]
+        //
+        // Row 0 += px * Row 3
+        // Row 1 += py * Row 3
+        // Row 2 += pz * Row 3
+
+        const px = p.x;
+        const py = p.y;
+        const pz = p.z;
+
+        // Row 3 elements of M (which are used in the calculation)
+        const m3 = m[3];
+        const m7 = m[7];
+        const m11 = m[11];
+        const m15 = m[15];
+
+        if (px !== 0) {
+            m[0] += px * m3;
+            m[4] += px * m7;
+            m[8] += px * m11;
+            m[12] += px * m15;
+        }
+
+        if (py !== 0) {
+            m[1] += py * m3;
+            m[5] += py * m7;
+            m[9] += py * m11;
+            m[13] += py * m15;
+        }
+
+        if (pz !== 0) {
+            m[2] += pz * m3;
+            m[6] += pz * m7;
+            m[10] += pz * m11;
+            m[14] += pz * m15;
+        }
 
-        // Apply scale
-        const scaleMatrix = Mat4x4.identity();
-        scaleMatrix.set(0, 0, this._scale.x);
-        scaleMatrix.set(1, 1, this._scale.y);
-        scaleMatrix.set(2, 2, this._scale.z);
-        scaleMatrix.set(3, 3, this._scale.w);
-
-        // Apply rotation (toMatrix returns Float32Array, wrap in Mat4x4)
-        const rotationMatrix = new Mat4x4(this._rotation.toMatrix());
-
-        // Apply translation (in 4D, translation is stored in last column, keep [3,3]=1)
-        const translationMatrix = Mat4x4.identity();
-        translationMatrix.set(0, 3, this._position.x);
-        translationMatrix.set(1, 3, this._position.y);
-        translationMatrix.set(2, 3, this._position.z);
-        // Note: position.w is the 4th spatial coordinate, handled separately
-        // Matrix[3,3] must remain 1 for proper transformation
-
-        // Compose: T * R * S
-        this._localMatrix = translationMatrix.multiply(rotationMatrix).multiply(scaleMatrix);
         this._localDirty = false;
     }
 
@@ -535,10 +580,15 @@ export class Node4D {
             this._updateLocalMatrix();
         }
 
+        // Ensure matrix exists
+        if (!this._worldMatrix) {
+            this._worldMatrix = new Mat4x4();
+        }
+
         if (this._parent) {
-            this._worldMatrix = this._parent.worldMatrix.multiply(this._localMatrix);
+            this._parent.worldMatrix.multiply(this._localMatrix, this._worldMatrix);
         } else {
-            this._worldMatrix = this._localMatrix.clone();
+            this._worldMatrix.copy(this._localMatrix);
         }
 
         this._worldDirty = false;