@babylonjs/core 5.24.0 → 5.26.0

package/Maths/math.vector.d.ts

@@ -178,7 +178,7 @@ export declare 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: Vector2): Vector2;
     /**
@@ -454,13 +454,13 @@ export declare class Vector3 {
     private static _RightReadOnly;
     private static _LeftReadOnly;
     private static _ZeroReadOnly;
-    /** @hidden */
+    /** @internal */
     _x: number;
-    /** @hidden */
+    /** @internal */
     _y: number;
-    /** @hidden */
+    /** @internal */
     _z: number;
-    /** @hidden */
+    /** @internal */
     _isDirty: boolean;
     /** Gets or sets the x coordinate */
     get x(): number;
@@ -550,7 +550,7 @@ export declare 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: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
@@ -572,7 +572,7 @@ export declare 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: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
@@ -591,7 +591,7 @@ export declare 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: number, y: number, z: number, result: Vector3): Vector3;
     /**
@@ -610,7 +610,7 @@ export declare 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: Vector3): Vector3;
     /**
@@ -632,15 +632,22 @@ export declare 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: number, result: Vector3): Vector3;
+    /**
+     * 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: DeepImmutable<Vector3>): Vector3;
     /**
      * 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: Quaternion, result: Vector3): Vector3;
     /**
@@ -724,7 +731,7 @@ export declare 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: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
@@ -748,7 +755,7 @@ export declare 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: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
@@ -957,6 +964,21 @@ export declare class Vector3 {
      * @returns the angle in radians (float) between vector0 and vector1 projected on the plane with the specified normal
      */
     static GetAngleBetweenVectorsOnPlane(vector0: Vector3, vector1: Vector3, normal: Vector3): number;
+    /**
+     * 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: Vector3, target: Vector3, ref: Vector3): Vector3;
+    /**
+     * 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: Vector3, target: Vector3): Vector3;
     /**
      * Slerp between two vectors. See also `SmoothToRef`
      * Slerp is a spherical linear interpolation
@@ -1308,10 +1330,7 @@ export declare class Vector3 {
      */
     static ProjectToRef(vector: DeepImmutable<Vector3>, world: DeepImmutable<Matrix>, transform: DeepImmutable<Matrix>, viewport: DeepImmutable<Viewport>, result: DeepImmutable<Vector3>): Vector3;
     /**
-     * @param source
-     * @param matrix
-     * @param result
-     * @hidden
+     * @internal
      */
     static _UnprojectFromInvertedMatrixToRef(source: DeepImmutable<Vector3>, matrix: DeepImmutable<Matrix>, result: Vector3): void;
     /**
@@ -1585,7 +1604,7 @@ export declare 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: Vector4): Vector4;
     /**
@@ -1929,15 +1948,15 @@ export declare class Vector4 {
  * @see https://doc.babylonjs.com/features/position,_rotation,_scaling
  */
 export declare class Quaternion {
-    /** @hidden */
+    /** @internal */
     _x: number;
-    /** @hidden */
+    /** @internal */
     _y: number;
-    /** @hidden */
+    /** @internal */
     _z: number;
-    /** @hidden */
+    /** @internal */
     _w: number;
-    /** @hidden */
+    /** @internal */
     _isDirty: boolean;
     /** Gets or sets the x coordinate */
     get x(): number;
@@ -2180,6 +2199,21 @@ export declare class Quaternion {
      * @param result defines the target quaternion
      */
     static FromRotationMatrixToRef(matrix: DeepImmutable<Matrix>, result: Quaternion): void;
+    /**
+     * 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: DeepImmutable<Vector3>, toVector: DeepImmutable<Vector3>): Quaternion;
+    /**
+     * 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: DeepImmutable<Vector3>, toVector: DeepImmutable<Vector3>, result: DeepImmutable<Quaternion>): Quaternion;
     /**
      * Returns the dot product (float) between the quaternions "left" and "right"
      * @param left defines the left operand
@@ -3281,7 +3315,7 @@ export declare class Matrix {
     static FromQuaternionToRef(quat: DeepImmutable<Quaternion>, result: Matrix): void;
 }
 /**
- * @hidden
+ * @internal
  */
 export declare class TmpVectors {
     static Vector2: [Vector2, Vector2, Vector2];

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);
@@ -694,7 +694,7 @@ export class Vector3 {
      * @param z defines the third coordinates (on Z axis)
      */
     constructor(x = 0, y = 0, z = 0) {
-        /** @hidden */
+        /** @internal */
         this._isDirty = true;
         this._x = x;
         this._y = y;
@@ -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
@@ -2031,10 +2084,7 @@ export class Vector3 {
         return result;
     }
     /**
-     * @param source
-     * @param matrix
-     * @param result
-     * @hidden
+     * @internal
      */
     static _UnprojectFromInvertedMatrixToRef(source, matrix, result) {
         Vector3.TransformCoordinatesToRef(source, matrix, result);
@@ -2569,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);
@@ -3133,7 +3183,7 @@ export class Quaternion {
      * @param w defines the fourth component (1.0 by default)
      */
     constructor(x = 0.0, y = 0.0, z = 0.0, w = 1.0) {
-        /** @hidden */
+        /** @internal */
         this._isDirty = true;
         this._x = x;
         this._y = y;
@@ -3611,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
@@ -5895,7 +5971,7 @@ export class Matrix {
 Matrix._UpdateFlagSeed = 0;
 Matrix._IdentityReadOnly = Matrix.Identity();
 /**
- * @hidden
+ * @internal
  * Same as Tmp but not exported to keep it only for math functions to avoid conflicts
  */
 class MathTmp {
@@ -5904,7 +5980,7 @@ MathTmp.Vector3 = ArrayTools.BuildTuple(11, Vector3.Zero);
 MathTmp.Matrix = ArrayTools.BuildTuple(2, Matrix.Identity);
 MathTmp.Quaternion = ArrayTools.BuildTuple(3, Quaternion.Zero);
 /**
- * @hidden
+ * @internal
  */
 export class TmpVectors {
 }