@babylonjs/core 5.28.0 → 5.30.0

package/Maths/math.vector.js

@@ -70,7 +70,7 @@ export class Vector2 {
      * Example Playground https://playground.babylonjs.com/#QYBWV4#39
      * @param array defines the destination array
      * @param index defines the offset in the destination array
-     * @returns the current Vector3
+     * @returns the current Vector2
      */
     fromArray(array, index = 0) {
         Vector2.FromArrayToRef(array, index, this);
@@ -126,19 +126,19 @@ export class Vector2 {
      * @returns a new Vector2 set with the addition of the current Vector2 and the given one coordinates
      */
     add(otherVector) {
-        return new Vector2(this.x + otherVector.x, this.y + otherVector.y);
+        return new this.constructor(this.x + otherVector.x, this.y + otherVector.y);
     }
     /**
      * Sets the "result" coordinates with the addition of the current Vector2 and the given one coordinates
      * Example Playground https://playground.babylonjs.com/#QYBWV4#12
      * @param otherVector defines the other vector
      * @param result defines the target vector
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     addToRef(otherVector, result) {
         result.x = this.x + otherVector.x;
         result.y = this.y + otherVector.y;
-        return this;
+        return result;
     }
     /**
      * Set the Vector2 coordinates by adding the given Vector2 coordinates
@@ -158,7 +158,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     addVector3(otherVector) {
-        return new Vector2(this.x + otherVector.x, this.y + otherVector.y);
+        return new this.constructor(this.x + otherVector.x, this.y + otherVector.y);
     }
     /**
      * Gets a new Vector2 set with the subtracted coordinates of the given one from the current Vector2
@@ -167,19 +167,19 @@ export class Vector2 {
      * @returns a new Vector2
      */
     subtract(otherVector) {
-        return new Vector2(this.x - otherVector.x, this.y - otherVector.y);
+        return new this.constructor(this.x - otherVector.x, this.y - otherVector.y);
     }
     /**
      * Sets the "result" coordinates with the subtraction of the given one from the current Vector2 coordinates.
      * Example Playground https://playground.babylonjs.com/#QYBWV4#63
      * @param otherVector defines the other vector
      * @param result defines the target vector
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     subtractToRef(otherVector, result) {
         result.x = this.x - otherVector.x;
         result.y = this.y - otherVector.y;
-        return this;
+        return result;
     }
     /**
      * Sets the current Vector2 coordinates by subtracting from it the given one coordinates
@@ -210,19 +210,19 @@ export class Vector2 {
      * @returns a new Vector2
      */
     multiply(otherVector) {
-        return new Vector2(this.x * otherVector.x, this.y * otherVector.y);
+        return new this.constructor(this.x * otherVector.x, this.y * otherVector.y);
     }
     /**
      * Sets "result" coordinates with the multiplication of the current Vector2 and the given one coordinates
      * Example Playground https://playground.babylonjs.com/#QYBWV4#44
      * @param otherVector defines the other vector
      * @param result defines the target vector
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     multiplyToRef(otherVector, result) {
         result.x = this.x * otherVector.x;
         result.y = this.y * otherVector.y;
-        return this;
+        return result;
     }
     /**
      * Gets a new Vector2 set with the Vector2 coordinates multiplied by the given floats
@@ -232,7 +232,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     multiplyByFloats(x, y) {
-        return new Vector2(this.x * x, this.y * y);
+        return new this.constructor(this.x * x, this.y * y);
     }
     /**
      * Returns a new Vector2 set with the Vector2 coordinates divided by the given one coordinates
@@ -241,19 +241,19 @@ export class Vector2 {
      * @returns a new Vector2
      */
     divide(otherVector) {
-        return new Vector2(this.x / otherVector.x, this.y / otherVector.y);
+        return new this.constructor(this.x / otherVector.x, this.y / otherVector.y);
     }
     /**
      * Sets the "result" coordinates with the Vector2 divided by the given one coordinates
      * Example Playground https://playground.babylonjs.com/#QYBWV4#30
      * @param otherVector defines the other vector
      * @param result defines the target vector
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     divideToRef(otherVector, result) {
         result.x = this.x / otherVector.x;
         result.y = this.y / otherVector.y;
-        return this;
+        return result;
     }
     /**
      * Divides the current Vector2 coordinates by the given ones
@@ -270,7 +270,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     negate() {
-        return new Vector2(-this.x, -this.y);
+        return new this.constructor(-this.x, -this.y);
     }
     /**
      * Negate this vector in place
@@ -309,7 +309,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     scale(scale) {
-        const result = new Vector2(0, 0);
+        const result = new this.constructor(0, 0);
         this.scaleToRef(scale, result);
         return result;
     }
@@ -318,24 +318,24 @@ export class Vector2 {
      * Example Playground https://playground.babylonjs.com/#QYBWV4#57
      * @param scale defines the scale factor
      * @param result defines the Vector2 object where to store the result
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     scaleToRef(scale, result) {
         result.x = this.x * scale;
         result.y = this.y * scale;
-        return this;
+        return result;
     }
     /**
      * Scale the current Vector2 values by a factor and add the result to a given Vector2
      * Example Playground https://playground.babylonjs.com/#QYBWV4#58
      * @param scale defines the scale factor
      * @param result defines the Vector2 object where to store the result
-     * @returns the unmodified current Vector2
+     * @returns result input
      */
     scaleAndAddToRef(scale, result) {
         result.x += this.x * scale;
         result.y += this.y * scale;
-        return this;
+        return result;
     }
     /**
      * Gets a boolean if two vectors are equals
@@ -363,7 +363,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     floor() {
-        return new Vector2(Math.floor(this.x), Math.floor(this.y));
+        return new this.constructor(Math.floor(this.x), Math.floor(this.y));
     }
     /**
      * Gets a new Vector2 from current Vector2 fractional values
@@ -372,21 +372,21 @@ export class Vector2 {
      * @returns a new Vector2
      */
     fract() {
-        return new Vector2(this.x - Math.floor(this.x), this.y - Math.floor(this.y));
+        return new this.constructor(this.x - Math.floor(this.x), this.y - Math.floor(this.y));
     }
     /**
      * Rotate the current vector into a given result vector
      * Example Playground https://playground.babylonjs.com/#QYBWV4#49
      * @param angle defines the rotation angle
      * @param result defines the result vector where to store the rotated vector
-     * @returns the current vector
+     * @returns result input
      */
     rotateToRef(angle, result) {
         const cos = Math.cos(angle);
         const sin = Math.sin(angle);
         result.x = cos * this.x - sin * this.y;
         result.y = sin * this.x + cos * this.y;
-        return this;
+        return result;
     }
     // Properties
     /**
@@ -419,7 +419,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     clone() {
-        return new Vector2(this.x, this.y);
+        return new this.constructor(this.x, this.y);
     }
     // Statics
     /**
@@ -458,10 +458,12 @@ export class Vector2 {
      * @param array defines the data source
      * @param offset defines the offset in the data source
      * @param result defines the target vector
+     * @returns result input
      */
     static FromArrayToRef(array, offset, result) {
         result.x = array[offset];
         result.y = array[offset + 1];
+        return result;
     }
     /**
      * Gets a new Vector2 located for "amount" (float) on the CatmullRom spline defined by the given four Vector2
@@ -486,7 +488,7 @@ export class Vector2 {
                 (-value1.y + value3.y) * amount +
                 (2.0 * value1.y - 5.0 * value2.y + 4.0 * value3.y - value4.y) * squared +
                 (-value1.y + 3.0 * value2.y - 3.0 * value3.y + value4.y) * cubed);
-        return new Vector2(x, y);
+        return new value1.constructor(x, y);
     }
     /**
      * Returns a new Vector2 set with same the coordinates than "value" ones if the vector "value" is in the square defined by "min" and "max".
@@ -505,7 +507,7 @@ export class Vector2 {
         let y = value.y;
         y = y > max.y ? max.y : y;
         y = y < min.y ? min.y : y;
-        return new Vector2(x, y);
+        return new value.constructor(x, y);
     }
     /**
      * Returns a new Vector2 located for "amount" (float) on the Hermite spline defined by the vectors "value1", "value2", "tangent1", "tangent2"
@@ -526,7 +528,7 @@ export class Vector2 {
         const part4 = cubed - squared;
         const x = value1.x * part1 + value2.x * part2 + tangent1.x * part3 + tangent2.x * part4;
         const y = value1.y * part1 + value2.y * part2 + tangent1.y * part3 + tangent2.y * part4;
-        return new Vector2(x, y);
+        return new value1.constructor(x, y);
     }
     /**
      * Returns a new Vector2 which is the 1st derivative of the Hermite spline defined by the vectors "value1", "value2", "tangent1", "tangent2".
@@ -539,7 +541,7 @@ export class Vector2 {
      * @returns 1st derivative
      */
     static Hermite1stDerivative(value1, tangent1, value2, tangent2, time) {
-        const result = Vector2.Zero();
+        const result = new value1.constructor();
         this.Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result);
         return result;
     }
@@ -552,11 +554,13 @@ export class Vector2 {
      * @param tangent2 defines the second tangent
      * @param time define where the derivative must be done
      * @param result define where the derivative will be stored
+     * @returns result input
      */
     static Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result) {
         const t2 = time * time;
         result.x = (t2 - time) * 6 * value1.x + (3 * t2 - 4 * time + 1) * tangent1.x + (-t2 + time) * 6 * value2.x + (3 * t2 - 2 * time) * tangent2.x;
         result.y = (t2 - time) * 6 * value1.y + (3 * t2 - 4 * time + 1) * tangent1.y + (-t2 + time) * 6 * value2.y + (3 * t2 - 2 * time) * tangent2.y;
+        return result;
     }
     /**
      * Returns a new Vector2 located for "amount" (float) on the linear interpolation between the vector "start" adn the vector "end".
@@ -569,7 +573,7 @@ export class Vector2 {
     static Lerp(start, end, amount) {
         const x = start.x + (end.x - start.x) * amount;
         const y = start.y + (end.y - start.y) * amount;
-        return new Vector2(x, y);
+        return new start.constructor(x, y);
     }
     /**
      * Gets the dot product of the vector "left" and the vector "right"
@@ -588,7 +592,7 @@ export class Vector2 {
      * @returns a new Vector2
      */
     static Normalize(vector) {
-        const newVector = Vector2.Zero();
+        const newVector = new vector.constructor();
         this.NormalizeToRef(vector, newVector);
         return newVector;
     }
@@ -597,14 +601,16 @@ export class Vector2 {
      * Example Playground https://playground.babylonjs.com/#QYBWV4#50
      * @param vector defines the vector to normalize
      * @param result defines the vector where to store the result
+     * @returns result input
      */
     static NormalizeToRef(vector, result) {
         const len = vector.length();
         if (len === 0) {
-            return;
+            return result;
         }
         result.x = vector.x / len;
         result.y = vector.y / len;
+        return result;
     }
     /**
      * Gets a new Vector2 set with the minimal coordinate values from the "left" and "right" vectors
@@ -616,7 +622,7 @@ export class Vector2 {
     static Minimize(left, right) {
         const x = left.x < right.x ? left.x : right.x;
         const y = left.y < right.y ? left.y : right.y;
-        return new Vector2(x, y);
+        return new left.constructor(x, y);
     }
     /**
      * Gets a new Vector2 set with the maximal coordinate values from the "left" and "right" vectors
@@ -628,7 +634,7 @@ export class Vector2 {
     static Maximize(left, right) {
         const x = left.x > right.x ? left.x : right.x;
         const y = left.y > right.y ? left.y : right.y;
-        return new Vector2(x, y);
+        return new left.constructor(x, y);
     }
     /**
      * Gets a new Vector2 set with the transformed coordinates of the given vector by the given transformation matrix
@@ -638,9 +644,9 @@ export class Vector2 {
      * @returns a new Vector2
      */
     static Transform(vector, transformation) {
-        const r = Vector2.Zero();
-        Vector2.TransformToRef(vector, transformation, r);
-        return r;
+        const result = new vector.constructor();
+        Vector2.TransformToRef(vector, transformation, result);
+        return result;
     }
     /**
      * Transforms the given vector coordinates by the given transformation matrix and stores the result in the vector "result" coordinates
@@ -648,6 +654,7 @@ export class Vector2 {
      * @param vector defines the vector to transform
      * @param transformation defines the matrix to apply
      * @param result defines the target vector
+     * @returns result input
      */
     static TransformToRef(vector, transformation, result) {
         const m = transformation.m;
@@ -655,6 +662,7 @@ export class Vector2 {
         const y = vector.x * m[1] + vector.y * m[5] + m[13];
         result.x = x;
         result.y = y;
+        return result;
     }
     /**
      * Determines if a given vector is included in a triangle
@@ -703,7 +711,8 @@ export class Vector2 {
      * @returns a new Vector2
      */
     static Center(value1, value2) {
-        return Vector2.CenterToRef(value1, value2, Vector2.Zero());
+        const result = new value1.constructor();
+        return Vector2.CenterToRef(value1, value2, result);
     }
     /**
      * Gets the center of the vectors "value1" and "value2" and stores the result in the vector "ref"
@@ -882,7 +891,7 @@ export class Vector3 {
      * @returns the resulting Vector3
      */
     add(otherVector) {
-        return new Vector3(this._x + otherVector._x, this._y + otherVector._y, this._z + otherVector._z);
+        return new this.constructor(this._x + otherVector._x, this._y + otherVector._y, this._z + otherVector._z);
     }
     /**
      * Adds the current Vector3 to the given one and stores the result in the vector "result"
@@ -913,7 +922,7 @@ export class Vector3 {
      * @returns the resulting Vector3
      */
     subtract(otherVector) {
-        return new Vector3(this._x - otherVector._x, this._y - otherVector._y, this._z - otherVector._z);
+        return new this.constructor(this._x - otherVector._x, this._y - otherVector._y, this._z - otherVector._z);
     }
     /**
      * Subtracts the given vector from the current Vector3 and stores the result in the vector "result".
@@ -934,7 +943,7 @@ export class Vector3 {
      * @returns the resulting Vector3
      */
     subtractFromFloats(x, y, z) {
-        return new Vector3(this._x - x, this._y - y, this._z - z);
+        return new this.constructor(this._x - x, this._y - y, this._z - z);
     }
     /**
      * Subtracts the given floats from the current Vector3 coordinates and set the given vector "result" with this result
@@ -954,7 +963,7 @@ export class Vector3 {
      * @returns a new Vector3
      */
     negate() {
-        return new Vector3(-this._x, -this._y, -this._z);
+        return new this.constructor(-this._x, -this._y, -this._z);
     }
     /**
      * Negate this vector in place
@@ -995,7 +1004,7 @@ export class Vector3 {
      * @returns a new Vector3
      */
     scale(scale) {
-        return new Vector3(this._x * scale, this._y * scale, this._z * scale);
+        return new this.constructor(this._x * scale, this._y * scale, this._z * scale);
     }
     /**
      * Multiplies the current Vector3 coordinates by the float "scale" and stores the result in the given vector "result" coordinates
@@ -1009,11 +1018,16 @@ export class Vector3 {
     }
     /**
      * Creates a vector normal (perpendicular) to the current Vector3 and stores the result in the given vector
+     * Out of the infinite possibilities the normal chosen is the one formed by rotating the current vector
+     * 90 degrees about an axis which lies perpendicular to the current vector
+     * and its projection on the xz plane. In the case of a current vector in the xz plane
+     * the normal is calculated to be along the y axis.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#230
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#231
      * @param result defines the Vector3 object where to store the resultant normal
      * returns the result
-     * @hidden
      */
-    _getNormalToRef(result) {
+    getNormalToRef(result) {
         /**
          * Calculates the spherical coordinates of the current vector
          * so saves on memory rather than importing whole Spherical Class
@@ -1068,14 +1082,14 @@ export class Vector3 {
      * @returns a new Vector3
      */
     applyRotationQuaternion(q) {
-        return this.applyRotationQuaternionToRef(q, Vector3.Zero());
+        return this.applyRotationQuaternionToRef(q, new this.constructor());
     }
     /**
      * Scale the current Vector3 values by a factor and add the result to a given Vector3
      * Example Playground https://playground.babylonjs.com/#R1F8YU#55
      * @param scale defines the scale factor
      * @param result defines the Vector3 object where to store the result
-     * @returns the unmodified current Vector3
+     * @returns result input
      */
     scaleAndAddToRef(scale, result) {
         return result.addInPlaceFromFloats(this._x * scale, this._y * scale, this._z * scale);
@@ -1088,7 +1102,7 @@ export class Vector3 {
      * @returns the projected vector3
      */
     projectOnPlane(plane, origin) {
-        const result = Vector3.Zero();
+        const result = new this.constructor();
         this.projectOnPlaneToRef(plane, origin, result);
         return result;
     }
@@ -1098,6 +1112,7 @@ export class Vector3 {
      * @param plane defines the plane to project to
      * @param origin defines the origin of the projection ray
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     projectOnPlaneToRef(plane, origin, result) {
         const n = plane.normal;
@@ -1117,6 +1132,7 @@ export class Vector3 {
             const scaledV = V.scaleInPlace(t);
             origin.addToRef(scaledV, result);
         }
+        return result;
     }
     /**
      * Returns true if the current Vector3 and the given vector coordinates are strictly equal
@@ -1191,7 +1207,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     multiplyByFloats(x, y, z) {
-        return new Vector3(this._x * x, this._y * y, this._z * z);
+        return new this.constructor(this._x * x, this._y * y, this._z * z);
     }
     /**
      * Returns a new Vector3 set with the result of the division of the current Vector3 coordinates by the given ones
@@ -1200,7 +1216,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     divide(otherVector) {
-        return new Vector3(this._x / otherVector._x, this._y / otherVector._y, this._z / otherVector._z);
+        return new this.constructor(this._x / otherVector._x, this._y / otherVector._y, this._z / otherVector._z);
     }
     /**
      * Divides the current Vector3 coordinates by the given ones and stores the result in the given vector "result"
@@ -1321,7 +1337,7 @@ export class Vector3 {
      * @returns a new Vector3
      */
     floor() {
-        return new Vector3(Math.floor(this._x), Math.floor(this._y), Math.floor(this._z));
+        return new this.constructor(Math.floor(this._x), Math.floor(this._y), Math.floor(this._z));
     }
     /**
      * Gets a new Vector3 from current Vector3 fractional values
@@ -1329,7 +1345,7 @@ export class Vector3 {
      * @returns a new Vector3
      */
     fract() {
-        return new Vector3(this._x - Math.floor(this._x), this._y - Math.floor(this._y), this._z - Math.floor(this._z));
+        return new this.constructor(this._x - Math.floor(this._x), this._y - Math.floor(this._y), this._z - Math.floor(this._z));
     }
     // Properties
     /**
@@ -1415,7 +1431,8 @@ export class Vector3 {
      * @returns the cross product
      */
     cross(other) {
-        return Vector3.Cross(this, other);
+        const result = new this.constructor();
+        return Vector3.CrossToRef(this, other, result);
     }
     /**
      * Normalize the current Vector3 with the given input length.
@@ -1436,7 +1453,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     normalizeToNew() {
-        const normalized = new Vector3(0, 0, 0);
+        const normalized = new this.constructor(0, 0, 0);
         this.normalizeToRef(normalized);
         return normalized;
     }
@@ -1459,7 +1476,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     clone() {
-        return new Vector3(this._x, this._y, this._z);
+        return new this.constructor(this._x, this._y, this._z);
     }
     /**
      * Copies the given vector coordinates to the current Vector3 ones
@@ -1635,6 +1652,7 @@ export class Vector3 {
         vector1Dir.scaleInPlace(scale1);
         result.copyFrom(vector0Dir).addInPlace(vector1Dir);
         result.scaleInPlace(Scalar.Lerp(vector0Length, vector1Length, slerp));
+        return result;
     }
     /**
      * Smooth interpolation between two vectors using Slerp
@@ -1647,6 +1665,7 @@ export class Vector3 {
      */
     static SmoothToRef(source, goal, deltaTime, lerpTime, result) {
         Vector3.SlerpToRef(source, goal, lerpTime === 0 ? 1 : deltaTime / lerpTime, result);
+        return result;
     }
     /**
      * Returns a new Vector3 set from the index "offset" of the given array
@@ -1674,11 +1693,13 @@ export class Vector3 {
      * @param array defines the source array
      * @param offset defines the offset in the source array
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static FromArrayToRef(array, offset, result) {
         result.x = array[offset];
         result.y = array[offset + 1];
         result.z = array[offset + 2];
+        return result;
     }
     /**
      * Sets the given vector "result" with the element values from the index "offset" of the given Float32Array
@@ -1700,6 +1721,7 @@ export class Vector3 {
      */
     static FromFloatsToRef(x, y, z, result) {
         result.copyFromFloats(x, y, z);
+        return result;
     }
     /**
      * Returns a new Vector3 set to (0.0, 0.0, 0.0)
@@ -1827,9 +1849,11 @@ export class Vector3 {
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static TransformCoordinatesToRef(vector, transformation, result) {
         Vector3.TransformCoordinatesFromFloatsToRef(vector._x, vector._y, vector._z, transformation, result);
+        return result;
     }
     /**
      * Sets the given vector "result" coordinates with the result of the transformation by the given matrix of the given floats (x, y, z)
@@ -1840,6 +1864,7 @@ export class Vector3 {
      * @param z define the z coordinate of the source vector
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static TransformCoordinatesFromFloatsToRef(x, y, z, transformation, result) {
         const m = transformation.m;
@@ -1850,6 +1875,7 @@ export class Vector3 {
         result.x = rx * rw;
         result.y = ry * rw;
         result.z = rz * rw;
+        return result;
     }
     /**
      * Returns a new Vector3 set with the result of the normal transformation by the given matrix of the given vector
@@ -1871,9 +1897,11 @@ export class Vector3 {
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static TransformNormalToRef(vector, transformation, result) {
         this.TransformNormalFromFloatsToRef(vector._x, vector._y, vector._z, transformation, result);
+        return result;
     }
     /**
      * Sets the given vector "result" with the result of the normal transformation by the given matrix of the given floats (x, y, z)
@@ -1884,12 +1912,14 @@ export class Vector3 {
      * @param z define the z coordinate of the source vector
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static TransformNormalFromFloatsToRef(x, y, z, transformation, result) {
         const m = transformation.m;
         result.x = x * m[0] + y * m[4] + z * m[8];
         result.y = x * m[1] + y * m[5] + z * m[9];
         result.z = x * m[2] + y * m[6] + z * m[10];
+        return result;
     }
     /**
      * Returns a new Vector3 located for "amount" on the CatmullRom interpolation spline defined by the vectors "value1", "value2", "value3", "value4"
@@ -1919,7 +1949,7 @@ export class Vector3 {
                 (-value1._z + value3._z) * amount +
                 (2.0 * value1._z - 5.0 * value2._z + 4.0 * value3._z - value4._z) * squared +
                 (-value1._z + 3.0 * value2._z - 3.0 * value3._z + value4._z) * cubed);
-        return new Vector3(x, y, z);
+        return new value1.constructor(x, y, z);
     }
     /**
      * Returns a new Vector3 set with the coordinates of "value", if the vector "value" is in the cube defined by the vectors "min" and "max"
@@ -1932,9 +1962,9 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Clamp(value, min, max) {
-        const v = new Vector3();
-        Vector3.ClampToRef(value, min, max, v);
-        return v;
+        const result = new value.constructor();
+        Vector3.ClampToRef(value, min, max, result);
+        return result;
     }
     /**
      * Sets the given vector "result" with the coordinates of "value", if the vector "value" is in the cube defined by the vectors "min" and "max"
@@ -1945,6 +1975,7 @@ export class Vector3 {
      * @param min defines the lower range value
      * @param max defines the upper range value
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static ClampToRef(value, min, max, result) {
         let x = value._x;
@@ -1957,6 +1988,7 @@ export class Vector3 {
         z = z > max._z ? max._z : z;
         z = z < min._z ? min._z : z;
         result.copyFromFloats(x, y, z);
+        return result;
     }
     /**
      * Checks if a given vector is inside a specific range
@@ -1989,7 +2021,7 @@ export class Vector3 {
         const x = value1._x * part1 + value2._x * part2 + tangent1._x * part3 + tangent2._x * part4;
         const y = value1._y * part1 + value2._y * part2 + tangent1._y * part3 + tangent2._y * part4;
         const z = value1._z * part1 + value2._z * part2 + tangent1._z * part3 + tangent2._z * part4;
-        return new Vector3(x, y, z);
+        return new value1.constructor(x, y, z);
     }
     /**
      * Returns a new Vector3 which is the 1st derivative of the Hermite spline defined by the vectors "value1", "value2", "tangent1", "tangent2".
@@ -2002,7 +2034,7 @@ export class Vector3 {
      * @returns 1st derivative
      */
     static Hermite1stDerivative(value1, tangent1, value2, tangent2, time) {
-        const result = Vector3.Zero();
+        const result = new value1.constructor();
         this.Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result);
         return result;
     }
@@ -2015,12 +2047,14 @@ export class Vector3 {
      * @param tangent2 defines the second tangent
      * @param time define where the derivative must be done
      * @param result define where to store the derivative
+     * @returns result input
      */
     static Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result) {
         const t2 = time * time;
         result.x = (t2 - time) * 6 * value1.x + (3 * t2 - 4 * time + 1) * tangent1.x + (-t2 + time) * 6 * value2.x + (3 * t2 - 2 * time) * tangent2.x;
         result.y = (t2 - time) * 6 * value1.y + (3 * t2 - 4 * time + 1) * tangent1.y + (-t2 + time) * 6 * value2.y + (3 * t2 - 2 * time) * tangent2.y;
         result.z = (t2 - time) * 6 * value1.z + (3 * t2 - 4 * time + 1) * tangent1.z + (-t2 + time) * 6 * value2.z + (3 * t2 - 2 * time) * tangent2.z;
+        return result;
     }
     /**
      * Returns a new Vector3 located for "amount" (float) on the linear interpolation between the vectors "start" and "end"
@@ -2031,7 +2065,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Lerp(start, end, amount) {
-        const result = new Vector3(0, 0, 0);
+        const result = new start.constructor(0, 0, 0);
         Vector3.LerpToRef(start, end, amount, result);
         return result;
     }
@@ -2042,11 +2076,13 @@ export class Vector3 {
      * @param end defines the end value
      * @param amount max defines amount between both (between 0 and 1)
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static LerpToRef(start, end, amount, result) {
         result.x = start._x + (end._x - start._x) * amount;
         result.y = start._y + (end._y - start._y) * amount;
         result.z = start._z + (end._z - start._z) * amount;
+        return result;
     }
     /**
      * Returns the dot product (float) between the vectors "left" and "right"
@@ -2067,7 +2103,7 @@ export class Vector3 {
      * @returns the cross product
      */
     static Cross(left, right) {
-        const result = Vector3.Zero();
+        const result = new left.constructor();
         Vector3.CrossToRef(left, right, result);
         return result;
     }
@@ -2078,12 +2114,14 @@ export class Vector3 {
      * @param left defines the left operand
      * @param right defines the right operand
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static CrossToRef(left, right, result) {
         const x = left._y * right._z - left._z * right._y;
         const y = left._z * right._x - left._x * right._z;
         const z = left._x * right._y - left._y * right._x;
         result.copyFromFloats(x, y, z);
+        return result;
     }
     /**
      * Returns a new Vector3 as the normalization of the given vector
@@ -2101,9 +2139,11 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#98
      * @param vector defines the Vector3 to normalize
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static NormalizeToRef(vector, result) {
         vector.normalizeToRef(result);
+        return result;
     }
     /**
      * Project a Vector3 onto screen space
@@ -2115,7 +2155,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Project(vector, world, transform, viewport) {
-        const result = new Vector3();
+        const result = new vector.constructor();
         Vector3.ProjectToRef(vector, world, transform, viewport, result);
         return result;
     }
@@ -2127,7 +2167,7 @@ export class Vector3 {
      * @param transform defines the transform (view x projection) matrix to use
      * @param viewport defines the screen viewport to use
      * @param result the vector in which the screen space will be stored
-     * @returns the new Vector3
+     * @returns result input
      */
     static ProjectToRef(vector, world, transform, viewport, result) {
         const cw = viewport.width;
@@ -2152,6 +2192,7 @@ export class Vector3 {
         if (Scalar.WithinEpsilon(num, 1.0)) {
             result.scaleInPlace(1.0 / num);
         }
+        return result;
     }
     /**
      * Unproject from screen space to object space
@@ -2178,7 +2219,7 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Unproject(source, viewportWidth, viewportHeight, world, view, projection) {
-        const result = Vector3.Zero();
+        const result = new source.constructor();
         Vector3.UnprojectToRef(source, viewportWidth, viewportHeight, world, view, projection, result);
         return result;
     }
@@ -2192,9 +2233,11 @@ export class Vector3 {
      * @param view defines the view matrix to use
      * @param projection defines the projection matrix to use
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static UnprojectToRef(source, viewportWidth, viewportHeight, world, view, projection, result) {
         Vector3.UnprojectFloatsToRef(source._x, source._y, source._z, viewportWidth, viewportHeight, world, view, projection, result);
+        return result;
     }
     /**
      * Unproject from screen space to object space
@@ -2208,6 +2251,7 @@ export class Vector3 {
      * @param view defines the view matrix to use
      * @param projection defines the projection matrix to use
      * @param result defines the Vector3 where to store the result
+     * @returns result input
      */
     static UnprojectFloatsToRef(sourceX, sourceY, sourceZ, viewportWidth, viewportHeight, world, view, projection, result) {
         var _a;
@@ -2225,6 +2269,7 @@ export class Vector3 {
             screenSource.z = 2 * sourceZ - 1.0;
         }
         Vector3._UnprojectFromInvertedMatrixToRef(screenSource, matrix, result);
+        return result;
     }
     /**
      * Gets the minimal coordinate values between two Vector3
@@ -2234,7 +2279,8 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Minimize(left, right) {
-        const min = left.clone();
+        const min = new left.constructor();
+        min.copyFrom(left);
         min.minimizeInPlace(right);
         return min;
     }
@@ -2246,7 +2292,8 @@ export class Vector3 {
      * @returns the new Vector3
      */
     static Maximize(left, right) {
-        const max = left.clone();
+        const max = new left.constructor();
+        max.copyFrom(left);
         max.maximizeInPlace(right);
         return max;
     }
@@ -2447,7 +2494,7 @@ export class Vector3 {
      * @see https://doc.babylonjs.com/divingDeeper/mesh/transforms/center_origin/target_align
      */
     static RotationFromAxis(axis1, axis2, axis3) {
-        const rotation = Vector3.Zero();
+        const rotation = new axis1.constructor();
         Vector3.RotationFromAxisToRef(axis1, axis2, axis3, rotation);
         return rotation;
     }
@@ -2458,11 +2505,13 @@ export class Vector3 {
      * @param axis2 defines the second axis
      * @param axis3 defines the third axis
      * @param ref defines the Vector3 where to store the result
+     * @returns result input
      */
     static RotationFromAxisToRef(axis1, axis2, axis3, ref) {
         const quat = MathTmp.Quaternion[0];
         Quaternion.RotationQuaternionFromAxisToRef(axis1, axis2, axis3, quat);
         quat.toEulerAnglesToRef(ref);
+        return ref;
     }
 }
 Vector3._UpReadOnly = Vector3.Up();
@@ -2485,13 +2534,13 @@ export class Vector4 {
      */
     constructor(
     /** x value of the vector */
-    x, 
+    x = 0, 
     /** y value of the vector */
-    y, 
+    y = 0, 
     /** z value of the vector */
-    z, 
+    z = 0, 
     /** w value of the vector */
-    w) {
+    w = 0) {
         this.x = x;
         this.y = y;
         this.z = z;
@@ -2580,20 +2629,20 @@ export class Vector4 {
      * @returns the resulting vector
      */
     add(otherVector) {
-        return new Vector4(this.x + otherVector.x, this.y + otherVector.y, this.z + otherVector.z, this.w + otherVector.w);
+        return new this.constructor(this.x + otherVector.x, this.y + otherVector.y, this.z + otherVector.z, this.w + otherVector.w);
     }
     /**
      * Updates the given vector "result" with the result of the addition of the current Vector4 and the given one.
      * @param otherVector the vector to add
      * @param result the vector to store the result
-     * @returns the current Vector4.
+     * @returns result input
      */
     addToRef(otherVector, result) {
         result.x = this.x + otherVector.x;
         result.y = this.y + otherVector.y;
         result.z = this.z + otherVector.z;
         result.w = this.w + otherVector.w;
-        return this;
+        return result;
     }
     /**
      * Subtract in place the given vector from the current Vector4.
@@ -2613,20 +2662,20 @@ export class Vector4 {
      * @returns the new vector with the result
      */
     subtract(otherVector) {
-        return new Vector4(this.x - otherVector.x, this.y - otherVector.y, this.z - otherVector.z, this.w - otherVector.w);
+        return new this.constructor(this.x - otherVector.x, this.y - otherVector.y, this.z - otherVector.z, this.w - otherVector.w);
     }
     /**
      * Sets the given vector "result" with the result of the subtraction of the given vector from the current Vector4.
      * @param otherVector the vector to subtract
      * @param result the vector to store the result
-     * @returns the current Vector4.
+     * @returns result input
      */
     subtractToRef(otherVector, result) {
         result.x = this.x - otherVector.x;
         result.y = this.y - otherVector.y;
         result.z = this.z - otherVector.z;
         result.w = this.w - otherVector.w;
-        return this;
+        return result;
     }
     /**
      * Returns a new Vector4 set with the result of the subtraction of the given floats from the current Vector4 coordinates.
@@ -2640,7 +2689,7 @@ export class Vector4 {
      * @returns new vector containing the result
      */
     subtractFromFloats(x, y, z, w) {
-        return new Vector4(this.x - x, this.y - y, this.z - z, this.w - w);
+        return new this.constructor(this.x - x, this.y - y, this.z - z, this.w - w);
     }
     /**
      * Sets the given vector "result" set with the result of the subtraction of the given floats from the current Vector4 coordinates.
@@ -2649,21 +2698,21 @@ export class Vector4 {
      * @param z value to subtract
      * @param w value to subtract
      * @param result the vector to store the result in
-     * @returns the current Vector4.
+     * @returns result input
      */
     subtractFromFloatsToRef(x, y, z, w, result) {
         result.x = this.x - x;
         result.y = this.y - y;
         result.z = this.z - z;
         result.w = this.w - w;
-        return this;
+        return result;
     }
     /**
      * Returns a new Vector4 set with the current Vector4 negated coordinates.
      * @returns a new vector with the negated values
      */
     negate() {
-        return new Vector4(-this.x, -this.y, -this.z, -this.w);
+        return new this.constructor(-this.x, -this.y, -this.z, -this.w);
     }
     /**
      * Negate this vector in place
@@ -2702,33 +2751,33 @@ export class Vector4 {
      * @returns a new vector with the result
      */
     scale(scale) {
-        return new Vector4(this.x * scale, this.y * scale, this.z * scale, this.w * scale);
+        return new this.constructor(this.x * scale, this.y * scale, this.z * scale, this.w * scale);
     }
     /**
      * Sets the given vector "result" with the current Vector4 coordinates multiplied by scale (float).
      * @param scale the number to scale with
      * @param result a vector to store the result in
-     * @returns the current Vector4.
+     * @returns result input
      */
     scaleToRef(scale, result) {
         result.x = this.x * scale;
         result.y = this.y * scale;
         result.z = this.z * scale;
         result.w = this.w * scale;
-        return this;
+        return result;
     }
     /**
      * Scale the current Vector4 values by a factor and add the result to a given Vector4
      * @param scale defines the scale factor
      * @param result defines the Vector4 object where to store the result
-     * @returns the unmodified current Vector4
+     * @returns result input
      */
     scaleAndAddToRef(scale, result) {
         result.x += this.x * scale;
         result.y += this.y * scale;
         result.z += this.z * scale;
         result.w += this.w * scale;
-        return this;
+        return result;
     }
     /**
      * Boolean : True if the current Vector4 coordinates are stricly equal to the given ones.
@@ -2780,20 +2829,20 @@ export class Vector4 {
      * @returns resulting new vector
      */
     multiply(otherVector) {
-        return new Vector4(this.x * otherVector.x, this.y * otherVector.y, this.z * otherVector.z, this.w * otherVector.w);
+        return new this.constructor(this.x * otherVector.x, this.y * otherVector.y, this.z * otherVector.z, this.w * otherVector.w);
     }
     /**
      * Updates the given vector "result" with the multiplication result of the current Vector4 and the given one.
      * @param otherVector vector to multiple with
      * @param result vector to store the result
-     * @returns the current Vector4.
+     * @returns result input
      */
     multiplyToRef(otherVector, result) {
         result.x = this.x * otherVector.x;
         result.y = this.y * otherVector.y;
         result.z = this.z * otherVector.z;
         result.w = this.w * otherVector.w;
-        return this;
+        return result;
     }
     /**
      * Returns a new Vector4 set with the multiplication result of the given floats and the current Vector4 coordinates.
@@ -2804,7 +2853,7 @@ export class Vector4 {
      * @returns resulting new vector
      */
     multiplyByFloats(x, y, z, w) {
-        return new Vector4(this.x * x, this.y * y, this.z * z, this.w * w);
+        return new this.constructor(this.x * x, this.y * y, this.z * z, this.w * w);
     }
     /**
      * Returns a new Vector4 set with the division result of the current Vector4 by the given one.
@@ -2812,20 +2861,20 @@ export class Vector4 {
      * @returns resulting new vector
      */
     divide(otherVector) {
-        return new Vector4(this.x / otherVector.x, this.y / otherVector.y, this.z / otherVector.z, this.w / otherVector.w);
+        return new this.constructor(this.x / otherVector.x, this.y / otherVector.y, this.z / otherVector.z, this.w / otherVector.w);
     }
     /**
      * Updates the given vector "result" with the division result of the current Vector4 by the given one.
      * @param otherVector vector to devide with
      * @param result vector to store the result
-     * @returns the current Vector4.
+     * @returns result input
      */
     divideToRef(otherVector, result) {
         result.x = this.x / otherVector.x;
         result.y = this.y / otherVector.y;
         result.z = this.z / otherVector.z;
         result.w = this.w / otherVector.w;
-        return this;
+        return result;
     }
     /**
      * Divides the current Vector3 coordinates by the given ones.
@@ -2880,14 +2929,14 @@ export class Vector4 {
      * @returns a new Vector4
      */
     floor() {
-        return new Vector4(Math.floor(this.x), Math.floor(this.y), Math.floor(this.z), Math.floor(this.w));
+        return new this.constructor(Math.floor(this.x), Math.floor(this.y), Math.floor(this.z), Math.floor(this.w));
     }
     /**
      * Gets a new Vector4 from current Vector4 fractional values
      * @returns a new Vector4
      */
     fract() {
-        return new Vector4(this.x - Math.floor(this.x), this.y - Math.floor(this.y), this.z - Math.floor(this.z), this.w - Math.floor(this.w));
+        return new this.constructor(this.x - Math.floor(this.x), this.y - Math.floor(this.y), this.z - Math.floor(this.z), this.w - Math.floor(this.w));
     }
     // Properties
     /**
@@ -2928,7 +2977,7 @@ export class Vector4 {
      * @returns the new cloned vector
      */
     clone() {
-        return new Vector4(this.x, this.y, this.z, this.w);
+        return new this.constructor(this.x, this.y, this.z, this.w);
     }
     /**
      * Updates the current Vector4 with the given one coordinates.
@@ -2995,21 +3044,25 @@ export class Vector4 {
      * @param array the array to pull values from
      * @param offset the offset into the array to start at
      * @param result the vector to store the result in
+     * @returns result input
      */
     static FromArrayToRef(array, offset, result) {
         result.x = array[offset];
         result.y = array[offset + 1];
         result.z = array[offset + 2];
         result.w = array[offset + 3];
+        return result;
     }
     /**
      * Updates the given vector "result" from the starting index of the given Float32Array.
      * @param array the array to pull values from
      * @param offset the offset into the array to start at
      * @param result the vector to store the result in
+     * @returns result input
      */
     static FromFloatArrayToRef(array, offset, result) {
         Vector4.FromArrayToRef(array, offset, result);
+        return result;
     }
     /**
      * Updates the given vector "result" coordinates from the given floats.
@@ -3018,12 +3071,14 @@ export class Vector4 {
      * @param z float to set from
      * @param w float to set from
      * @param result the vector to the floats in
+     * @returns result input
      */
     static FromFloatsToRef(x, y, z, w, result) {
         result.x = x;
         result.y = y;
         result.z = z;
         result.w = w;
+        return result;
     }
     /**
      * Returns a new Vector4 set to (0.0, 0.0, 0.0, 0.0)
@@ -3059,10 +3114,12 @@ export class Vector4 {
      * Updates the given vector "result" from the normalization of the given one.
      * @param vector the vector to normalize
      * @param result the vector to store the result in
+     * @returns result input
      */
     static NormalizeToRef(vector, result) {
         result.copyFrom(vector);
         result.normalize();
+        return result;
     }
     /**
      * Returns a vector with the minimum values from the left and right vectors
@@ -3071,7 +3128,8 @@ export class Vector4 {
      * @returns a new vector with the minimum of the left and right vector values
      */
     static Minimize(left, right) {
-        const min = left.clone();
+        const min = new left.constructor();
+        min.copyFrom(left);
         min.minimizeInPlace(right);
         return min;
     }
@@ -3082,7 +3140,8 @@ export class Vector4 {
      * @returns a new vector with the maximum of the left and right vector values
      */
     static Maximize(left, right) {
-        const max = left.clone();
+        const max = new left.constructor();
+        max.copyFrom(left);
         max.maximizeInPlace(right);
         return max;
     }
@@ -3147,9 +3206,11 @@ export class Vector4 {
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @param result defines the Vector4 where to store the result
+     * @returns result input
      */
     static TransformCoordinatesToRef(vector, transformation, result) {
         Vector4.TransformCoordinatesFromFloatsToRef(vector._x, vector._y, vector._z, transformation, result);
+        return result;
     }
     /**
      * Sets the given vector "result" coordinates with the result of the transformation by the given matrix of the given floats (x, y, z)
@@ -3160,6 +3221,7 @@ export class Vector4 {
      * @param z define the z coordinate of the source vector
      * @param transformation defines the transformation matrix
      * @param result defines the Vector4 where to store the result
+     * @returns result input
      */
     static TransformCoordinatesFromFloatsToRef(x, y, z, transformation, result) {
         const m = transformation.m;
@@ -3171,6 +3233,7 @@ export class Vector4 {
         result.y = ry;
         result.z = rz;
         result.w = rw;
+        return result;
     }
     /**
      * Returns a new Vector4 set with the result of the normal transformation by the given matrix of the given vector.
@@ -3180,7 +3243,7 @@ export class Vector4 {
      * @returns the new vector
      */
     static TransformNormal(vector, transformation) {
-        const result = Vector4.Zero();
+        const result = new vector.constructor();
         Vector4.TransformNormalToRef(vector, transformation, result);
         return result;
     }
@@ -3190,6 +3253,7 @@ export class Vector4 {
      * @param vector the vector to transform
      * @param transformation the transformation matrix to apply
      * @param result the vector to store the result in
+     * @returns result input
      */
     static TransformNormalToRef(vector, transformation, result) {
         const m = transformation.m;
@@ -3200,6 +3264,7 @@ export class Vector4 {
         result.y = y;
         result.z = z;
         result.w = vector.w;
+        return result;
     }
     /**
      * Sets the given vector "result" with the result of the normal transformation by the given matrix of the given floats (x, y, z, w).
@@ -3210,6 +3275,7 @@ export class Vector4 {
      * @param w value to transform
      * @param transformation the transformation matrix to apply
      * @param result the vector to store the results in
+     * @returns result input
      */
     static TransformNormalFromFloatsToRef(x, y, z, w, transformation, result) {
         const m = transformation.m;
@@ -3217,6 +3283,7 @@ export class Vector4 {
         result.y = x * m[1] + y * m[5] + z * m[9];
         result.z = x * m[2] + y * m[6] + z * m[10];
         result.w = w;
+        return result;
     }
     /**
      * Creates a new Vector4 from a Vector3
@@ -3231,6 +3298,7 @@ export class Vector4 {
 Vector4._ZeroReadOnly = Vector4.Zero();
 /**
  * Class used to store quaternion data
+ * Example Playground - Overview - https://playground.babylonjs.com/#L49EJ7#100
  * @see https://en.wikipedia.org/wiki/Quaternion
  * @see https://doc.babylonjs.com/features/position,_rotation,_scaling
  */
@@ -3313,6 +3381,7 @@ export class Quaternion {
     }
     /**
      * Copy the quaternion to an array
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#13
      * @returns a new array populated with 4 elements from the quaternion coordinates
      */
     asArray() {
@@ -3320,6 +3389,7 @@ export class Quaternion {
     }
     /**
      * Stores from the starting index in the given array the Quaternion successive values
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#59
      * @param array defines the array where to store the x,y,z,w components
      * @param index defines an optional index in the target array to define where to start storing values
      * @returns the current Quaternion object
@@ -3333,6 +3403,7 @@ export class Quaternion {
     }
     /**
      * Check if two quaternions are equals
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#38
      * @param otherQuaternion defines the second operand
      * @returns true if the current quaternion and the given one coordinates are strictly equals
      */
@@ -3341,6 +3412,7 @@ export class Quaternion {
     }
     /**
      * Gets a boolean if two quaternions are equals (using an epsilon value)
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#37
      * @param otherQuaternion defines the other quaternion
      * @param epsilon defines the minimal distance to consider equality
      * @returns true if the given quaternion coordinates are close to the current ones by a distance of epsilon.
@@ -3354,13 +3426,15 @@ export class Quaternion {
     }
     /**
      * Clone the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#12
      * @returns a new quaternion copied from the current one
      */
     clone() {
-        return new Quaternion(this._x, this._y, this._z, this._w);
+        return new this.constructor(this._x, this._y, this._z, this._w);
     }
     /**
      * Copy a quaternion to the current one
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#86
      * @param other defines the other quaternion
      * @returns the updated current quaternion
      */
@@ -3373,6 +3447,7 @@ export class Quaternion {
     }
     /**
      * Updates the current quaternion with the given float coordinates
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#87
      * @param x defines the x coordinate
      * @param y defines the y coordinate
      * @param z defines the z coordinate
@@ -3388,6 +3463,7 @@ export class Quaternion {
     }
     /**
      * Updates the current quaternion from the given float coordinates
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#56
      * @param x defines the x coordinate
      * @param y defines the y coordinate
      * @param z defines the z coordinate
@@ -3399,14 +3475,16 @@ export class Quaternion {
     }
     /**
      * Adds two quaternions
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#10
      * @param other defines the second operand
      * @returns a new quaternion as the addition result of the given one and the current quaternion
      */
     add(other) {
-        return new Quaternion(this._x + other._x, this._y + other._y, this._z + other._z, this._w + other._w);
+        return new this.constructor(this._x + other._x, this._y + other._y, this._z + other._z, this._w + other._w);
     }
     /**
      * Add a quaternion to the current one
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#11
      * @param other defines the quaternion to add
      * @returns the current quaternion
      */
@@ -3419,14 +3497,16 @@ export class Quaternion {
     }
     /**
      * Subtract two quaternions
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#57
      * @param other defines the second operand
      * @returns a new quaternion as the subtraction result of the given one from the current one
      */
     subtract(other) {
-        return new Quaternion(this._x - other._x, this._y - other._y, this._z - other._z, this._w - other._w);
+        return new this.constructor(this._x - other._x, this._y - other._y, this._z - other._z, this._w - other._w);
     }
     /**
      * Subtract a quaternion to the current one
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#58
      * @param other defines the quaternion to subtract
      * @returns the current quaternion
      */
@@ -3439,27 +3519,30 @@ export class Quaternion {
     }
     /**
      * Multiplies the current quaternion by a scale factor
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#88
      * @param value defines the scale factor
      * @returns a new quaternion set by multiplying the current quaternion coordinates by the float "scale"
      */
     scale(value) {
-        return new Quaternion(this._x * value, this._y * value, this._z * value, this._w * value);
+        return new this.constructor(this._x * value, this._y * value, this._z * value, this._w * value);
     }
     /**
      * Scale the current quaternion values by a factor and stores the result to a given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#89
      * @param scale defines the scale factor
      * @param result defines the Quaternion object where to store the result
-     * @returns the unmodified current quaternion
+     * @returns result input
      */
     scaleToRef(scale, result) {
         result.x = this._x * scale;
         result.y = this._y * scale;
         result.z = this._z * scale;
         result.w = this._w * scale;
-        return this;
+        return result;
     }
     /**
      * Multiplies in place the current quaternion by a scale factor
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#90
      * @param value defines the scale factor
      * @returns the current modified quaternion
      */
@@ -3472,29 +3555,32 @@ export class Quaternion {
     }
     /**
      * Scale the current quaternion values by a factor and add the result to a given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#91
      * @param scale defines the scale factor
      * @param result defines the Quaternion object where to store the result
-     * @returns the unmodified current quaternion
+     * @returns result input
      */
     scaleAndAddToRef(scale, result) {
         result.x += this._x * scale;
         result.y += this._y * scale;
         result.z += this._z * scale;
         result.w += this._w * scale;
-        return this;
+        return result;
     }
     /**
      * Multiplies two quaternions
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#43
      * @param q1 defines the second operand
      * @returns a new quaternion set as the multiplication result of the current one with the given one "q1"
      */
     multiply(q1) {
-        const result = new Quaternion(0, 0, 0, 1.0);
+        const result = new this.constructor(0, 0, 0, 1.0);
         this.multiplyToRef(q1, result);
         return result;
     }
     /**
      * Sets the given "result" as the the multiplication result of the current one with the given one "q1"
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#45
      * @param q1 defines the second operand
      * @param result defines the target quaternion
      * @returns the current quaternion
@@ -3505,10 +3591,11 @@ export class Quaternion {
         const z = this._x * q1._y - this._y * q1._x + this._z * q1._w + this._w * q1._z;
         const w = -this._x * q1._x - this._y * q1._y - this._z * q1._z + this._w * q1._w;
         result.copyFromFloats(x, y, z, w);
-        return this;
+        return result;
     }
     /**
      * Updates the current quaternion with the multiplication of itself with the given one "q1"
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#46
      * @param q1 defines the second operand
      * @returns the currentupdated quaternion
      */
@@ -3518,15 +3605,17 @@ export class Quaternion {
     }
     /**
      * Conjugates the current quaternion and stores the result in the given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#81
      * @param ref defines the target quaternion
-     * @returns the current quaternion
+     * @returns result input
      */
     conjugateToRef(ref) {
         ref.copyFromFloats(-this._x, -this._y, -this._z, this._w);
-        return this;
+        return ref;
     }
     /**
      * Conjugates in place the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#82
      * @returns the current updated quaternion
      */
     conjugateInPlace() {
@@ -3537,13 +3626,15 @@ export class Quaternion {
     }
     /**
      * Conjugates (1-q) the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#83
      * @returns a new quaternion
      */
     conjugate() {
-        return new Quaternion(-this._x, -this._y, -this._z, this._w);
+        return new this.constructor(-this._x, -this._y, -this._z, this._w);
     }
     /**
      * Returns the inverse of the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#84
      * @returns a new quaternion
      */
     invert() {
@@ -3557,6 +3648,7 @@ export class Quaternion {
     }
     /**
      * Invert in place the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#85
      * @returns this quaternion
      */
     invertInPlace() {
@@ -3570,6 +3662,7 @@ export class Quaternion {
     }
     /**
      * Gets squared length of current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#29
      * @returns the quaternion length (float)
      */
     lengthSquared() {
@@ -3577,6 +3670,7 @@ export class Quaternion {
     }
     /**
      * Gets length of current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#28
      * @returns the quaternion length (float)
      */
     length() {
@@ -3584,6 +3678,7 @@ export class Quaternion {
     }
     /**
      * Normalize in place the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#54
      * @returns the current updated quaternion
      */
     normalize() {
@@ -3597,6 +3692,7 @@ export class Quaternion {
     }
     /**
      * Normalize a copy of the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#55
      * @returns the normalized quaternion
      */
     normalizeToNew() {
@@ -3609,6 +3705,7 @@ export class Quaternion {
     }
     /**
      * Returns a new Vector3 set with the Euler angles translated from the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#32
      * @returns a new Vector3 containing the Euler angles
      * @see https://doc.babylonjs.com/divingDeeper/mesh/transforms/center_origin/rotation_conventions
      */
@@ -3619,8 +3716,9 @@ export class Quaternion {
     }
     /**
      * Sets the given vector3 "result" with the Euler angles translated from the current quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#31
      * @param result defines the vector which will be filled with the Euler angles
-     * @returns the current unchanged quaternion
+     * @returns result input
      * @see https://doc.babylonjs.com/divingDeeper/mesh/transforms/center_origin/rotation_conventions
      */
     toEulerAnglesToRef(result) {
@@ -3649,19 +3747,21 @@ export class Quaternion {
             result.x = Math.asin(-2.0 * zAxisY);
             result.y = Math.atan2(2.0 * (qz * qx + qy * qw), sqz - sqx - sqy + sqw);
         }
-        return this;
+        return result;
     }
     /**
      * Updates the given rotation matrix with the current quaternion values
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#67
      * @param result defines the target matrix
      * @returns the current unchanged quaternion
      */
     toRotationMatrix(result) {
         Matrix.FromQuaternionToRef(this, result);
-        return this;
+        return result;
     }
     /**
      * Updates the current quaternion from the given rotation matrix values
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#41
      * @param matrix defines the source matrix
      * @returns the current updated quaternion
      */
@@ -3672,6 +3772,7 @@ export class Quaternion {
     // Statics
     /**
      * Creates a new quaternion from a rotation matrix
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#101
      * @param matrix defines the source matrix
      * @returns a new quaternion created from the given rotation matrix values
      */
@@ -3682,8 +3783,10 @@ export class Quaternion {
     }
     /**
      * Updates the given quaternion with the given rotation matrix values
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#102
      * @param matrix defines the source matrix
      * @param result defines the target quaternion
+     * @returns result input
      */
     static FromRotationMatrixToRef(matrix, result) {
         const data = matrix.m;
@@ -3720,37 +3823,11 @@ export class Quaternion {
             result.y = (m23 + m32) / s;
             result.z = 0.25 * s;
         }
-    }
-    /**
-     * Creates the rotation quaternion needed to rotate from one Vector3 onto another Vector3
-     * Example PG https://playground.babylonjs.com/#L49EJ7#2
-     * @param fromVector the starting vector
-     * @param toVector the ending vector
-     * @returns the rotation quaternion needed
-     */
-    static RotationQuaternionFromOnto(fromVector, toVector) {
-        const ref = Quaternion.Zero();
-        return Quaternion.RotationQuaternionFromOntoToRef(fromVector, toVector, ref);
-    }
-    /**
-     * Creates the rotation quaternion needed to rotate from one Vector3 onto another Vector3 and stores in a result Quaternion
-     * Example PG https://playground.babylonjs.com/#L49EJ7#3
-     * @param fromVector the starting vector
-     * @param toVector the ending vector
-     * @param result the rotation quaternion needed
-     * @returns the result
-     */
-    static RotationQuaternionFromOntoToRef(fromVector, toVector, result) {
-        const normal = TmpVectors.Vector3[0];
-        Vector3.CrossToRef(fromVector, toVector, normal);
-        if (normal.equals(Vector3.ZeroReadOnly)) {
-            fromVector._getNormalToRef(normal);
-        }
-        const angle = Vector3.GetAngleBetweenVectors(fromVector, toVector, normal);
-        return Quaternion.RotationAxisToRef(normal, angle, result);
+        return result;
     }
     /**
      * Returns the dot product (float) between the quaternions "left" and "right"
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#61
      * @param left defines the left operand
      * @param right defines the right operand
      * @returns the dot product
@@ -3760,6 +3837,7 @@ export class Quaternion {
     }
     /**
      * Checks if the orientations of two rotation quaternions are close to each other
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#60
      * @param quat0 defines the first quaternion to check
      * @param quat1 defines the second quaternion to check
      * @param epsilon defines closeness, 0 same orientation, 1 PI apart, default 0.1
@@ -3771,7 +3849,7 @@ export class Quaternion {
     }
     /**
      * Smooth interpolation between two quaternions using Slerp
-     *
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#93
      * @param source source quaternion
      * @param goal goal quaternion
      * @param deltaTime current interpolation frame
@@ -3782,6 +3860,7 @@ export class Quaternion {
         let slerp = lerpTime === 0 ? 1 : deltaTime / lerpTime;
         slerp = Scalar.Clamp(slerp, 0, 1);
         Quaternion.SlerpToRef(source, goal, slerp, result);
+        return result;
     }
     /**
      * Creates an empty quaternion
@@ -3792,14 +3871,16 @@ export class Quaternion {
     }
     /**
      * Inverse a given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#103
      * @param q defines the source quaternion
      * @returns a new quaternion as the inverted current quaternion
      */
     static Inverse(q) {
-        return new Quaternion(-q._x, -q._y, -q._z, q._w);
+        return new q.constructor(-q._x, -q._y, -q._z, q._w);
     }
     /**
      * Inverse a given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#104
      * @param q defines the source quaternion
      * @param result the quaternion the result will be stored in
      * @returns the result quaternion
@@ -3825,6 +3906,7 @@ export class Quaternion {
     }
     /**
      * Creates a quaternion from a rotation around an axis
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#72
      * @param axis defines the axis to use
      * @param angle defines the angle to use
      * @returns a new quaternion created from the given axis (Vector3) and angle in radians (float)
@@ -3834,6 +3916,7 @@ export class Quaternion {
     }
     /**
      * Creates a rotation around an axis and stores it into the given quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#73
      * @param axis defines the axis to use
      * @param angle defines the angle to use
      * @param result defines the target quaternion
@@ -3850,6 +3933,7 @@ export class Quaternion {
     }
     /**
      * Creates a new quaternion from data stored into an array
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#63
      * @param array defines the data source
      * @param offset defines the offset in the source array where the data starts
      * @returns a new quaternion
@@ -3862,18 +3946,22 @@ export class Quaternion {
     }
     /**
      * Updates the given quaternion "result" from the starting index of the given array.
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#64
      * @param array the array to pull values from
      * @param offset the offset into the array to start at
      * @param result the quaternion to store the result in
+     * @returns result input
      */
     static FromArrayToRef(array, offset, result) {
         result.x = array[offset];
         result.y = array[offset + 1];
         result.z = array[offset + 2];
         result.w = array[offset + 3];
+        return result;
     }
     /**
      * Create a quaternion from Euler rotation angles
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#33
      * @param x Pitch
      * @param y Yaw
      * @param z Roll
@@ -3886,6 +3974,7 @@ export class Quaternion {
     }
     /**
      * Updates a quaternion from Euler rotation angles
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#34
      * @param x Pitch
      * @param y Yaw
      * @param z Roll
@@ -3898,6 +3987,7 @@ export class Quaternion {
     }
     /**
      * Create a quaternion from Euler rotation vector
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#35
      * @param vec the Euler vector (x Pitch, y Yaw, z Roll)
      * @returns the new Quaternion
      */
@@ -3908,6 +3998,7 @@ export class Quaternion {
     }
     /**
      * Updates a quaternion from Euler rotation vector
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#36
      * @param vec the Euler vector (x Pitch, y Yaw, z Roll)
      * @param result the quaternion to store the result
      * @returns the updated quaternion
@@ -3918,6 +4009,7 @@ export class Quaternion {
     }
     /**
      * Updates a quaternion so that it rotates vector vecFrom to vector vecTo
+     * Example Playground - https://playground.babylonjs.com/#L49EJ7#70
      * @param vecFrom defines the direction vector from which to rotate
      * @param vecTo defines the direction vector to which to rotate
      * @param result the quaternion to store the result
@@ -3941,6 +4033,7 @@ export class Quaternion {
     }
     /**
      * Creates a new quaternion from the given Euler float angles (y, x, z)
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#77
      * @param yaw defines the rotation around Y axis
      * @param pitch defines the rotation around X axis
      * @param roll defines the rotation around Z axis
@@ -3953,10 +4046,12 @@ export class Quaternion {
     }
     /**
      * Creates a new rotation from the given Euler float angles (y, x, z) and stores it in the target quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#78
      * @param yaw defines the rotation around Y axis
      * @param pitch defines the rotation around X axis
      * @param roll defines the rotation around Z axis
      * @param result defines the target quaternion
+     * @returns result input
      */
     static RotationYawPitchRollToRef(yaw, pitch, roll, result) {
         // Produces a quaternion from Euler angles in the z-y-x orientation (Tait-Bryan angles)
@@ -3973,9 +4068,11 @@ export class Quaternion {
         result.y = sinYaw * cosPitch * cosRoll - cosYaw * sinPitch * sinRoll;
         result.z = cosYaw * cosPitch * sinRoll - sinYaw * sinPitch * cosRoll;
         result.w = cosYaw * cosPitch * cosRoll + sinYaw * sinPitch * sinRoll;
+        return result;
     }
     /**
      * Creates a new quaternion from the given Euler float angles expressed in z-x-z orientation
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#68
      * @param alpha defines the rotation around first axis
      * @param beta defines the rotation around second axis
      * @param gamma defines the rotation around third axis
@@ -3988,10 +4085,12 @@ export class Quaternion {
     }
     /**
      * Creates a new quaternion from the given Euler float angles expressed in z-x-z orientation and stores it in the target quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#69
      * @param alpha defines the rotation around first axis
      * @param beta defines the rotation around second axis
      * @param gamma defines the rotation around third axis
      * @param result defines the target quaternion
+     * @returns result input
      */
     static RotationAlphaBetaGammaToRef(alpha, beta, gamma, result) {
         // Produces a quaternion from Euler angles in the z-x-z orientation
@@ -4002,9 +4101,11 @@ export class Quaternion {
         result.y = Math.sin(halfGammaMinusAlpha) * Math.sin(halfBeta);
         result.z = Math.sin(halfGammaPlusAlpha) * Math.cos(halfBeta);
         result.w = Math.cos(halfGammaPlusAlpha) * Math.cos(halfBeta);
+        return result;
     }
     /**
      * Creates a new quaternion containing the rotation value to reach the target (axis1, axis2, axis3) orientation as a rotated XYZ system (axis1, axis2 and axis3 are normalized during this operation)
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#75
      * @param axis1 defines the first axis
      * @param axis2 defines the second axis
      * @param axis3 defines the third axis
@@ -4017,19 +4118,23 @@ export class Quaternion {
     }
     /**
      * Creates a rotation value to reach the target (axis1, axis2, axis3) orientation as a rotated XYZ system (axis1, axis2 and axis3 are normalized during this operation) and stores it in the target quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#76
      * @param axis1 defines the first axis
      * @param axis2 defines the second axis
      * @param axis3 defines the third axis
      * @param ref defines the target quaternion
+     * @returns result input
      */
     static RotationQuaternionFromAxisToRef(axis1, axis2, axis3, ref) {
         const rotMat = MathTmp.Matrix[0];
         Matrix.FromXYZAxesToRef(axis1.normalize(), axis2.normalize(), axis3.normalize(), rotMat);
         Quaternion.FromRotationMatrixToRef(rotMat, ref);
+        return ref;
     }
     /**
      * Creates a new rotation value to orient an object to look towards the given forward direction, the up direction being oriented like "up".
      * This function works in left handed mode
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#96
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @returns A new quaternion oriented toward the specified forward and up.
@@ -4042,18 +4147,22 @@ export class Quaternion {
     /**
      * Creates a new rotation value to orient an object to look towards the given forward direction with the up direction being oriented like "up", and stores it in the target quaternion.
      * This function works in left handed mode
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#97
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @param ref defines the target quaternion.
+     * @returns result input
      */
     static FromLookDirectionLHToRef(forward, up, ref) {
         const rotMat = MathTmp.Matrix[0];
         Matrix.LookDirectionLHToRef(forward, up, rotMat);
         Quaternion.FromRotationMatrixToRef(rotMat, ref);
+        return ref;
     }
     /**
      * Creates a new rotation value to orient an object to look towards the given forward direction, the up direction being oriented like "up".
      * This function works in right handed mode
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#98
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @returns A new quaternion oriented toward the specified forward and up.
@@ -4066,9 +4175,11 @@ export class Quaternion {
     /**
      * Creates a new rotation value to orient an object to look towards the given forward direction with the up direction being oriented like "up", and stores it in the target quaternion.
      * This function works in right handed mode
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#105
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @param ref defines the target quaternion.
+     * @returns result input
      */
     static FromLookDirectionRHToRef(forward, up, ref) {
         const rotMat = MathTmp.Matrix[0];
@@ -4077,6 +4188,7 @@ export class Quaternion {
     }
     /**
      * Interpolates between two quaternions
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#79
      * @param left defines first quaternion
      * @param right defines second quaternion
      * @param amount defines the gradient to use
@@ -4089,10 +4201,12 @@ export class Quaternion {
     }
     /**
      * Interpolates between two quaternions and stores it into a target quaternion
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#92
      * @param left defines first quaternion
      * @param right defines second quaternion
      * @param amount defines the gradient to use
      * @param result defines the target quaternion
+     * @returns result input
      */
     static SlerpToRef(left, right, amount, result) {
         let num2;
@@ -4117,9 +4231,12 @@ export class Quaternion {
         result.y = num3 * left._y + num2 * right._y;
         result.z = num3 * left._z + num2 * right._z;
         result.w = num3 * left._w + num2 * right._w;
+        return result;
     }
     /**
      * Interpolate between two quaternions using Hermite interpolation
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#47
+     * @see https://doc.babylonjs.com/features/featuresDeepDive/mesh/drawCurves#hermite-quaternion-spline
      * @param value1 defines first quaternion
      * @param tangent1 defines the incoming tangent
      * @param value2 defines second quaternion
@@ -4138,10 +4255,11 @@ export class Quaternion {
         const y = value1._y * part1 + value2._y * part2 + tangent1._y * part3 + tangent2._y * part4;
         const z = value1._z * part1 + value2._z * part2 + tangent1._z * part3 + tangent2._z * part4;
         const w = value1._w * part1 + value2._w * part2 + tangent1._w * part3 + tangent2._w * part4;
-        return new Quaternion(x, y, z, w);
+        return new value1.constructor(x, y, z, w);
     }
     /**
      * Returns a new Quaternion which is the 1st derivative of the Hermite spline defined by the quaternions "value1", "value2", "tangent1", "tangent2".
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#48
      * @param value1 defines the first control point
      * @param tangent1 defines the first tangent
      * @param value2 defines the second control point
@@ -4150,18 +4268,20 @@ export class Quaternion {
      * @returns 1st derivative
      */
     static Hermite1stDerivative(value1, tangent1, value2, tangent2, time) {
-        const result = Quaternion.Zero();
+        const result = new value1.constructor();
         this.Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result);
         return result;
     }
     /**
      * Update a Quaternion with the 1st derivative of the Hermite spline defined by the quaternions "value1", "value2", "tangent1", "tangent2".
+     * Example Playground https://playground.babylonjs.com/#L49EJ7#49
      * @param value1 defines the first control point
      * @param tangent1 defines the first tangent
      * @param value2 defines the second control point
      * @param tangent2 defines the second tangent
      * @param time define where the derivative must be done
      * @param result define where to store the derivative
+     * @returns result input
      */
     static Hermite1stDerivativeToRef(value1, tangent1, value2, tangent2, time, result) {
         const t2 = time * time;
@@ -4169,6 +4289,7 @@ export class Quaternion {
         result.y = (t2 - time) * 6 * value1.y + (3 * t2 - 4 * time + 1) * tangent1.y + (-t2 + time) * 6 * value2.y + (3 * t2 - 2 * time) * tangent2.y;
         result.z = (t2 - time) * 6 * value1.z + (3 * t2 - 4 * time + 1) * tangent1.z + (-t2 + time) * 6 * value2.z + (3 * t2 - 2 * time) * tangent2.z;
         result.w = (t2 - time) * 6 * value1.w + (3 * t2 - 4 * time + 1) * tangent1.w + (-t2 + time) * 6 * value2.w + (3 * t2 - 2 * time) * tangent2.w;
+        return result;
     }
 }
 /**
@@ -4355,7 +4476,7 @@ export class Matrix {
      * @returns a new matrix as the addition of the current matrix and the given one
      */
     add(other) {
-        const result = new Matrix();
+        const result = new this.constructor();
         this.addToRef(other, result);
         return result;
     }
@@ -4363,7 +4484,7 @@ export class Matrix {
      * Sets the given matrix "result" to the addition of the current matrix and the given one
      * @param other defines the matrix to add
      * @param result defines the target matrix
-     * @returns the current matrix
+     * @returns result input
      */
     addToRef(other, result) {
         const m = this._m;
@@ -4373,7 +4494,7 @@ export class Matrix {
             resultM[index] = m[index] + otherM[index];
         }
         result.markAsUpdated();
-        return this;
+        return result;
     }
     /**
      * Adds in place the given matrix to the current matrix
@@ -4392,12 +4513,12 @@ export class Matrix {
     /**
      * Sets the given matrix to the current inverted Matrix
      * @param other defines the target matrix
-     * @returns the unmodified current matrix
+     * @returns result input
      */
     invertToRef(other) {
         if (this._isIdentity === true) {
             Matrix.IdentityToRef(other);
-            return this;
+            return other;
         }
         // the inverse of a Matrix is the transpose of cofactor matrix divided by the determinant
         const m = this._m;
@@ -4419,7 +4540,7 @@ export class Matrix {
         if (det === 0) {
             // not invertible
             other.copyFrom(this);
-            return this;
+            return other;
         }
         const detInv = 1 / det;
         const det_12_33 = m12 * m33 - m32 * m13;
@@ -4447,7 +4568,7 @@ export class Matrix {
         const cofact_32 = -(m00 * det_11_23 - m01 * det_10_23 + m03 * det_10_21);
         const cofact_33 = +(m00 * det_11_22 - m01 * det_10_22 + m02 * det_10_21);
         Matrix.FromValuesToRef(cofact_00 * detInv, cofact_10 * detInv, cofact_20 * detInv, cofact_30 * detInv, cofact_01 * detInv, cofact_11 * detInv, cofact_21 * detInv, cofact_31 * detInv, cofact_02 * detInv, cofact_12 * detInv, cofact_22 * detInv, cofact_32 * detInv, cofact_03 * detInv, cofact_13 * detInv, cofact_23 * detInv, cofact_33 * detInv, other);
-        return this;
+        return other;
     }
     /**
      * add a value at the specified position in the current Matrix
@@ -4523,7 +4644,7 @@ export class Matrix {
         result.x = this._m[12];
         result.y = this._m[13];
         result.z = this._m[14];
-        return this;
+        return result;
     }
     /**
      * Remove rotation and scaling part from the matrix
@@ -4541,7 +4662,7 @@ export class Matrix {
      * @returns a new matrix set with the multiplication result of the current Matrix and the given one
      */
     multiply(other) {
-        const result = new Matrix();
+        const result = new this.constructor();
         this.multiplyToRef(other, result);
         return result;
     }
@@ -4587,20 +4708,20 @@ export class Matrix {
      * Sets the given matrix "result" with the multiplication result of the current Matrix and the given one
      * @param other defines the second operand
      * @param result defines the matrix where to store the multiplication
-     * @returns the current matrix
+     * @returns result input
      */
     multiplyToRef(other, result) {
         if (this._isIdentity) {
             result.copyFrom(other);
-            return this;
+            return result;
         }
         if (other._isIdentity) {
             result.copyFrom(this);
-            return this;
+            return result;
         }
         this.multiplyToArray(other, result._m, 0);
         result.markAsUpdated();
-        return this;
+        return result;
     }
     /**
      * Sets the Float32Array "result" from the given index "offset" with the multiplication of the current matrix and the given one
@@ -4677,7 +4798,7 @@ export class Matrix {
      * @returns a new matrix from the current matrix
      */
     clone() {
-        const matrix = new Matrix();
+        const matrix = new this.constructor();
         matrix.copyFrom(this);
         return matrix;
     }
@@ -4779,7 +4900,7 @@ export class Matrix {
      * Gets specific row of the matrix to ref
      * @param index defines the number of the row to get
      * @param rowVector vector to store the index-th row of the current matrix
-     * @returns the current matrix
+     * @returns result input
      */
     getRowToRef(index, rowVector) {
         if (index >= 0 && index < 3) {
@@ -4789,7 +4910,7 @@ export class Matrix {
             rowVector.z = this._m[i + 2];
             rowVector.w = this._m[i + 3];
         }
-        return this;
+        return rowVector;
     }
     /**
      * Sets the index-th row of the current matrix to the vector4 values
@@ -4805,16 +4926,18 @@ export class Matrix {
      * @returns the new transposed matrix
      */
     transpose() {
-        return Matrix.Transpose(this);
+        const result = new this.constructor();
+        Matrix.TransposeToRef(this, result);
+        return result;
     }
     /**
      * Compute the transpose of the matrix and store it in a given matrix
      * @param result defines the target matrix
-     * @returns the current matrix
+     * @returns result input
      */
     transposeToRef(result) {
         Matrix.TransposeToRef(this, result);
-        return this;
+        return result;
     }
     /**
      * Sets the index-th row of the current matrix with the given 4 x float values
@@ -4843,7 +4966,7 @@ export class Matrix {
      * @returns a new matrix
      */
     scale(scale) {
-        const result = new Matrix();
+        const result = new this.constructor();
         this.scaleToRef(scale, result);
         return result;
     }
@@ -4851,27 +4974,27 @@ export class Matrix {
      * Scale the current matrix values by a factor to a given result matrix
      * @param scale defines the scale factor
      * @param result defines the matrix to store the result
-     * @returns the current matrix
+     * @returns result input
      */
     scaleToRef(scale, result) {
         for (let index = 0; index < 16; index++) {
             result._m[index] = this._m[index] * scale;
         }
         result.markAsUpdated();
-        return this;
+        return result;
     }
     /**
      * Scale the current matrix values by a factor and add the result to a given matrix
      * @param scale defines the scale factor
      * @param result defines the Matrix to store the result
-     * @returns the current matrix
+     * @returns result input
      */
     scaleAndAddToRef(scale, result) {
         for (let index = 0; index < 16; index++) {
             result._m[index] += this._m[index] * scale;
         }
         result.markAsUpdated();
-        return this;
+        return result;
     }
     /**
      * Writes to the given matrix a normal matrix, computed from this one (using values from identity matrix for fourth row and column).
@@ -4883,31 +5006,32 @@ export class Matrix {
         tmp.transposeToRef(ref);
         const m = ref._m;
         Matrix.FromValuesToRef(m[0], m[1], m[2], 0.0, m[4], m[5], m[6], 0.0, m[8], m[9], m[10], 0.0, 0.0, 0.0, 0.0, 1.0, ref);
+        return ref;
     }
     /**
      * Gets only rotation part of the current matrix
      * @returns a new matrix sets to the extracted rotation matrix from the current one
      */
     getRotationMatrix() {
-        const result = new Matrix();
+        const result = new this.constructor();
         this.getRotationMatrixToRef(result);
         return result;
     }
     /**
      * Extracts the rotation matrix from the current one and sets it as the given "result"
      * @param result defines the target matrix to store data to
-     * @returns the current matrix
+     * @returns result input
      */
     getRotationMatrixToRef(result) {
         const scale = MathTmp.Vector3[0];
         if (!this.decompose(scale)) {
             Matrix.IdentityToRef(result);
-            return this;
+            return result;
         }
         const m = this._m;
         const sx = 1 / scale._x, sy = 1 / scale._y, sz = 1 / scale._z;
         Matrix.FromValuesToRef(m[0] * sx, m[1] * sx, m[2] * sx, 0.0, m[4] * sy, m[5] * sy, m[6] * sy, 0.0, m[8] * sz, m[9] * sz, m[10] * sz, 0.0, 0.0, 0.0, 0.0, 1.0, result);
-        return this;
+        return result;
     }
     /**
      * Toggles model matrix from being right handed to left handed in place and vice versa
@@ -4920,6 +5044,7 @@ export class Matrix {
         m[9] *= -1;
         m[14] *= -1;
         this.markAsUpdated();
+        return this;
     }
     /**
      * Toggles projection matrix from being right handed to left handed in place and vice versa
@@ -4931,6 +5056,7 @@ export class Matrix {
         m[10] *= -1;
         m[11] *= -1;
         this.markAsUpdated();
+        return this;
     }
     // Statics
     /**
@@ -4949,12 +5075,14 @@ export class Matrix {
      * @param array defines the source array
      * @param offset defines an offset in the source array
      * @param result defines the target matrix
+     * @returns result input
      */
     static FromArrayToRef(array, offset, result) {
         for (let index = 0; index < 16; index++) {
             result._m[index] = array[index + offset];
         }
         result.markAsUpdated();
+        return result;
     }
     /**
      * Stores an array into a matrix after having multiplied each component by a given factor
@@ -4962,12 +5090,14 @@ export class Matrix {
      * @param offset defines the offset in the source array
      * @param scale defines the scaling factor
      * @param result defines the target matrix
+     * @returns result input
      */
     static FromFloat32ArrayToRefScaled(array, offset, scale, result) {
         for (let index = 0; index < 16; index++) {
             result._m[index] = array[index + offset] * scale;
         }
         result.markAsUpdated();
+        return result;
     }
     /**
      * Gets an identity matrix that must not be updated
@@ -4994,6 +5124,7 @@ export class Matrix {
      * @param initialM43 defines 3rd value of 4th row
      * @param initialM44 defines 4th value of 4th row
      * @param result defines the target matrix
+     * @returns result input
      */
     static FromValuesToRef(initialM11, initialM12, initialM13, initialM14, initialM21, initialM22, initialM23, initialM24, initialM31, initialM32, initialM33, initialM34, initialM41, initialM42, initialM43, initialM44, result) {
         const m = result._m;
@@ -5075,6 +5206,7 @@ export class Matrix {
      * @param rotation defines the rotation quaternion
      * @param translation defines the translation vector3
      * @param result defines the target matrix
+     * @returns result input
      */
     static ComposeToRef(scale, rotation, translation, result) {
         const m = result._m;
@@ -5101,6 +5233,7 @@ export class Matrix {
         m[14] = translation._z;
         m[15] = 1;
         result.markAsUpdated();
+        return result;
     }
     /**
      * Creates a new identity matrix
@@ -5114,10 +5247,12 @@ export class Matrix {
     /**
      * Creates a new identity matrix and stores the result in a given matrix
      * @param result defines the target matrix
+     * @returns result input
      */
     static IdentityToRef(result) {
         Matrix.FromValuesToRef(1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, result);
         result._updateIdentityStatus(true);
+        return result;
     }
     /**
      * Creates a new zero matrix
@@ -5144,7 +5279,7 @@ export class Matrix {
      * @returns the new matrix
      */
     static Invert(source) {
-        const result = new Matrix();
+        const result = new source.constructor();
         source.invertToRef(result);
         return result;
     }
@@ -5152,12 +5287,14 @@ export class Matrix {
      * Creates a new rotation matrix for "angle" radians around the X axis and stores it in a given matrix
      * @param angle defines the angle (in radians) to use
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationXToRef(angle, result) {
         const s = Math.sin(angle);
         const c = Math.cos(angle);
         Matrix.FromValuesToRef(1.0, 0.0, 0.0, 0.0, 0.0, c, s, 0.0, 0.0, -s, c, 0.0, 0.0, 0.0, 0.0, 1.0, result);
         result._updateIdentityStatus(c === 1 && s === 0);
+        return result;
     }
     /**
      * Creates a new rotation matrix for "angle" radians around the Y axis
@@ -5173,12 +5310,14 @@ export class Matrix {
      * Creates a new rotation matrix for "angle" radians around the Y axis and stores it in a given matrix
      * @param angle defines the angle (in radians) to use
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationYToRef(angle, result) {
         const s = Math.sin(angle);
         const c = Math.cos(angle);
         Matrix.FromValuesToRef(c, 0.0, -s, 0.0, 0.0, 1.0, 0.0, 0.0, s, 0.0, c, 0.0, 0.0, 0.0, 0.0, 1.0, result);
         result._updateIdentityStatus(c === 1 && s === 0);
+        return result;
     }
     /**
      * Creates a new rotation matrix for "angle" radians around the Z axis
@@ -5194,12 +5333,14 @@ export class Matrix {
      * Creates a new rotation matrix for "angle" radians around the Z axis and stores it in a given matrix
      * @param angle defines the angle (in radians) to use
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationZToRef(angle, result) {
         const s = Math.sin(angle);
         const c = Math.cos(angle);
         Matrix.FromValuesToRef(c, s, 0.0, 0.0, -s, c, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, result);
         result._updateIdentityStatus(c === 1 && s === 0);
+        return result;
     }
     /**
      * Creates a new rotation matrix for "angle" radians around the given axis
@@ -5217,6 +5358,7 @@ export class Matrix {
      * @param axis defines the axis to use
      * @param angle defines the angle (in radians) to use
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationAxisToRef(axis, angle, result) {
         const s = Math.sin(-angle);
@@ -5241,6 +5383,7 @@ export class Matrix {
         m[14] = 0.0;
         m[15] = 1.0;
         result.markAsUpdated();
+        return result;
     }
     /**
      * Takes normalised vectors and returns a rotation matrix to align "from" with "to".
@@ -5248,6 +5391,7 @@ export class Matrix {
      * @param from defines the vector to align
      * @param to defines the vector to align to
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationAlignToRef(from, to, result) {
         const c = Vector3.Dot(to, from);
@@ -5289,6 +5433,7 @@ export class Matrix {
         m[14] = 0;
         m[15] = 1;
         result.markAsUpdated();
+        return result;
     }
     /**
      * Creates a rotation matrix
@@ -5308,10 +5453,12 @@ export class Matrix {
      * @param pitch defines the pitch angle in radians (X axis)
      * @param roll defines the roll angle in radians (Z axis)
      * @param result defines the target matrix
+     * @returns result input
      */
     static RotationYawPitchRollToRef(yaw, pitch, roll, result) {
         Quaternion.RotationYawPitchRollToRef(yaw, pitch, roll, MathTmp.Quaternion[0]);
         MathTmp.Quaternion[0].toRotationMatrix(result);
+        return result;
     }
     /**
      * Creates a scaling matrix
@@ -5331,10 +5478,12 @@ export class Matrix {
      * @param y defines the scale factor on Y axis
      * @param z defines the scale factor on Z axis
      * @param result defines the target matrix
+     * @returns result input
      */
     static ScalingToRef(x, y, z, result) {
         Matrix.FromValuesToRef(x, 0.0, 0.0, 0.0, 0.0, y, 0.0, 0.0, 0.0, 0.0, z, 0.0, 0.0, 0.0, 0.0, 1.0, result);
         result._updateIdentityStatus(x === 1 && y === 1 && z === 1);
+        return result;
     }
     /**
      * Creates a translation matrix
@@ -5354,10 +5503,12 @@ export class Matrix {
      * @param y defines the translation on Y axis
      * @param z defines the translationon Z axis
      * @param result defines the target matrix
+     * @returns result input
      */
     static TranslationToRef(x, y, z, result) {
         Matrix.FromValuesToRef(1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, x, y, z, 1.0, result);
         result._updateIdentityStatus(x === 0 && y === 0 && z === 0);
+        return result;
     }
     /**
      * Returns a new Matrix whose values are the interpolated values for "gradient" (float) between the ones of the matrices "startValue" and "endValue".
@@ -5367,7 +5518,7 @@ export class Matrix {
      * @returns the new matrix
      */
     static Lerp(startValue, endValue, gradient) {
-        const result = new Matrix();
+        const result = new startValue.constructor();
         Matrix.LerpToRef(startValue, endValue, gradient, result);
         return result;
     }
@@ -5377,6 +5528,7 @@ export class Matrix {
      * @param endValue defines the end value
      * @param gradient defines the gradient factor
      * @param result defines the Matrix object where to store data
+     * @returns result input
      */
     static LerpToRef(startValue, endValue, gradient, result) {
         const resultM = result._m;
@@ -5386,6 +5538,7 @@ export class Matrix {
             resultM[index] = startM[index] * (1.0 - gradient) + endM[index] * gradient;
         }
         result.markAsUpdated();
+        return result;
     }
     /**
      * Builds a new matrix whose values are computed by:
@@ -5398,7 +5551,7 @@ export class Matrix {
      * @returns the new matrix
      */
     static DecomposeLerp(startValue, endValue, gradient) {
-        const result = new Matrix();
+        const result = new startValue.constructor();
         Matrix.DecomposeLerpToRef(startValue, endValue, gradient, result);
         return result;
     }
@@ -5411,6 +5564,7 @@ export class Matrix {
      * @param endValue defines the second matrix
      * @param gradient defines the gradient between the two matrices
      * @param result defines the target matrix
+     * @returns result input
      */
     static DecomposeLerpToRef(startValue, endValue, gradient, result) {
         const startScale = MathTmp.Vector3[0];
@@ -5428,6 +5582,7 @@ export class Matrix {
         const resultTranslation = MathTmp.Vector3[5];
         Vector3.LerpToRef(startTranslation, endTranslation, gradient, resultTranslation);
         Matrix.ComposeToRef(resultScale, resultRotation, resultTranslation, result);
+        return result;
     }
     /**
      * Gets a new rotation matrix used to rotate an entity so as it looks at the target vector3, from the eye vector3 position, the up vector3 being oriented like "up"
@@ -5449,6 +5604,7 @@ export class Matrix {
      * @param target defines where the entity should look at
      * @param up defines the up vector for the entity
      * @param result defines the target matrix
+     * @returns result input
      */
     static LookAtLHToRef(eye, target, up, result) {
         const xAxis = MathTmp.Vector3[0];
@@ -5495,6 +5651,7 @@ export class Matrix {
      * @param target defines where the entity should look at
      * @param up defines the up vector for the entity
      * @param result defines the target matrix
+     * @returns result input
      */
     static LookAtRHToRef(eye, target, up, result) {
         const xAxis = MathTmp.Vector3[0];
@@ -5520,6 +5677,7 @@ export class Matrix {
         const ey = -Vector3.Dot(yAxis, eye);
         const ez = -Vector3.Dot(zAxis, eye);
         Matrix.FromValuesToRef(xAxis._x, yAxis._x, zAxis._x, 0.0, xAxis._y, yAxis._y, zAxis._y, 0.0, xAxis._z, yAxis._z, zAxis._z, 0.0, ex, ey, ez, 1.0, result);
+        return result;
     }
     /**
      * Gets a new rotation matrix used to rotate an entity so as it looks in the direction specified by forward from the eye position, the up direction being oriented like "up".
@@ -5539,6 +5697,7 @@ export class Matrix {
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @param result defines the target matrix
+     * @returns result input
      */
     static LookDirectionLHToRef(forward, up, result) {
         const back = MathTmp.Vector3[0];
@@ -5548,6 +5707,7 @@ export class Matrix {
         Vector3.CrossToRef(up, back, left);
         // Generate the rotation matrix.
         Matrix.FromValuesToRef(left._x, left._y, left._z, 0.0, up._x, up._y, up._z, 0.0, back._x, back._y, back._z, 0.0, 0, 0, 0, 1.0, result);
+        return result;
     }
     /**
      * Gets a new rotation matrix used to rotate an entity so as it looks in the direction specified by forward from the eye position, the up Vector3 being oriented like "up".
@@ -5567,12 +5727,14 @@ export class Matrix {
      * @param forward defines the forward direction - Must be normalized and orthogonal to up.
      * @param up defines the up vector for the entity - Must be normalized and orthogonal to forward.
      * @param result defines the target matrix
+     * @returns result input
      */
     static LookDirectionRHToRef(forward, up, result) {
         const right = MathTmp.Vector3[2];
         Vector3.CrossToRef(up, forward, right);
         // Generate the rotation matrix.
         Matrix.FromValuesToRef(right._x, right._y, right._z, 0.0, up._x, up._y, up._z, 0.0, forward._x, forward._y, forward._z, 0.0, 0, 0, 0, 1.0, result);
+        return result;
     }
     /**
      * Create a left-handed orthographic projection matrix
@@ -5596,6 +5758,7 @@ export class Matrix {
      * @param zfar defines the far clip plane
      * @param result defines the target matrix
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
+     * @returns result input
      */
     static OrthoLHToRef(width, height, znear, zfar, result, halfZRange) {
         const n = znear;
@@ -5609,6 +5772,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result._updateIdentityStatus(a === 1 && b === 1 && c === 1 && d === 0);
+        return result;
     }
     /**
      * Create a left-handed orthographic projection matrix
@@ -5636,6 +5800,7 @@ export class Matrix {
      * @param zfar defines the far clip plane
      * @param result defines the target matrix
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
+     * @returns result input
      */
     static OrthoOffCenterLHToRef(left, right, bottom, top, znear, zfar, result, halfZRange) {
         const n = znear;
@@ -5651,6 +5816,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result.markAsUpdated();
+        return result;
     }
     /**
      * Creates a right-handed orthographic projection matrix
@@ -5678,10 +5844,12 @@ export class Matrix {
      * @param zfar defines the far clip plane
      * @param result defines the target matrix
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
+     * @returns result input
      */
     static OrthoOffCenterRHToRef(left, right, bottom, top, znear, zfar, result, halfZRange) {
         Matrix.OrthoOffCenterLHToRef(left, right, bottom, top, znear, zfar, result, halfZRange);
         result._m[10] *= -1; // No need to call markAsUpdated as previous function already called it and let _isIdentityDirty to true
+        return result;
     }
     /**
      * Creates a left-handed perspective projection matrix
@@ -5736,6 +5904,7 @@ export class Matrix {
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
      * @param projectionPlaneTilt optional tilt angle of the projection plane around the X axis (horizontal)
      * @param reverseDepthBufferMode true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)
+     * @returns result input
      */
     static PerspectiveFovLHToRef(fov, aspect, znear, zfar, result, isVerticalFovFixed = true, halfZRange, projectionPlaneTilt = 0, reverseDepthBufferMode = false) {
         const n = znear;
@@ -5751,6 +5920,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result._updateIdentityStatus(false);
+        return result;
     }
     /**
      * Stores a left-handed perspective projection into a given matrix with depth reversed
@@ -5762,6 +5932,7 @@ export class Matrix {
      * @param isVerticalFovFixed defines it the fov is vertically fixed (default) or horizontally
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
      * @param projectionPlaneTilt optional tilt angle of the projection plane around the X axis (horizontal)
+     * @returns result input
      */
     static PerspectiveFovReverseLHToRef(fov, aspect, znear, zfar, result, isVerticalFovFixed = true, halfZRange, projectionPlaneTilt = 0) {
         const t = 1.0 / Math.tan(fov * 0.5);
@@ -5773,6 +5944,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result._updateIdentityStatus(false);
+        return result;
     }
     /**
      * Creates a right-handed perspective projection matrix
@@ -5801,6 +5973,7 @@ export class Matrix {
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
      * @param projectionPlaneTilt optional tilt angle of the projection plane around the X axis (horizontal)
      * @param reverseDepthBufferMode true to indicate that we are in a reverse depth buffer mode (meaning znear and zfar have been inverted when calling the function)
+     * @returns result input
      */
     static PerspectiveFovRHToRef(fov, aspect, znear, zfar, result, isVerticalFovFixed = true, halfZRange, projectionPlaneTilt = 0, reverseDepthBufferMode = false) {
         //alternatively this could be expressed as:
@@ -5820,6 +5993,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result._updateIdentityStatus(false);
+        return result;
     }
     /**
      * Stores a right-handed perspective projection into a given matrix
@@ -5831,6 +6005,7 @@ export class Matrix {
      * @param isVerticalFovFixed defines it the fov is vertically fixed (default) or horizontally
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
      * @param projectionPlaneTilt optional tilt angle of the projection plane around the X axis (horizontal)
+     * @returns result input
      */
     static PerspectiveFovReverseRHToRef(fov, aspect, znear, zfar, result, isVerticalFovFixed = true, halfZRange, projectionPlaneTilt = 0) {
         const t = 1.0 / Math.tan(fov * 0.5);
@@ -5842,6 +6017,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result._updateIdentityStatus(false);
+        return result;
     }
     /**
      * Stores a perspective projection for WebVR info a given matrix
@@ -5856,6 +6032,7 @@ export class Matrix {
      * @param rightHanded defines if the matrix must be in right-handed mode (false by default)
      * @param halfZRange true to generate NDC coordinates between 0 and 1 instead of -1 and 1 (default: false)
      * @param projectionPlaneTilt optional tilt angle of the projection plane around the X axis (horizontal)
+     * @returns result input
      */
     static PerspectiveFovWebVRToRef(fov, znear, zfar, result, rightHanded = false, halfZRange, projectionPlaneTilt = 0) {
         const rightHandedFactor = rightHanded ? -1 : 1;
@@ -5882,6 +6059,7 @@ export class Matrix {
             result.multiplyToRef(mtxConvertNDCToHalfZRange, result);
         }
         result.markAsUpdated();
+        return result;
     }
     /**
      * Computes a complete transformation matrix
@@ -5899,10 +6077,10 @@ export class Matrix {
         const cx = viewport.x;
         const cy = viewport.y;
         const viewportMatrix = Matrix.FromValues(cw / 2.0, 0.0, 0.0, 0.0, 0.0, -ch / 2.0, 0.0, 0.0, 0.0, 0.0, zmax - zmin, 0.0, cx + cw / 2.0, ch / 2.0 + cy, zmin, 1.0);
-        const matrix = MathTmp.Matrix[0];
+        const matrix = new world.constructor();
         world.multiplyToRef(view, matrix);
         matrix.multiplyToRef(projection, matrix);
-        return matrix.multiply(viewportMatrix);
+        return matrix.multiplyToRef(viewportMatrix, matrix);
     }
     /**
      * Extracts a 2x2 matrix from a given matrix and store the result in a Float32Array
@@ -5930,7 +6108,7 @@ export class Matrix {
      * @returns the new matrix
      */
     static Transpose(matrix) {
-        const result = new Matrix();
+        const result = new matrix.constructor();
         Matrix.TransposeToRef(matrix, result);
         return result;
     }
@@ -5938,6 +6116,7 @@ export class Matrix {
      * Compute the transpose of a matrix and store it in a target matrix
      * @param matrix defines the matrix to transpose
      * @param result defines the target matrix
+     * @returns result input
      */
     static TransposeToRef(matrix, result) {
         const rm = result._m;
@@ -5961,6 +6140,7 @@ export class Matrix {
         result.markAsUpdated();
         // identity-ness does not change when transposing
         result._updateIdentityStatus(matrix._isIdentity, matrix._isIdentityDirty);
+        return result;
     }
     /**
      * Computes a reflection matrix from a plane
@@ -5976,6 +6156,7 @@ export class Matrix {
      * Computes a reflection matrix from a plane
      * @param plane defines the reflection plane
      * @param result defines the target matrix
+     * @returns result input
      */
     static ReflectionToRef(plane, result) {
         plane.normalize();
@@ -5986,6 +6167,7 @@ export class Matrix {
         const temp2 = -2 * y;
         const temp3 = -2 * z;
         Matrix.FromValuesToRef(temp * x + 1, temp2 * x, temp3 * x, 0.0, temp * y, temp2 * y + 1, temp3 * y, 0.0, temp * z, temp2 * z, temp3 * z + 1, 0.0, temp * plane.d, temp2 * plane.d, temp3 * plane.d, 1.0, result);
+        return result;
     }
     /**
      * Sets the given matrix as a rotation matrix composed from the 3 left handed axes
@@ -5993,14 +6175,17 @@ export class Matrix {
      * @param yaxis defines the value of the 2nd axis
      * @param zaxis defines the value of the 3rd axis
      * @param result defines the target matrix
+     * @returns result input
      */
     static FromXYZAxesToRef(xaxis, yaxis, zaxis, result) {
         Matrix.FromValuesToRef(xaxis._x, xaxis._y, xaxis._z, 0.0, yaxis._x, yaxis._y, yaxis._z, 0.0, zaxis._x, zaxis._y, zaxis._z, 0.0, 0.0, 0.0, 0.0, 1.0, result);
+        return result;
     }
     /**
      * Creates a rotation matrix from a quaternion and stores it in a target matrix
      * @param quat defines the quaternion to use
      * @param result defines the target matrix
+     * @returns result input
      */
     static FromQuaternionToRef(quat, result) {
         const xx = quat._x * quat._x;
@@ -6029,6 +6214,7 @@ export class Matrix {
         result._m[14] = 0.0;
         result._m[15] = 1.0;
         result.markAsUpdated();
+        return result;
     }
 }
 Matrix._UpdateFlagSeed = 0;