@babylonjs/core 5.17.1 → 5.20.0

package/Maths/math.vector.js

@@ -406,6 +406,16 @@ var Vector2 = /** @class */ (function () {
     Vector2.One = function () {
         return new Vector2(1, 1);
     };
+    Object.defineProperty(Vector2, "ZeroReadOnly", {
+        /**
+         * Gets a zero Vector2 that must not be updated
+         */
+        get: function () {
+            return Vector2._ZeroReadOnly;
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
      * Gets a new Vector2 set from the given index element of the given array
      * @param array defines the data source
@@ -677,6 +687,7 @@ var Vector2 = /** @class */ (function () {
         var proj = segA.add(v.multiplyByFloats(t, t));
         return Vector2.Distance(p, proj);
     };
+    Vector2._ZeroReadOnly = Vector2.Zero();
     return Vector2;
 }());
 export { Vector2 };
@@ -685,6 +696,7 @@ export { Vector2 };
  * A Vector3 is the main object used in 3D geometry
  * It can represent either the coordinates of a point the space, either a direction
  * Reminder: js uses a left handed forward facing system
+ * Example Playground - Overview - https://playground.babylonjs.com/#R1F8YU
  */
 var Vector3 = /** @class */ (function () {
     /**
@@ -741,6 +753,7 @@ var Vector3 = /** @class */ (function () {
     });
     /**
      * Creates a string representation of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#67
      * @returns a string with the Vector3 coordinates.
      */
     Vector3.prototype.toString = function () {
@@ -769,6 +782,7 @@ var Vector3 = /** @class */ (function () {
     // Operators
     /**
      * Creates an array containing three elements : the coordinates of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#10
      * @returns a new array of numbers
      */
     Vector3.prototype.asArray = function () {
@@ -778,6 +792,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Populates the given array or Float32Array from the given index with the successive coordinates of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#65
      * @param array defines the destination array
      * @param index defines the offset in the destination array
      * @returns the current Vector3
@@ -791,6 +806,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Update the current vector from an array
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#24
      * @param array defines the destination array
      * @param index defines the offset in the destination array
      * @returns the current Vector3
@@ -802,6 +818,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Converts the current Vector3 into a quaternion (considering that the Vector3 contains Euler angles representation of a rotation)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#66
      * @returns a new Quaternion object, computed from the Vector3 coordinates
      */
     Vector3.prototype.toQuaternion = function () {
@@ -809,6 +826,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Adds the given vector to the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#4
      * @param otherVector defines the second operand
      * @returns the current updated Vector3
      */
@@ -817,6 +835,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Adds the given coordinates to the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#5
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -830,6 +849,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets a new Vector3, result of the addition the current Vector3 and the given vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#3
      * @param otherVector defines the second operand
      * @returns the resulting Vector3
      */
@@ -838,6 +858,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Adds the current Vector3 to the given one and stores the result in the vector "result"
+     * 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
@@ -847,6 +868,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Subtract the given vector from the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#61
      * @param otherVector defines the second operand
      * @returns the current updated Vector3
      */
@@ -858,6 +880,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3, result of the subtraction of the given vector from the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#60
      * @param otherVector defines the second operand
      * @returns the resulting Vector3
      */
@@ -866,6 +889,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Subtracts the given vector from the current Vector3 and stores the result in the vector "result".
+     * 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
@@ -875,6 +899,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set with the subtraction of the given floats from the current Vector3 coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#62
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -885,6 +910,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Subtracts the given floats from the current Vector3 coordinates and set the given vector "result" with this result
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#64
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -896,6 +922,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets a new Vector3 set with the current Vector3 negated coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#35
      * @returns a new Vector3
      */
     Vector3.prototype.negate = function () {
@@ -903,6 +930,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Negate this vector in place
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#36
      * @returns this
      */
     Vector3.prototype.negateInPlace = function () {
@@ -913,6 +941,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * 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
      */
@@ -921,6 +950,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Multiplies the Vector3 coordinates by the float "scale"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#56
      * @param scale defines the multiplier factor
      * @returns the current updated Vector3
      */
@@ -932,6 +962,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set with the current Vector3 coordinates multiplied by the float "scale"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#53
      * @param scale defines the multiplier factor
      * @returns a new Vector3
      */
@@ -940,6 +971,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Multiplies the current Vector3 coordinates by the float "scale" and stores the result in the given vector "result" coordinates
+     * 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
@@ -949,6 +981,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * 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
@@ -965,6 +998,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Rotates the vector in place using the given unit quaternion
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#8
      * @param q the unit quaternion representing the rotation
      * @returns the current updated Vector3
      */
@@ -973,6 +1007,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Rotates the vector using the given unit quaternion and returns the new vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#7
      * @param q the unit quaternion representing the rotation
      * @returns a new Vector3
      */
@@ -981,6 +1016,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * 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
@@ -989,7 +1025,8 @@ var Vector3 = /** @class */ (function () {
         return result.addInPlaceFromFloats(this._x * scale, this._y * scale, this._z * scale);
     };
     /**
-     * Projects the current vector3 to a plane along a ray starting from a specified origin and directed towards the point.
+     * Projects the current point Vector3 to a plane along a ray starting from a specified origin and passing through the current point Vector3.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#48
      * @param plane defines the plane to project to
      * @param origin defines the origin of the projection ray
      * @returns the projected vector3
@@ -1000,44 +1037,34 @@ var Vector3 = /** @class */ (function () {
         return result;
     };
     /**
-     * Projects the current vector3 to a plane along a ray starting from a specified origin and directed towards the point.
+     * Projects the current point Vector3 to a plane along a ray starting from a specified origin and passing through the current point Vector3.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#49
      * @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
      */
     Vector3.prototype.projectOnPlaneToRef = function (plane, origin, result) {
-        // Use the normal scaled to the plane offset as the origin for the formula
-        var planeOrigin = MathTmp.Vector3[0];
-        plane.normal.scaleToRef(-plane.d, planeOrigin);
-        // Since the normal in Babylon should point toward the viewer, invert it for the dot product
-        var inverseNormal = MathTmp.Vector3[1];
-        plane.normal.negateToRef(inverseNormal);
-        // This vector is the direction
-        var _a = this, x = _a.x, y = _a.y, z = _a.z;
-        // Calculate how close the direction is to the normal of the plane
-        var dotProduct = Vector3.Dot(inverseNormal, this);
-        /*
-         * Early out in case the direction will never hit the plane.
-         *
-         * Epsilon is used to avoid issues with rays very near to parallel with the
-         * plane, and squared because as of writing the value is not sufficiently
-         * small for this use case.
-         */
-        if (dotProduct <= Epsilon * Epsilon) {
-            // No good option for setting the result vector here, so just take the origin of the ray
-            result.copyFrom(origin);
-            return;
+        var n = plane.normal;
+        var d = plane.d;
+        var V = MathTmp.Vector3[0];
+        // ray direction
+        this.subtractToRef(origin, V);
+        V.normalize();
+        var denom = Vector3.Dot(V, n);
+        //When the ray is close to parallel to the plane return infinity vector
+        if (Math.abs(denom) < Math.pow(10, -10)) {
+            result.setAll(Infinity);
+        }
+        else {
+            var t = -(Vector3.Dot(origin, n) + d) / denom;
+            // P = P0 + t*V
+            var scaledV = V.scaleInPlace(t);
+            origin.addToRef(scaledV, result);
         }
-        // Calculate the offset
-        var relativeOrigin = MathTmp.Vector3[2];
-        planeOrigin.subtractToRef(origin, relativeOrigin);
-        // Calculate the length along the direction vector to the hit point
-        var hitDistance = Vector3.Dot(relativeOrigin, inverseNormal) / dotProduct;
-        // Apply the hit point by adding the direction scaled by the distance to the origin
-        result.set(origin.x + x * hitDistance, origin.y + y * hitDistance, origin.z + z * hitDistance);
     };
     /**
      * Returns true if the current Vector3 and the given vector coordinates are strictly equal
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#19
      * @param otherVector defines the second operand
      * @returns true if both vectors are equals
      */
@@ -1046,6 +1073,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns true if the current Vector3 and the given vector coordinates are distant less than epsilon
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#21
      * @param otherVector defines the second operand
      * @param epsilon defines the minimal distance to define values as equals
      * @returns true if both vectors are distant less than epsilon
@@ -1059,16 +1087,18 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns true if the current Vector3 coordinates equals the given floats
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#20
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
-     * @returns true if both vectors are equals
+     * @returns true if both vectors are equal
      */
     Vector3.prototype.equalsToFloats = function (x, y, z) {
         return this._x === x && this._y === y && this._z === z;
     };
     /**
      * Multiplies the current Vector3 coordinates by the given ones
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#32
      * @param otherVector defines the second operand
      * @returns the current updated Vector3
      */
@@ -1080,6 +1110,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3, result of the multiplication of the current Vector3 by the given vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#31
      * @param otherVector defines the second operand
      * @returns the new Vector3
      */
@@ -1088,6 +1119,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Multiplies the current Vector3 by the given one and stores the result in the given vector "result"
+     * 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
@@ -1097,6 +1129,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set with the result of the multiplication of the current Vector3 coordinates by the given floats
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#34
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -1107,6 +1140,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set with the result of the division of the current Vector3 coordinates by the given ones
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#16
      * @param otherVector defines the second operand
      * @returns the new Vector3
      */
@@ -1115,6 +1149,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Divides the current Vector3 coordinates by the given ones and stores the result in the given vector "result"
+     * 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
@@ -1124,6 +1159,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Divides the current Vector3 coordinates by the given ones.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#17
      * @param otherVector defines the second operand
      * @returns the current updated Vector3
      */
@@ -1132,6 +1168,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Updates the current Vector3 with the minimal coordinate values between its and the given vector ones
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#29
      * @param other defines the second operand
      * @returns the current updated Vector3
      */
@@ -1140,6 +1177,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Updates the current Vector3 with the maximal coordinate values between its and the given vector ones.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#27
      * @param other defines the second operand
      * @returns the current updated Vector3
      */
@@ -1148,6 +1186,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Updates the current Vector3 with the minimal coordinate values between its and the given coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#30
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -1167,6 +1206,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Updates the current Vector3 with the maximal coordinate values between its and the given coordinates.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#28
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -1226,13 +1266,15 @@ var Vector3 = /** @class */ (function () {
     });
     /**
      * Gets a new Vector3 from current Vector3 floored values
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#22
      * @returns a new Vector3
      */
     Vector3.prototype.floor = function () {
         return new Vector3(Math.floor(this._x), Math.floor(this._y), Math.floor(this._z));
     };
     /**
-     * Gets a new Vector3 from current Vector3 floored values
+     * Gets a new Vector3 from current Vector3 fractional values
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#23
      * @returns a new Vector3
      */
     Vector3.prototype.fract = function () {
@@ -1241,6 +1283,7 @@ var Vector3 = /** @class */ (function () {
     // Properties
     /**
      * Gets the length of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#25
      * @returns the length of the Vector3
      */
     Vector3.prototype.length = function () {
@@ -1248,6 +1291,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets the squared length of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#26
      * @returns squared length of the Vector3
      */
     Vector3.prototype.lengthSquared = function () {
@@ -1256,6 +1300,7 @@ var Vector3 = /** @class */ (function () {
     Object.defineProperty(Vector3.prototype, "hasAZeroComponent", {
         /**
          * Gets a boolean indicating if the vector contains a zero in one of its components
+         * Example Playground https://playground.babylonjs.com/#R1F8YU#1
          */
         get: function () {
             return this._x * this._y * this._z === 0;
@@ -1266,6 +1311,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Normalize the current Vector3.
      * Please note that this is an in place operation.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#122
      * @returns the current updated Vector3
      */
     Vector3.prototype.normalize = function () {
@@ -1273,6 +1319,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Reorders the x y z properties of the vector in place
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#44
      * @param order new ordering of the properties (eg. for vector 1,2,3 with "ZYX" will produce 3,2,1)
      * @returns the current updated vector
      */
@@ -1290,6 +1337,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Rotates the vector around 0,0,0 by a quaternion
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#47
      * @param quaternion the rotation quaternion
      * @param result vector to store the result
      * @returns the resulting vector
@@ -1301,6 +1349,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Rotates a vector around a given point
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#46
      * @param quaternion the rotation quaternion
      * @param point the point to rotate around
      * @param result vector to store the result
@@ -1315,6 +1364,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Returns a new Vector3 as the cross product of the current vector and the "other" one
      * The cross product is then orthogonal to both current and "other"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#14
      * @param other defines the right operand
      * @returns the cross product
      */
@@ -1324,6 +1374,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Normalize the current Vector3 with the given input length.
      * Please note that this is an in place operation.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#123
      * @param len the length of the vector
      * @returns the current updated Vector3
      */
@@ -1335,6 +1386,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Normalize the current Vector3 to a new vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#124
      * @returns the new Vector3
      */
     Vector3.prototype.normalizeToNew = function () {
@@ -1344,6 +1396,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Normalize the current Vector3 to the reference
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#125
      * @param reference define the Vector3 to update
      * @returns the updated Vector3
      */
@@ -1356,6 +1409,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Creates a new Vector3 copied from the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#11
      * @returns the new Vector3
      */
     Vector3.prototype.clone = function () {
@@ -1363,6 +1417,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Copies the given vector coordinates to the current Vector3 ones
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#12
      * @param source defines the source Vector3
      * @returns the current updated Vector3
      */
@@ -1371,6 +1426,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Copies the given floats to the current Vector3 coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#13
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -1384,6 +1440,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Copies the given floats to the current Vector3 coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#58
      * @param x defines the x coordinate of the operand
      * @param y defines the y coordinate of the operand
      * @param z defines the z coordinate of the operand
@@ -1394,6 +1451,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Copies the given float to the current Vector3 coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#59
      * @param v defines the x, y and z coordinates of the operand
      * @returns the current updated Vector3
      */
@@ -1404,6 +1462,7 @@ var Vector3 = /** @class */ (function () {
     // Statics
     /**
      * Get the clip factor between two vectors
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#126
      * @param vector0 defines the first operand
      * @param vector1 defines the second operand
      * @param axis defines the axis to use
@@ -1418,6 +1477,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Get angle between two vectors
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#86
      * @param vector0 angle between vector0 and vector1
      * @param vector1 angle between vector0 and vector1
      * @param normal direction of the normal
@@ -1439,6 +1499,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Get angle between two vectors projected on a plane
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#87
      * @param vector0 angle between vector0 and vector1
      * @param vector1 angle between vector0 and vector1
      * @param normal Normal of the projection plane
@@ -1463,6 +1524,10 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Slerp between two vectors. See also `SmoothToRef`
+     * Slerp is a spherical linear interpolation
+     * giving a slow in and out effect
+     * Example Playground 1 https://playground.babylonjs.com/#R1F8YU#108
+     * Example Playground 2 https://playground.babylonjs.com/#R1F8YU#109
      * @param vector0 Start vector
      * @param vector1 End vector
      * @param slerp amount (will be clamped between 0 and 1)
@@ -1499,6 +1564,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Smooth interpolation between two vectors using Slerp
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#110
      * @param source source vector
      * @param goal goal vector
      * @param deltaTime current interpolation frame
@@ -1510,6 +1576,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set from the index "offset" of the given array
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#83
      * @param array defines the source array
      * @param offset defines the offset in the source array
      * @returns the new Vector3
@@ -1530,6 +1597,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Sets the given vector "result" with the element values from the index "offset" of the given array
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#84
      * @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
@@ -1551,6 +1619,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Sets the given vector "result" with the given floats.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#85
      * @param x defines the x coordinate of the source
      * @param y defines the y coordinate of the source
      * @param z defines the z coordinate of the source
@@ -1568,13 +1637,14 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set to (1.0, 1.0, 1.0)
-     * @returns a new unit Vector3
+     * @returns a new Vector3
      */
     Vector3.One = function () {
         return new Vector3(1.0, 1.0, 1.0);
     };
     /**
      * Returns a new Vector3 set to (0.0, 1.0, 0.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @returns a new up Vector3
      */
     Vector3.Up = function () {
@@ -1582,7 +1652,7 @@ var Vector3 = /** @class */ (function () {
     };
     Object.defineProperty(Vector3, "UpReadOnly", {
         /**
-         * Gets a up Vector3 that must not be updated
+         * Gets an up Vector3 that must not be updated
          */
         get: function () {
             return Vector3._UpReadOnly;
@@ -1590,6 +1660,16 @@ var Vector3 = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(Vector3, "DownReadOnly", {
+        /**
+         * Gets a down Vector3 that must not be updated
+         */
+        get: function () {
+            return Vector3._DownReadOnly;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(Vector3, "RightReadOnly", {
         /**
          * Gets a right Vector3 that must not be updated
@@ -1642,6 +1722,7 @@ var Vector3 = /** @class */ (function () {
     });
     /**
      * Returns a new Vector3 set to (0.0, -1.0, 0.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @returns a new down Vector3
      */
     Vector3.Down = function () {
@@ -1649,6 +1730,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set to (0.0, 0.0, 1.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @param rightHandedSystem is the scene right-handed (negative z)
      * @returns a new forward Vector3
      */
@@ -1658,8 +1740,9 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set to (0.0, 0.0, -1.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @param rightHandedSystem is the scene right-handed (negative-z)
-     * @returns a new forward Vector3
+     * @returns a new Backward Vector3
      */
     Vector3.Backward = function (rightHandedSystem) {
         if (rightHandedSystem === void 0) { rightHandedSystem = false; }
@@ -1667,6 +1750,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set to (1.0, 0.0, 0.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @returns a new right Vector3
      */
     Vector3.Right = function () {
@@ -1674,6 +1758,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 set to (-1.0, 0.0, 0.0)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#71
      * @returns a new left Vector3
      */
     Vector3.Left = function () {
@@ -1682,6 +1767,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Returns a new Vector3 set with the result of the transformation by the given matrix of the given vector.
      * This method computes transformed coordinates only, not transformed direction vectors (ie. it takes translation in account)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#111
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @returns the transformed Vector3
@@ -1694,6 +1780,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Sets the given vector "result" coordinates with the result of the transformation by the given matrix of the given vector
      * This method computes transformed coordinates only, not transformed direction vectors (ie. it takes translation in account)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#113
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
@@ -1704,6 +1791,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Sets the given vector "result" coordinates with the result of the transformation by the given matrix of the given floats (x, y, z)
      * This method computes transformed coordinates only, not transformed direction vectors
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#115
      * @param x define the x coordinate of the source vector
      * @param y define the y coordinate of the source vector
      * @param z define the z coordinate of the source vector
@@ -1723,6 +1811,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Returns a new Vector3 set with the result of the normal transformation by the given matrix of the given vector
      * This methods computes transformed normalized direction vectors only (ie. it does not apply translation)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#112
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @returns the new Vector3
@@ -1735,6 +1824,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Sets the given vector "result" with the result of the normal transformation by the given matrix of the given vector
      * This methods computes transformed normalized direction vectors only (ie. it does not apply translation)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#114
      * @param vector defines the Vector3 to transform
      * @param transformation defines the transformation matrix
      * @param result defines the Vector3 where to store the result
@@ -1745,6 +1835,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Sets the given vector "result" with the result of the normal transformation by the given matrix of the given floats (x, y, z)
      * This methods computes transformed normalized direction vectors only (ie. it does not apply translation)
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#116
      * @param x define the x coordinate of the source vector
      * @param y define the y coordinate of the source vector
      * @param z define the z coordinate of the source vector
@@ -1759,6 +1850,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 located for "amount" on the CatmullRom interpolation spline defined by the vectors "value1", "value2", "value3", "value4"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#69
      * @param value1 defines the first control point
      * @param value2 defines the second control point
      * @param value3 defines the third control point
@@ -1790,6 +1882,7 @@ var Vector3 = /** @class */ (function () {
      * 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"
      * If a coordinate value of "value" is lower than one of the "min" coordinate, then this "value" coordinate is set with the "min" one
      * If a coordinate value of "value" is greater than one of the "max" coordinate, then this "value" coordinate is set with the "max" one
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#76
      * @param value defines the current value
      * @param min defines the lower range value
      * @param max defines the upper range value
@@ -1804,6 +1897,7 @@ var Vector3 = /** @class */ (function () {
      * 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"
      * If a coordinate value of "value" is lower than one of the "min" coordinate, then this "value" coordinate is set with the "min" one
      * If a coordinate value of "value" is greater than one of the "max" coordinate, then this "value" coordinate is set with the "max" one
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#77
      * @param value defines the current value
      * @param min defines the lower range value
      * @param max defines the upper range value
@@ -1823,6 +1917,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Checks if a given vector is inside a specific range
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#75
      * @param v defines the vector to test
      * @param min defines the minimum range
      * @param max defines the maximum range
@@ -1833,6 +1928,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 located for "amount" (float) on the Hermite interpolation spline defined by the vectors "value1", "tangent1", "value2", "tangent2"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#89
      * @param value1 defines the first control point
      * @param tangent1 defines the first tangent vector
      * @param value2 defines the second control point
@@ -1854,6 +1950,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 which is the 1st derivative of the Hermite spline defined by the vectors "value1", "value2", "tangent1", "tangent2".
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#90
      * @param value1 defines the first control point
      * @param tangent1 defines the first tangent
      * @param value2 defines the second control point
@@ -1868,6 +1965,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Update a Vector3 with the 1st derivative of the Hermite spline defined by the vectors "value1", "value2", "tangent1", "tangent2".
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#91
      * @param value1 defines the first control point
      * @param tangent1 defines the first tangent
      * @param value2 defines the second control point
@@ -1883,6 +1981,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 located for "amount" (float) on the linear interpolation between the vectors "start" and "end"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#95
      * @param start defines the start value
      * @param end defines the end value
      * @param amount max defines amount between both (between 0 and 1)
@@ -1895,6 +1994,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Sets the given vector "result" with the result of the linear interpolation from the vector "start" for "amount" to the vector "end"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#93
      * @param start defines the start value
      * @param end defines the end value
      * @param amount max defines amount between both (between 0 and 1)
@@ -1907,6 +2007,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns the dot product (float) between the vectors "left" and "right"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#82
      * @param left defines the left operand
      * @param right defines the right operand
      * @returns the dot product
@@ -1917,6 +2018,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Returns a new Vector3 as the cross product of the vectors "left" and "right"
      * The cross product is then orthogonal to both "left" and "right"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#15
      * @param left defines the left operand
      * @param right defines the right operand
      * @returns the cross product
@@ -1929,6 +2031,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Sets the given vector "result" with the cross product of "left" and "right"
      * The cross product is then orthogonal to both "left" and "right"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#78
      * @param left defines the left operand
      * @param right defines the right operand
      * @param result defines the Vector3 where to store the result
@@ -1941,6 +2044,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 as the normalization of the given vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#98
      * @param vector defines the Vector3 to normalize
      * @returns the new Vector3
      */
@@ -1951,6 +2055,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Sets the given vector "result" with the normalization of the given first vector
+     * 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
      */
@@ -1959,6 +2064,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Project a Vector3 onto screen space
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#101
      * @param vector defines the Vector3 to project
      * @param world defines the world matrix to use
      * @param transform defines the transform (view x projection) matrix to use
@@ -1972,6 +2078,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Project a Vector3 onto screen space to reference
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#102
      * @param vector defines the Vector3 to project
      * @param world defines the world matrix to use
      * @param transform defines the transform (view x projection) matrix to use
@@ -2008,6 +2115,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Unproject from screen space to object space
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#121
      * @param source defines the screen space Vector3 to use
      * @param viewportWidth defines the current width of the viewport
      * @param viewportHeight defines the current height of the viewport
@@ -2020,6 +2128,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Unproject from screen space to object space
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#117
      * @param source defines the screen space Vector3 to use
      * @param viewportWidth defines the current width of the viewport
      * @param viewportHeight defines the current height of the viewport
@@ -2035,6 +2144,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Unproject from screen space to object space
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#119
      * @param source defines the screen space Vector3 to use
      * @param viewportWidth defines the current width of the viewport
      * @param viewportHeight defines the current height of the viewport
@@ -2048,6 +2158,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Unproject from screen space to object space
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#120
      * @param sourceX defines the screen space x coordinate to use
      * @param sourceY defines the screen space y coordinate to use
      * @param sourceZ defines the screen space z coordinate to use
@@ -2077,6 +2188,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets the minimal coordinate values between two Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#97
      * @param left defines the first operand
      * @param right defines the second operand
      * @returns the new Vector3
@@ -2088,6 +2200,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets the maximal coordinate values between two Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#96
      * @param left defines the first operand
      * @param right defines the second operand
      * @returns the new Vector3
@@ -2099,6 +2212,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns the distance between the vectors "value1" and "value2"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#81
      * @param value1 defines the first operand
      * @param value2 defines the second operand
      * @returns the distance
@@ -2108,6 +2222,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns the squared distance between the vectors "value1" and "value2"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#80
      * @param value1 defines the first operand
      * @param value2 defines the second operand
      * @returns the squared distance
@@ -2121,6 +2236,7 @@ var Vector3 = /** @class */ (function () {
     /**
      * Projects "vector" on the triangle determined by its extremities "p0", "p1" and "p2", stores the result in "ref"
      * and returns the distance to the projected point.
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#104
      * From http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.104.4264&rep=rep1&type=pdf
      *
      * @param vector the vector to get distance from
@@ -2259,6 +2375,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Returns a new Vector3 located at the center between "value1" and "value2"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#72
      * @param value1 defines the first operand
      * @param value2 defines the second operand
      * @returns the new Vector3
@@ -2268,6 +2385,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * Gets the center of the vectors "value1" and "value2" and stores the result in the vector "ref"
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#73
      * @param value1 defines first vector
      * @param value2 defines second vector
      * @param ref defines third vector
@@ -2281,6 +2399,7 @@ var Vector3 = /** @class */ (function () {
      * RotationFromAxis() returns the rotation Euler angles (ex : rotation.x, rotation.y, rotation.z) to apply
      * to something in order to rotate it from its local system to the given target system
      * Note: axis1, axis2 and axis3 are normalized during this operation
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#106
      * @param axis1 defines the first axis
      * @param axis2 defines the second axis
      * @param axis3 defines the third axis
@@ -2294,6 +2413,7 @@ var Vector3 = /** @class */ (function () {
     };
     /**
      * The same than RotationFromAxis but updates the given ref Vector3 parameter instead of returning a new Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#107
      * @param axis1 defines the first axis
      * @param axis2 defines the second axis
      * @param axis3 defines the third axis
@@ -2305,6 +2425,7 @@ var Vector3 = /** @class */ (function () {
         quat.toEulerAnglesToRef(ref);
     };
     Vector3._UpReadOnly = Vector3.Up();
+    Vector3._DownReadOnly = Vector3.Down();
     Vector3._LeftHandedForwardReadOnly = Vector3.Forward(false);
     Vector3._RightHandedForwardReadOnly = Vector3.Forward(true);
     Vector3._RightReadOnly = Vector3.Right();
@@ -2726,7 +2847,7 @@ var Vector4 = /** @class */ (function () {
         return new Vector4(Math.floor(this.x), Math.floor(this.y), Math.floor(this.z), Math.floor(this.w));
     };
     /**
-     * Gets a new Vector4 from current Vector3 floored values
+     * Gets a new Vector4 from current Vector4 fractional values
      * @returns a new Vector4
      */
     Vector4.prototype.fract = function () {
@@ -2882,6 +3003,16 @@ var Vector4 = /** @class */ (function () {
     Vector4.One = function () {
         return new Vector4(1.0, 1.0, 1.0, 1.0);
     };
+    Object.defineProperty(Vector4, "ZeroReadOnly", {
+        /**
+         * Gets a zero Vector4 that must not be updated
+         */
+        get: function () {
+            return Vector4._ZeroReadOnly;
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
      * Returns a new normalized Vector4 from the given one.
      * @param vector the vector to normalize
@@ -3065,6 +3196,7 @@ var Vector4 = /** @class */ (function () {
         if (w === void 0) { w = 0; }
         return new Vector4(source._x, source._y, source._z, w);
     };
+    Vector4._ZeroReadOnly = Vector4.Zero();
     return Vector4;
 }());
 export { Vector4 };