@babylonjs/core 5.17.1 → 5.20.0

package/Maths/math.vector.d.ts

@@ -11,6 +11,7 @@ export declare class Vector2 {
     x: number;
     /** defines the second coordinate */
     y: number;
+    private static _ZeroReadOnly;
     /**
      * Creates a new Vector2 from the given x and y coordinates
      * @param x defines the first coordinate
@@ -268,6 +269,10 @@ export declare class Vector2 {
      * @returns a new Vector2
      */
     static One(): Vector2;
+    /**
+     * Gets a zero Vector2 that must not be updated
+     */
+    static get ZeroReadOnly(): DeepImmutable<Vector2>;
     /**
      * Gets a new Vector2 set from the given index element of the given array
      * @param array defines the data source
@@ -439,9 +444,11 @@ export declare class 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
  */
 export declare class Vector3 {
     private static _UpReadOnly;
+    private static _DownReadOnly;
     private static _LeftHandedForwardReadOnly;
     private static _RightHandedForwardReadOnly;
     private static _RightReadOnly;
@@ -473,6 +480,7 @@ export declare class Vector3 {
     constructor(x?: number, y?: number, z?: number);
     /**
      * Creates a string representation of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#67
      * @returns a string with the Vector3 coordinates.
      */
     toString(): string;
@@ -488,11 +496,13 @@ export declare class Vector3 {
     getHashCode(): number;
     /**
      * 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
      */
     asArray(): number[];
     /**
      * 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
@@ -500,6 +510,7 @@ export declare class Vector3 {
     toArray(array: FloatArray, index?: number): Vector3;
     /**
      * 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
@@ -507,17 +518,20 @@ export declare class Vector3 {
     fromArray(array: FloatArray, index?: number): Vector3;
     /**
      * 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
      */
     toQuaternion(): Quaternion;
     /**
      * 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
      */
     addInPlace(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -526,12 +540,14 @@ export declare class Vector3 {
     addInPlaceFromFloats(x: number, y: number, z: number): Vector3;
     /**
      * 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
      */
     add(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -539,18 +555,21 @@ export declare class Vector3 {
     addToRef(otherVector: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
      * 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
      */
     subtractInPlace(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
      */
     subtract(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -558,6 +577,7 @@ export declare class Vector3 {
     subtractToRef(otherVector: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
      * 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
@@ -566,6 +586,7 @@ export declare class Vector3 {
     subtractFromFloats(x: number, y: number, z: number): Vector3;
     /**
      * 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
@@ -575,34 +596,40 @@ export declare class Vector3 {
     subtractFromFloatsToRef(x: number, y: number, z: number, result: Vector3): Vector3;
     /**
      * Gets a new Vector3 set with the current Vector3 negated coordinates
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#35
      * @returns a new Vector3
      */
     negate(): Vector3;
     /**
      * Negate this vector in place
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#36
      * @returns this
      */
     negateInPlace(): 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
      */
     negateToRef(result: Vector3): Vector3;
     /**
      * 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
      */
     scaleInPlace(scale: number): Vector3;
     /**
      * 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
      */
     scale(scale: number): Vector3;
     /**
      * 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
@@ -610,6 +637,7 @@ export declare class Vector3 {
     scaleToRef(scale: number, result: 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
@@ -617,32 +645,37 @@ export declare class Vector3 {
     applyRotationQuaternionToRef(q: Quaternion, result: Vector3): Vector3;
     /**
      * 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
      */
     applyRotationQuaternionInPlace(q: Quaternion): Vector3;
     /**
      * 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
      */
     applyRotationQuaternion(q: Quaternion): Vector3;
     /**
      * 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
      */
     scaleAndAddToRef(scale: number, result: Vector3): Vector3;
     /**
-     * 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
      */
     projectOnPlane(plane: Plane, origin: Vector3): Vector3;
     /**
-     * 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
@@ -650,12 +683,14 @@ export declare class Vector3 {
     projectOnPlaneToRef(plane: Plane, origin: Vector3, result: Vector3): void;
     /**
      * 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
      */
     equals(otherVector: DeepImmutable<Vector3>): boolean;
     /**
      * 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
@@ -663,26 +698,30 @@ export declare class Vector3 {
     equalsWithEpsilon(otherVector: DeepImmutable<Vector3>, epsilon?: number): boolean;
     /**
      * 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
      */
     equalsToFloats(x: number, y: number, z: number): boolean;
     /**
      * 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
      */
     multiplyInPlace(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
      */
     multiply(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -690,6 +729,7 @@ export declare class Vector3 {
     multiplyToRef(otherVector: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
      * 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
@@ -698,12 +738,14 @@ export declare class Vector3 {
     multiplyByFloats(x: number, y: number, z: number): Vector3;
     /**
      * 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
      */
     divide(otherVector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -711,24 +753,28 @@ export declare class Vector3 {
     divideToRef(otherVector: DeepImmutable<Vector3>, result: Vector3): Vector3;
     /**
      * 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
      */
     divideInPlace(otherVector: Vector3): Vector3;
     /**
      * 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
      */
     minimizeInPlace(other: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
      */
     maximizeInPlace(other: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -737,6 +783,7 @@ export declare class Vector3 {
     minimizeInPlaceFromFloats(x: number, y: number, z: number): Vector3;
     /**
      * 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
@@ -756,42 +803,50 @@ export declare class Vector3 {
     get isNonUniform(): boolean;
     /**
      * Gets a new Vector3 from current Vector3 floored values
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#22
      * @returns a new Vector3
      */
     floor(): Vector3;
     /**
-     * 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
      */
     fract(): Vector3;
     /**
      * Gets the length of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#25
      * @returns the length of the Vector3
      */
     length(): number;
     /**
      * Gets the squared length of the Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#26
      * @returns squared length of the Vector3
      */
     lengthSquared(): number;
     /**
      * Gets a boolean indicating if the vector contains a zero in one of its components
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#1
      */
     get hasAZeroComponent(): boolean;
     /**
      * 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
      */
     normalize(): Vector3;
     /**
      * 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
      */
     reorderInPlace(order: string): this;
     /**
      * 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
@@ -799,6 +854,7 @@ export declare class Vector3 {
     rotateByQuaternionToRef(quaternion: Quaternion, result: Vector3): Vector3;
     /**
      * 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
@@ -808,6 +864,7 @@ export declare class Vector3 {
     /**
      * 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
      */
@@ -815,34 +872,40 @@ export declare class Vector3 {
     /**
      * 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
      */
     normalizeFromLength(len: number): Vector3;
     /**
      * Normalize the current Vector3 to a new vector
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#124
      * @returns the new Vector3
      */
     normalizeToNew(): Vector3;
     /**
      * 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
      */
     normalizeToRef(reference: Vector3): Vector3;
     /**
      * Creates a new Vector3 copied from the current Vector3
+     * Example Playground https://playground.babylonjs.com/#R1F8YU#11
      * @returns the new Vector3
      */
     clone(): Vector3;
     /**
      * 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
      */
     copyFrom(source: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -851,6 +914,7 @@ export declare class Vector3 {
     copyFromFloats(x: number, y: number, z: number): Vector3;
     /**
      * 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
@@ -859,12 +923,14 @@ export declare class Vector3 {
     set(x: number, y: number, z: number): Vector3;
     /**
      * 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
      */
     setAll(v: number): Vector3;
     /**
      * 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
@@ -874,6 +940,7 @@ export declare class Vector3 {
     static GetClipFactor(vector0: DeepImmutable<Vector3>, vector1: DeepImmutable<Vector3>, axis: DeepImmutable<Vector3>, size: number): number;
     /**
      * 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
@@ -882,6 +949,7 @@ export declare class Vector3 {
     static GetAngleBetweenVectors(vector0: DeepImmutable<Vector3>, vector1: DeepImmutable<Vector3>, normal: DeepImmutable<Vector3>): number;
     /**
      * 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
@@ -890,6 +958,10 @@ export declare class Vector3 {
     static GetAngleBetweenVectorsOnPlane(vector0: Vector3, vector1: Vector3, normal: Vector3): number;
     /**
      * 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)
@@ -898,6 +970,7 @@ export declare class Vector3 {
     static SlerpToRef(vector0: Vector3, vector1: Vector3, slerp: number, result: Vector3): void;
     /**
      * 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
@@ -907,6 +980,7 @@ export declare class Vector3 {
     static SmoothToRef(source: Vector3, goal: Vector3, deltaTime: number, lerpTime: number, result: Vector3): void;
     /**
      * 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
@@ -922,6 +996,7 @@ export declare class Vector3 {
     static FromFloatArray(array: DeepImmutable<Float32Array>, offset?: number): Vector3;
     /**
      * 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
@@ -937,6 +1012,7 @@ export declare class Vector3 {
     static FromFloatArrayToRef(array: DeepImmutable<Float32Array>, offset: number, result: Vector3): void;
     /**
      * 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
@@ -950,18 +1026,23 @@ export declare class Vector3 {
     static Zero(): Vector3;
     /**
      * Returns a new Vector3 set to (1.0, 1.0, 1.0)
-     * @returns a new unit Vector3
+     * @returns a new Vector3
      */
     static One(): Vector3;
     /**
      * 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
      */
     static Up(): Vector3;
     /**
-     * Gets a up Vector3 that must not be updated
+     * Gets an up Vector3 that must not be updated
      */
     static get UpReadOnly(): DeepImmutable<Vector3>;
+    /**
+     * Gets a down Vector3 that must not be updated
+     */
+    static get DownReadOnly(): DeepImmutable<Vector3>;
     /**
      * Gets a right Vector3 that must not be updated
      */
@@ -984,34 +1065,40 @@ export declare class Vector3 {
     static get ZeroReadOnly(): DeepImmutable<Vector3>;
     /**
      * 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
      */
     static Down(): Vector3;
     /**
      * 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
      */
     static Forward(rightHandedSystem?: boolean): Vector3;
     /**
      * 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
      */
     static Backward(rightHandedSystem?: boolean): Vector3;
     /**
      * 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
      */
     static Right(): Vector3;
     /**
      * 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
      */
     static Left(): Vector3;
     /**
      * 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
@@ -1020,6 +1107,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1028,6 +1116,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1038,6 +1127,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1046,6 +1136,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1054,6 +1145,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1063,6 +1155,7 @@ export declare class Vector3 {
     static TransformNormalFromFloatsToRef(x: number, y: number, z: number, transformation: DeepImmutable<Matrix>, result: Vector3): void;
     /**
      * 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
@@ -1075,6 +1168,7 @@ export declare class Vector3 {
      * 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
@@ -1085,6 +1179,7 @@ export declare class Vector3 {
      * 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
@@ -1093,6 +1188,7 @@ export declare class Vector3 {
     static ClampToRef(value: DeepImmutable<Vector3>, min: DeepImmutable<Vector3>, max: DeepImmutable<Vector3>, result: Vector3): void;
     /**
      * 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
@@ -1100,6 +1196,7 @@ export declare class Vector3 {
     static CheckExtends(v: Vector3, min: Vector3, max: Vector3): void;
     /**
      * 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
@@ -1110,6 +1207,7 @@ export declare class Vector3 {
     static Hermite(value1: DeepImmutable<Vector3>, tangent1: DeepImmutable<Vector3>, value2: DeepImmutable<Vector3>, tangent2: DeepImmutable<Vector3>, amount: number): Vector3;
     /**
      * 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
@@ -1120,6 +1218,7 @@ export declare class Vector3 {
     static Hermite1stDerivative(value1: DeepImmutable<Vector3>, tangent1: DeepImmutable<Vector3>, value2: DeepImmutable<Vector3>, tangent2: DeepImmutable<Vector3>, time: number): Vector3;
     /**
      * 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
@@ -1130,6 +1229,7 @@ export declare class Vector3 {
     static Hermite1stDerivativeToRef(value1: DeepImmutable<Vector3>, tangent1: DeepImmutable<Vector3>, value2: DeepImmutable<Vector3>, tangent2: DeepImmutable<Vector3>, time: number, result: Vector3): void;
     /**
      * 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)
@@ -1138,6 +1238,7 @@ export declare class Vector3 {
     static Lerp(start: DeepImmutable<Vector3>, end: DeepImmutable<Vector3>, amount: number): Vector3;
     /**
      * 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)
@@ -1146,6 +1247,7 @@ export declare class Vector3 {
     static LerpToRef(start: DeepImmutable<Vector3>, end: DeepImmutable<Vector3>, amount: number, result: Vector3): void;
     /**
      * 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
@@ -1154,6 +1256,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1162,6 +1265,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1169,18 +1273,21 @@ export declare class Vector3 {
     static CrossToRef(left: DeepImmutable<Vector3>, right: DeepImmutable<Vector3>, result: Vector3): void;
     /**
      * 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
      */
     static Normalize(vector: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
      */
     static NormalizeToRef(vector: DeepImmutable<Vector3>, result: Vector3): void;
     /**
      * 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
@@ -1190,6 +1297,7 @@ export declare class Vector3 {
     static Project(vector: DeepImmutable<Vector3>, world: DeepImmutable<Matrix>, transform: DeepImmutable<Matrix>, viewport: DeepImmutable<Viewport>): Vector3;
     /**
      * 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
@@ -1207,6 +1315,7 @@ export declare class Vector3 {
     static _UnprojectFromInvertedMatrixToRef(source: DeepImmutable<Vector3>, matrix: DeepImmutable<Matrix>, result: Vector3): void;
     /**
      * 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
@@ -1217,6 +1326,7 @@ export declare class Vector3 {
     static UnprojectFromTransform(source: Vector3, viewportWidth: number, viewportHeight: number, world: DeepImmutable<Matrix>, transform: DeepImmutable<Matrix>): Vector3;
     /**
      * 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
@@ -1228,6 +1338,7 @@ export declare class Vector3 {
     static Unproject(source: DeepImmutable<Vector3>, viewportWidth: number, viewportHeight: number, world: DeepImmutable<Matrix>, view: DeepImmutable<Matrix>, projection: DeepImmutable<Matrix>): Vector3;
     /**
      * 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
@@ -1239,6 +1350,7 @@ export declare class Vector3 {
     static UnprojectToRef(source: DeepImmutable<Vector3>, viewportWidth: number, viewportHeight: number, world: DeepImmutable<Matrix>, view: DeepImmutable<Matrix>, projection: DeepImmutable<Matrix>, result: Vector3): void;
     /**
      * 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
@@ -1252,6 +1364,7 @@ export declare class Vector3 {
     static UnprojectFloatsToRef(sourceX: float, sourceY: float, sourceZ: float, viewportWidth: number, viewportHeight: number, world: DeepImmutable<Matrix>, view: DeepImmutable<Matrix>, projection: DeepImmutable<Matrix>, result: Vector3): void;
     /**
      * 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
@@ -1259,6 +1372,7 @@ export declare class Vector3 {
     static Minimize(left: DeepImmutable<Vector3>, right: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -1266,6 +1380,7 @@ export declare class Vector3 {
     static Maximize(left: DeepImmutable<Vector3>, right: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -1273,6 +1388,7 @@ export declare class Vector3 {
     static Distance(value1: DeepImmutable<Vector3>, value2: DeepImmutable<Vector3>): number;
     /**
      * 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
@@ -1281,6 +1397,7 @@ export declare class Vector3 {
     /**
      * 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
@@ -1293,6 +1410,7 @@ export declare class Vector3 {
     static ProjectOnTriangleToRef(vector: DeepImmutable<Vector3>, p0: DeepImmutable<Vector3>, p1: DeepImmutable<Vector3>, p2: DeepImmutable<Vector3>, ref: Vector3): number;
     /**
      * 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
@@ -1300,6 +1418,7 @@ export declare class Vector3 {
     static Center(value1: DeepImmutable<Vector3>, value2: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -1311,6 +1430,7 @@ export declare class Vector3 {
      * 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
@@ -1320,6 +1440,7 @@ export declare class Vector3 {
     static RotationFromAxis(axis1: DeepImmutable<Vector3>, axis2: DeepImmutable<Vector3>, axis3: DeepImmutable<Vector3>): Vector3;
     /**
      * 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
@@ -1339,6 +1460,7 @@ export declare class Vector4 {
     z: number;
     /** w value of the vector */
     w: number;
+    private static _ZeroReadOnly;
     /**
      * Creates a Vector4 object from the given floats.
      * @param x x value of the vector
@@ -1578,7 +1700,7 @@ export declare class Vector4 {
      */
     floor(): Vector4;
     /**
-     * Gets a new Vector4 from current Vector3 floored values
+     * Gets a new Vector4 from current Vector4 fractional values
      * @returns a new Vector4
      */
     fract(): Vector4;
@@ -1677,6 +1799,10 @@ export declare class Vector4 {
      * @returns the new vector
      */
     static One(): Vector4;
+    /**
+     * Gets a zero Vector4 that must not be updated
+     */
+    static get ZeroReadOnly(): DeepImmutable<Vector4>;
     /**
      * Returns a new normalized Vector4 from the given one.
      * @param vector the vector to normalize