@babylonjs/core 5.25.0 → 5.26.1

package/Maths/math.vector.js

@@ -262,7 +262,7 @@ export class Vector2 {
     /**
      * Negate the current Vector2 and stores the result in the given vector "result" coordinates
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector2
+     * @returns the result
      */
     negateToRef(result) {
         return result.copyFromFloats(this.x * -1, this.y * -1);
@@ -832,7 +832,7 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#6
      * @param otherVector defines the second operand
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     addToRef(otherVector, result) {
         return result.copyFromFloats(this._x + otherVector._x, this._y + otherVector._y, this._z + otherVector._z);
@@ -863,7 +863,7 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#63
      * @param otherVector defines the second operand
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     subtractToRef(otherVector, result) {
         return this.subtractFromFloatsToRef(otherVector._x, otherVector._y, otherVector._z, result);
@@ -886,7 +886,7 @@ export class Vector3 {
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     subtractFromFloatsToRef(x, y, z, result) {
         return result.copyFromFloats(this._x - x, this._y - y, this._z - z);
@@ -914,7 +914,7 @@ export class Vector3 {
      * Negate the current Vector3 and stores the result in the given vector "result" coordinates
      * Example Playground https://playground.babylonjs.com/#R1F8YU#37
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     negateToRef(result) {
         return result.copyFromFloats(this._x * -1, this._y * -1, this._z * -1);
@@ -945,17 +945,45 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#57
      * @param scale defines the multiplier factor
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     scaleToRef(scale, result) {
         return result.copyFromFloats(this._x * scale, this._y * scale, this._z * scale);
     }
+    /**
+     * Creates a vector normal (perpendicular) to the current Vector3 and stores the result in the given vector
+     * @param result defines the Vector3 object where to store the resultant normal
+     * returns the result
+     * @hidden
+     */
+    _getNormalToRef(result) {
+        /**
+         * Calculates the spherical coordinates of the current vector
+         * so saves on memory rather than importing whole Spherical Class
+         */
+        const radius = this.length();
+        let theta = Math.acos(this.y / radius);
+        const phi = Math.atan2(this.z, this.x);
+        //makes angle 90 degs to current vector
+        if (theta > Math.PI / 2) {
+            theta -= Math.PI / 2;
+        }
+        else {
+            theta += Math.PI / 2;
+        }
+        //Calculates resutant normal vector from spherical coordinate of perpendicular vector
+        const x = radius * Math.sin(theta) * Math.cos(phi);
+        const y = radius * Math.cos(theta);
+        const z = radius * Math.sin(theta) * Math.sin(phi);
+        result.set(x, y, z);
+        return result;
+    }
     /**
      * Rotates the vector using the given unit quaternion and stores the new vector in result
      * Example Playground https://playground.babylonjs.com/#R1F8YU#9
      * @param q the unit quaternion representing the rotation
      * @param result the output vector
-     * @returns the current Vector3
+     * @returns the result
      */
     applyRotationQuaternionToRef(q, result) {
         const ix = q.w * this.x + q.y * this.z - q.z * this.y;
@@ -1092,7 +1120,7 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#33
      * @param otherVector defines the second operand
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     multiplyToRef(otherVector, result) {
         return result.copyFromFloats(this._x * otherVector._x, this._y * otherVector._y, this._z * otherVector._z);
@@ -1122,7 +1150,7 @@ export class Vector3 {
      * Example Playground https://playground.babylonjs.com/#R1F8YU#18
      * @param otherVector defines the second operand
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector3
+     * @returns the result
      */
     divideToRef(otherVector, result) {
         return result.copyFromFloats(this._x / otherVector._x, this._y / otherVector._y, this._z / otherVector._z);
@@ -1484,6 +1512,31 @@ export class Vector3 {
         const angle = Math.atan2(Vector3.Dot(v1, right), Vector3.Dot(v1, forward));
         return Scalar.NormalizeRadians(angle);
     }
+    /**
+     * Gets the rotation that aligns the roll axis (Y) to the line joining the start point to the target point and stores it in the ref Vector3
+     * @param start the starting point
+     * @param target the target point
+     * @param ref the vector3 to store the result
+     * @returns ref in the form (pitch, yaw, 0)
+     */
+    static PitchYawRollToMoveBetweenPointsToRef(start, target, ref) {
+        const diff = TmpVectors.Vector3[0];
+        target.subtractToRef(start, diff);
+        ref.y = Math.atan2(diff.x, diff.z) || 0;
+        ref.x = Math.atan2(Math.sqrt(diff.x ** 2 + diff.z ** 2), diff.y) || 0;
+        ref.z = 0;
+        return ref;
+    }
+    /**
+     * Gets the rotation that aligns the roll axis (Y) to the line joining the start point to the target point
+     * @param start the starting point
+     * @param target the target point
+     * @returns the rotation in the form (pitch, yaw, 0)
+     */
+    static PitchYawRollToMoveBetweenPoints(start, target) {
+        const ref = Vector3.Zero();
+        return Vector3.PitchYawRollToMoveBetweenPointsToRef(start, target, ref);
+    }
     /**
      * Slerp between two vectors. See also `SmoothToRef`
      * Slerp is a spherical linear interpolation
@@ -2566,7 +2619,7 @@ export class Vector4 {
     /**
      * Negate the current Vector4 and stores the result in the given vector "result" coordinates
      * @param result defines the Vector3 object where to store the result
-     * @returns the current Vector4
+     * @returns the result
      */
     negateToRef(result) {
         return result.copyFromFloats(this.x * -1, this.y * -1, this.z * -1, this.w * -1);
@@ -3608,6 +3661,32 @@ export class Quaternion {
             result.z = 0.25 * s;
         }
     }
+    /**
+     * Creates the rotation quaternion needed to rotate from one Vector3 onto another Vector3
+     * @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
+     * @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);
+    }
     /**
      * Returns the dot product (float) between the quaternions "left" and "right"
      * @param left defines the left operand