Nightly

dist/preview release/babylon.max.js

@@ -1004,11 +1004,29 @@ var BABYLON;
     BABYLON.ToGammaSpace = 1 / 2.2;
     BABYLON.ToLinearSpace = 2.2;
     BABYLON.Epsilon = 0.001;
+    /**
+     * Class used to hold a RBG color
+     */
     var Color3 = /** @class */ (function () {
         /**
-         * Creates a new Color3 object from red, green, blue values, all between 0 and 1.
+         * Creates a new Color3 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
          */
-        function Color3(r, g, b) {
+        function Color3(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1017,19 +1035,22 @@ var BABYLON;
             this.b = b;
         }
         /**
-         * Returns a string with the Color3 current values.
+         * Creates a string with the Color3 current values
+         * @returns the string representation of the Color3 object
          */
         Color3.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + "}";
         };
         /**
-         * Returns the string "Color3".
+         * Returns the string "Color3"
+         * @returns "Color3"
          */
         Color3.prototype.getClassName = function () {
             return "Color3";
         };
         /**
-         * Returns the Color3 hash code.
+         * Compute the Color3 hash code
+         * @returns an unique number that can be used to hash Color3 objects
          */
         Color3.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1039,8 +1060,10 @@ var BABYLON;
         };
         // Operators
         /**
-         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements.
-         * Returns the Color3.
+         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color3 object
          */
         Color3.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1052,14 +1075,17 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 object from the current Color3 and the passed alpha.
+         * Returns a new {BABYLON.Color4} object from the current Color3 and the passed alpha
+         * @param alpha defines the alpha component on the new {BABYLON.Color4} object (default is 1)
+         * @returns a new {BABYLON.Color4} object
          */
         Color3.prototype.toColor4 = function (alpha) {
             if (alpha === void 0) { alpha = 1; }
             return new Color4(this.r, this.g, this.b, alpha);
         };
         /**
-         * Returns a new array populated with 3 numeric elements : red, green and blue values.
+         * Returns a new array populated with 3 numeric elements : red, green and blue values
+         * @returns the new array
          */
         Color3.prototype.asArray = function () {
             var result = new Array();
@@ -1067,21 +1093,25 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns the luminance value (float).
+         * Returns the luminance value
+         * @returns a float value
          */
         Color3.prototype.toLuminance = function () {
             return this.r * 0.3 + this.g * 0.59 + this.b * 0.11;
         };
         /**
-         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object.
-         * Returns this new object.
+         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object
+         * @param otherColor defines the second operand
+         * @returns the new Color3 object
          */
         Color3.prototype.multiply = function (otherColor) {
             return new Color3(this.r * otherColor.r, this.g * otherColor.g, this.b * otherColor.b);
         };
         /**
-         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result".
-         * Returns the current Color3.
+         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result"
+         * @param otherColor defines the second operand
+         * @param result defines the Color3 object where to store the result
+         * @returns the current Color3
          */
         Color3.prototype.multiplyToRef = function (otherColor, result) {
             result.r = this.r * otherColor.r;
@@ -1090,27 +1120,36 @@ var BABYLON;
             return this;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between Color3 objects
+         * @param otherColor defines the second operand
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equals = function (otherColor) {
             return otherColor && this.r === otherColor.r && this.g === otherColor.g && this.b === otherColor.b;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between the current Color3 object and a set of r,b,g values
+         * @param r defines the red component to check
+         * @param g defines the green component to check
+         * @param b defines the blue component to check
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equalsFloats = function (r, g, b) {
             return this.r === r && this.g === g && this.b === b;
         };
         /**
-         * Multiplies in place each rgb value by scale.
-         * Returns the updated Color3.
+         * Multiplies in place each rgb value by scale
+         * @param scale defines the scaling factor
+         * @returns the updated Color3.
          */
         Color3.prototype.scale = function (scale) {
             return new Color3(this.r * scale, this.g * scale, this.b * scale);
         };
         /**
-         * Multiplies the rgb values by scale and stores the result into "result".
-         * Returns the unmodified current Color3.
+         * Multiplies the rgb values by scale and stores the result into "result"
+         * @param scale defines the scaling factor
+         * @param result defines the Color3 object where to store the result
+         * @returns the unmodified current Color3.
          */
         Color3.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1119,12 +1158,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color3.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color3
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into
+         * @returns the original Color3
          */
         Color3.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1135,14 +1173,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the added values of the current Color3 and of the passed one.
+         * Creates a new Color3 set with the added values of the current Color3 and of the passed one
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.add = function (otherColor) {
             return new Color3(this.r + otherColor.r, this.g + otherColor.g, this.b + otherColor.b);
         };
         /**
-         * Stores the result of the addition of the current Color3 and passed one rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the addition of the current Color3 and passed one rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.addToRef = function (otherColor, result) {
             result.r = this.r + otherColor.r;
@@ -1151,14 +1193,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3 .
+         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.subtract = function (otherColor) {
             return new Color3(this.r - otherColor.r, this.g - otherColor.g, this.b - otherColor.b);
         };
         /**
-         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.subtractToRef = function (otherColor, result) {
             result.r = this.r - otherColor.r;
@@ -1167,14 +1213,16 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 copied the current one.
+         * Copy the current object
+         * @returns a new Color3 copied the current one
          */
         Color3.prototype.clone = function () {
             return new Color3(this.r, this.g, this.b);
         };
         /**
-         * Copies the rgb values from the source in the current Color3.
-         * Returns the updated Color3.
+         * Copies the rgb values from the source in the current Color3
+         * @param source defines the source Color3 object
+         * @returns the updated Color3 object
          */
         Color3.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1183,8 +1231,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.copyFromFloats = function (r, g, b) {
             this.r = r;
@@ -1193,14 +1244,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.set = function (r, g, b) {
             return this.copyFromFloats(r, g, b);
         };
         /**
-         * Returns the Color3 hexadecimal code as a string.
+         * Compute the Color3 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color3 object
          */
         Color3.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1209,7 +1264,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB);
         };
         /**
-         * Returns a new Color3 converted to linear space.
+         * Computes a new Color3 converted from the current one to linear space
+         * @returns a new Color3 object
          */
         Color3.prototype.toLinearSpace = function () {
             var convertedColor = new Color3();
@@ -1217,8 +1273,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the linear space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1227,7 +1284,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 converted to gamma space.
+         * Computes a new Color3 converted from the current one to gamma space
+         * @returns a new Color3 object
          */
         Color3.prototype.toGammaSpace = function () {
             var convertedColor = new Color3();
@@ -1235,8 +1293,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the gamma space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1246,7 +1305,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color3 from the string containing valid hexadecimal values.
+         * Creates a new Color3 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color3 object
          */
         Color3.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 7) {
@@ -1259,20 +1320,31 @@ var BABYLON;
             return Color3.FromInts(r, g, b);
         };
         /**
-         * Creates a new Vector3 from the startind index of the passed array.
+         * Creates a new Vector3 from the starting index of the passed array
+         * @param array defines the source array
+         * @param offset defines an offset in the source array
+         * @returns a new Color3 object
          */
         Color3.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color3(array[offset], array[offset + 1], array[offset + 2]);
         };
         /**
-         * Creates a new Color3 from integer values ( < 256).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color3.FromInts = function (r, g, b) {
             return new Color3(r / 255.0, g / 255.0, b / 255.0);
         };
         /**
-         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3.
+         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3
+         * @param start defines the start Color3 value
+         * @param end defines the end Color3 value
+         * @param amount defines the gradient value between start and end
+         * @returns a new Color3 object
          */
         Color3.Lerp = function (start, end, amount) {
             var r = start.r + ((end.r - start.r) * amount);
@@ -1280,25 +1352,92 @@ var BABYLON;
             var b = start.b + ((end.b - start.b) * amount);
             return new Color3(r, g, b);
         };
+        /**
+         * Returns a Color3 value containing a red color
+         * @returns a new Color3 object
+         */
         Color3.Red = function () { return new Color3(1, 0, 0); };
+        /**
+         * Returns a Color3 value containing a green color
+         * @returns a new Color3 object
+         */
         Color3.Green = function () { return new Color3(0, 1, 0); };
+        /**
+         * Returns a Color3 value containing a blue color
+         * @returns a new Color3 object
+         */
         Color3.Blue = function () { return new Color3(0, 0, 1); };
+        /**
+         * Returns a Color3 value containing a black color
+         * @returns a new Color3 object
+         */
         Color3.Black = function () { return new Color3(0, 0, 0); };
+        /**
+         * Returns a Color3 value containing a white color
+         * @returns a new Color3 object
+         */
         Color3.White = function () { return new Color3(1, 1, 1); };
+        /**
+         * Returns a Color3 value containing a purple color
+         * @returns a new Color3 object
+         */
         Color3.Purple = function () { return new Color3(0.5, 0, 0.5); };
+        /**
+         * Returns a Color3 value containing a magenta color
+         * @returns a new Color3 object
+         */
         Color3.Magenta = function () { return new Color3(1, 0, 1); };
+        /**
+         * Returns a Color3 value containing a yellow color
+         * @returns a new Color3 object
+         */
         Color3.Yellow = function () { return new Color3(1, 1, 0); };
+        /**
+         * Returns a Color3 value containing a gray color
+         * @returns a new Color3 object
+         */
         Color3.Gray = function () { return new Color3(0.5, 0.5, 0.5); };
+        /**
+         * Returns a Color3 value containing a teal color
+         * @returns a new Color3 object
+         */
         Color3.Teal = function () { return new Color3(0, 1.0, 1.0); };
+        /**
+         * Returns a Color3 value containing a random color
+         * @returns a new Color3 object
+         */
         Color3.Random = function () { return new Color3(Math.random(), Math.random(), Math.random()); };
         return Color3;
     }());
     BABYLON.Color3 = Color3;
+    /**
+     * Class used to hold a RBGA color
+     */
     var Color4 = /** @class */ (function () {
         /**
-         * Creates a new Color4 object from the passed float values ( < 1) : red, green, blue, alpha.
+         * Creates a new Color4 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
+         * @param a defines the alpha component (between 0 and 1, default is 1)
          */
-        function Color4(r, g, b, a) {
+        function Color4(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b, 
+            /**
+             * Defines the alpha component (between 0 and 1, default is 1)
+             */
+            a) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1310,8 +1449,9 @@ var BABYLON;
         }
         // Operators
         /**
-         * Adds in place the passed Color4 values to the current Color4.
-         * Returns the updated Color4.
+         * Adds in place the passed Color4 values to the current Color4 object
+         * @param right defines the second operand
+         * @returns the current updated Color4 object
          */
         Color4.prototype.addInPlace = function (right) {
             this.r += right.r;
@@ -1321,7 +1461,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new array populated with 4 numeric elements : red, green, blue, alpha values.
+         * Creates a new array populated with 4 numeric elements : red, green, blue, alpha values
+         * @returns the new array
          */
         Color4.prototype.asArray = function () {
             var result = new Array();
@@ -1329,8 +1470,10 @@ var BABYLON;
             return result;
         };
         /**
-         * Stores from the starting index in the passed array the Color4 successive values.
-         * Returns the Color4.
+         * Stores from the starting index in the passed array the Color4 successive values
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color4 object
          */
         Color4.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1343,20 +1486,26 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 set with the added values of the current Color4 and of the passed one.
+         * Creates a new Color4 set with the added values of the current Color4 and of the passed one
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.add = function (right) {
             return new Color4(this.r + right.r, this.g + right.g, this.b + right.b, this.a + right.a);
         };
         /**
-         * Returns a new Color4 set with the subtracted values of the passed one from the current Color4.
+         * Creates a new Color4 set with the subtracted values of the passed one from the current Color4
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.subtract = function (right) {
             return new Color4(this.r - right.r, this.g - right.g, this.b - right.b, this.a - right.a);
         };
         /**
-         * Subtracts the passed ones from the current Color4 values and stores the results in "result".
-         * Returns the Color4.
+         * Subtracts the passed ones from the current Color4 values and stores the results in "result"
+         * @param right defines the second operand
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4 object
          */
         Color4.prototype.subtractToRef = function (right, result) {
             result.r = this.r - right.r;
@@ -1366,14 +1515,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Creates a new Color4 with the current Color4 values multiplied by scale.
+         * Creates a new Color4 with the current Color4 values multiplied by scale
+         * @param scale defines the scaling factor to apply
+         * @returns a new Color4 object
          */
         Color4.prototype.scale = function (scale) {
             return new Color4(this.r * scale, this.g * scale, this.b * scale, this.a * scale);
         };
         /**
-         * Multiplies the current Color4 values by scale and stores the result in "result".
-         * Returns the Color4.
+         * Multiplies the current Color4 values by scale and stores the result in "result"
+         * @param scale defines the scaling factor to apply
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4.
          */
         Color4.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1383,12 +1536,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color4.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color4
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into.
+         * @returns the cuurent Color4
          */
         Color4.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1400,18 +1552,18 @@ var BABYLON;
             return this;
         };
         /**
-          * Multipy an RGBA Color4 value by another and return a new Color4 object
-          * @param color The Color4 (RGBA) value to multiply by
-          * @returns A new Color4.
+          * Multipy an Color4 value by another and return a new Color4 object
+          * @param color defines the Color4 value to multiply by
+          * @returns a new Color4 object
           */
         Color4.prototype.multiply = function (color) {
             return new Color4(this.r * color.r, this.g * color.g, this.b * color.b, this.a * color.a);
         };
         /**
-         * Multipy an RGBA Color4 value by another and push the result in a reference value
-         * @param color The Color4 (RGBA) value to multiply by
-         * @param result The Color4 (RGBA) to fill the result in
-         * @returns the result Color4.
+         * Multipy a Color4 value by another and push the result in a reference value
+         * @param color defines the Color4 value to multiply by
+         * @param result defines the Color4 to fill the result in
+         * @returns the result Color4
          */
         Color4.prototype.multiplyToRef = function (color, result) {
             result.r = this.r * color.r;
@@ -1421,19 +1573,22 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns a string with the Color4 values.
+         * Creates a string with the Color4 current values
+         * @returns the string representation of the Color4 object
          */
         Color4.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + " A:" + this.a + "}";
         };
         /**
          * Returns the string "Color4"
+         * @returns "Color4"
          */
         Color4.prototype.getClassName = function () {
             return "Color4";
         };
         /**
-         * Return the Color4 hash code as a number.
+         * Compute the Color4 hash code
+         * @returns an unique number that can be used to hash Color4 objects
          */
         Color4.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1443,14 +1598,16 @@ var BABYLON;
             return hash;
         };
         /**
-         * Creates a new Color4 copied from the current one.
+         * Creates a new Color4 copied from the current one
+         * @returns a new Color4 object
          */
         Color4.prototype.clone = function () {
             return new Color4(this.r, this.g, this.b, this.a);
         };
         /**
-         * Copies the passed Color4 values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed Color4 values into the current one
+         * @param source defines the source Color4 object
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1460,8 +1617,12 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFromFloats = function (r, g, b, a) {
             this.r = r;
@@ -1471,14 +1632,19 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.set = function (r, g, b, a) {
             return this.copyFromFloats(r, g, b, a);
         };
         /**
-         * Returns a string containing the hexadecimal Color4 code.
+         * Compute the Color4 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color4 object
          */
         Color4.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1488,7 +1654,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB) + BABYLON.Scalar.ToHex(intA);
         };
         /**
-         * Returns a new Color4 converted to linear space.
+         * Computes a new Color4 converted from the current one to linear space
+         * @returns a new Color4 object
          */
         Color4.prototype.toLinearSpace = function () {
             var convertedColor = new Color4();
@@ -1496,8 +1663,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the linear space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1507,7 +1675,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 converted to gamma space.
+         * Computes a new Color4 converted from the current one to gamma space
+         * @returns a new Color4 object
          */
         Color4.prototype.toGammaSpace = function () {
             var convertedColor = new Color4();
@@ -1515,8 +1684,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the gamma space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1527,7 +1697,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color4 from the valid hexadecimal value contained in the passed string.
+         * Creates a new Color4 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color4 object
          */
         Color4.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 9) {
@@ -1541,7 +1713,11 @@ var BABYLON;
             return Color4.FromInts(r, g, b, a);
         };
         /**
-         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @returns a new Color4 object
          */
         Color4.Lerp = function (left, right, amount) {
             var result = new Color4(0.0, 0.0, 0.0, 0.0);
@@ -1549,7 +1725,11 @@ var BABYLON;
             return result;
         };
         /**
-         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @param result defines the Color4 object where to store data
          */
         Color4.LerpToRef = function (left, right, amount, result) {
             result.r = left.r + (right.r - left.r) * amount;
@@ -1558,18 +1738,33 @@ var BABYLON;
             result.a = left.a + (right.a - left.a) * amount;
         };
         /**
-         * Creates a new Color4 from the starting index element of the passed array.
+         * Creates a new Color4 from the starting index element of the passed array
+         * @param array defines the source array to read from
+         * @param offset defines the offset in the source array
+         * @returns a new Color4 object
          */
         Color4.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color4(array[offset], array[offset + 1], array[offset + 2], array[offset + 3]);
         };
         /**
-         * Creates a new Color4 from the passed integers ( < 256 ).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @param a defines the alpha component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color4.FromInts = function (r, g, b, a) {
             return new Color4(r / 255.0, g / 255.0, b / 255.0, a / 255.0);
         };
+        /**
+         * Check the content of a given array and convert it to an array containing RGBA data
+         * If the original array was already containing count * 4 values then it is returned directly
+         * @param colors defines the array to check
+         * @param count defines the number of RGBA data to expect
+         * @returns an array containing count * 4 values (RGBA)
+         */
         Color4.CheckColors4 = function (colors, count) {
             // Check if color3 was used
             if (colors.length === count * 3) {
@@ -4161,7 +4356,7 @@ var BABYLON;
          * - a scale vector3 passed as a reference to update,
          * - a rotation quaternion passed as a reference to update,
          * - a translation vector3 passed as a reference to update.
-         * Returns the boolean `true`.
+         * Returns the true if operation was successful.
          */
         Matrix.prototype.decompose = function (scale, rotation, translation) {
             translation.x = this.m[12];
@@ -6518,14 +6713,15 @@ var BABYLON;
             state.target = target;
             state.currentTarget = currentTarget;
             state.skipNextObservers = false;
+            state.lastReturnValue = eventData;
             for (var _i = 0, _a = this._observers; _i < _a.length; _i++) {
                 var obs = _a[_i];
                 if (obs.mask & mask) {
                     if (obs.scope) {
-                        obs.callback.apply(obs.scope, [eventData, state]);
+                        state.lastReturnValue = obs.callback.apply(obs.scope, [eventData, state]);
                     }
                     else {
-                        obs.callback(eventData, state);
+                        state.lastReturnValue = obs.callback(eventData, state);
                     }
                 }
                 if (state.skipNextObservers) {
@@ -6535,6 +6731,55 @@ var BABYLON;
             return true;
         };
         /**
+         * Calling this will execute each callback, expecting it to be a promise or return a value.
+         * If at any point in the chain one function fails, the promise will fail and the execution will not continue.
+         * This is useful when a chain of events (sometimes async events) is needed to initialize a certain object
+         * and it is crucial that all callbacks will be executed.
+         * The order of the callbacks is kept, callbacks are not executed parallel.
+         *
+         * @param eventData The data to be sent to each callback
+         * @param mask is used to filter observers defaults to -1
+         * @param target the callback target (see EventState)
+         * @param currentTarget The current object in the bubbling phase
+         * @returns {Promise<T>} will return a Promise than resolves when all callbacks executed successfully.
+         */
+        Observable.prototype.notifyObserversWithPromise = function (eventData, mask, target, currentTarget) {
+            if (mask === void 0) { mask = -1; }
+            // create an empty promise
+            var p = Promise.resolve(eventData);
+            // no observers? return this promise.
+            if (!this._observers.length) {
+                return p;
+            }
+            var state = this._eventState;
+            state.mask = mask;
+            state.target = target;
+            state.currentTarget = currentTarget;
+            state.skipNextObservers = false;
+            // execute one callback after another (not using Promise.all, the order is important)
+            this._observers.forEach(function (obs) {
+                if (state.skipNextObservers) {
+                    return;
+                }
+                if (obs.mask & mask) {
+                    if (obs.scope) {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback.apply(obs.scope, [eventData, state]);
+                        });
+                    }
+                    else {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback(eventData, state);
+                        });
+                    }
+                }
+            });
+            // return the eventData
+            return p.then(function () { return eventData; });
+        };
+        /**
          * Notify a specific observer
          * @param eventData
          * @param mask
@@ -48931,7 +49176,7 @@ var BABYLON;
 
 
 
-//# sourceMappingURL=babylon.IParticleEmitterType.js.map
+//# sourceMappingURL=babylon.iParticleEmitterType.js.map
 
 var BABYLON;
 (function (BABYLON) {

dist/preview release/customConfigurations/minimalGLTFViewer/babylon.max.js

@@ -1004,11 +1004,29 @@ var BABYLON;
     BABYLON.ToGammaSpace = 1 / 2.2;
     BABYLON.ToLinearSpace = 2.2;
     BABYLON.Epsilon = 0.001;
+    /**
+     * Class used to hold a RBG color
+     */
     var Color3 = /** @class */ (function () {
         /**
-         * Creates a new Color3 object from red, green, blue values, all between 0 and 1.
+         * Creates a new Color3 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
          */
-        function Color3(r, g, b) {
+        function Color3(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1017,19 +1035,22 @@ var BABYLON;
             this.b = b;
         }
         /**
-         * Returns a string with the Color3 current values.
+         * Creates a string with the Color3 current values
+         * @returns the string representation of the Color3 object
          */
         Color3.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + "}";
         };
         /**
-         * Returns the string "Color3".
+         * Returns the string "Color3"
+         * @returns "Color3"
          */
         Color3.prototype.getClassName = function () {
             return "Color3";
         };
         /**
-         * Returns the Color3 hash code.
+         * Compute the Color3 hash code
+         * @returns an unique number that can be used to hash Color3 objects
          */
         Color3.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1039,8 +1060,10 @@ var BABYLON;
         };
         // Operators
         /**
-         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements.
-         * Returns the Color3.
+         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color3 object
          */
         Color3.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1052,14 +1075,17 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 object from the current Color3 and the passed alpha.
+         * Returns a new {BABYLON.Color4} object from the current Color3 and the passed alpha
+         * @param alpha defines the alpha component on the new {BABYLON.Color4} object (default is 1)
+         * @returns a new {BABYLON.Color4} object
          */
         Color3.prototype.toColor4 = function (alpha) {
             if (alpha === void 0) { alpha = 1; }
             return new Color4(this.r, this.g, this.b, alpha);
         };
         /**
-         * Returns a new array populated with 3 numeric elements : red, green and blue values.
+         * Returns a new array populated with 3 numeric elements : red, green and blue values
+         * @returns the new array
          */
         Color3.prototype.asArray = function () {
             var result = new Array();
@@ -1067,21 +1093,25 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns the luminance value (float).
+         * Returns the luminance value
+         * @returns a float value
          */
         Color3.prototype.toLuminance = function () {
             return this.r * 0.3 + this.g * 0.59 + this.b * 0.11;
         };
         /**
-         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object.
-         * Returns this new object.
+         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object
+         * @param otherColor defines the second operand
+         * @returns the new Color3 object
          */
         Color3.prototype.multiply = function (otherColor) {
             return new Color3(this.r * otherColor.r, this.g * otherColor.g, this.b * otherColor.b);
         };
         /**
-         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result".
-         * Returns the current Color3.
+         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result"
+         * @param otherColor defines the second operand
+         * @param result defines the Color3 object where to store the result
+         * @returns the current Color3
          */
         Color3.prototype.multiplyToRef = function (otherColor, result) {
             result.r = this.r * otherColor.r;
@@ -1090,27 +1120,36 @@ var BABYLON;
             return this;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between Color3 objects
+         * @param otherColor defines the second operand
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equals = function (otherColor) {
             return otherColor && this.r === otherColor.r && this.g === otherColor.g && this.b === otherColor.b;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between the current Color3 object and a set of r,b,g values
+         * @param r defines the red component to check
+         * @param g defines the green component to check
+         * @param b defines the blue component to check
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equalsFloats = function (r, g, b) {
             return this.r === r && this.g === g && this.b === b;
         };
         /**
-         * Multiplies in place each rgb value by scale.
-         * Returns the updated Color3.
+         * Multiplies in place each rgb value by scale
+         * @param scale defines the scaling factor
+         * @returns the updated Color3.
          */
         Color3.prototype.scale = function (scale) {
             return new Color3(this.r * scale, this.g * scale, this.b * scale);
         };
         /**
-         * Multiplies the rgb values by scale and stores the result into "result".
-         * Returns the unmodified current Color3.
+         * Multiplies the rgb values by scale and stores the result into "result"
+         * @param scale defines the scaling factor
+         * @param result defines the Color3 object where to store the result
+         * @returns the unmodified current Color3.
          */
         Color3.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1119,12 +1158,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color3.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color3
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into
+         * @returns the original Color3
          */
         Color3.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1135,14 +1173,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the added values of the current Color3 and of the passed one.
+         * Creates a new Color3 set with the added values of the current Color3 and of the passed one
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.add = function (otherColor) {
             return new Color3(this.r + otherColor.r, this.g + otherColor.g, this.b + otherColor.b);
         };
         /**
-         * Stores the result of the addition of the current Color3 and passed one rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the addition of the current Color3 and passed one rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.addToRef = function (otherColor, result) {
             result.r = this.r + otherColor.r;
@@ -1151,14 +1193,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3 .
+         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.subtract = function (otherColor) {
             return new Color3(this.r - otherColor.r, this.g - otherColor.g, this.b - otherColor.b);
         };
         /**
-         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.subtractToRef = function (otherColor, result) {
             result.r = this.r - otherColor.r;
@@ -1167,14 +1213,16 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 copied the current one.
+         * Copy the current object
+         * @returns a new Color3 copied the current one
          */
         Color3.prototype.clone = function () {
             return new Color3(this.r, this.g, this.b);
         };
         /**
-         * Copies the rgb values from the source in the current Color3.
-         * Returns the updated Color3.
+         * Copies the rgb values from the source in the current Color3
+         * @param source defines the source Color3 object
+         * @returns the updated Color3 object
          */
         Color3.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1183,8 +1231,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.copyFromFloats = function (r, g, b) {
             this.r = r;
@@ -1193,14 +1244,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.set = function (r, g, b) {
             return this.copyFromFloats(r, g, b);
         };
         /**
-         * Returns the Color3 hexadecimal code as a string.
+         * Compute the Color3 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color3 object
          */
         Color3.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1209,7 +1264,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB);
         };
         /**
-         * Returns a new Color3 converted to linear space.
+         * Computes a new Color3 converted from the current one to linear space
+         * @returns a new Color3 object
          */
         Color3.prototype.toLinearSpace = function () {
             var convertedColor = new Color3();
@@ -1217,8 +1273,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the linear space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1227,7 +1284,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 converted to gamma space.
+         * Computes a new Color3 converted from the current one to gamma space
+         * @returns a new Color3 object
          */
         Color3.prototype.toGammaSpace = function () {
             var convertedColor = new Color3();
@@ -1235,8 +1293,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the gamma space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1246,7 +1305,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color3 from the string containing valid hexadecimal values.
+         * Creates a new Color3 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color3 object
          */
         Color3.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 7) {
@@ -1259,20 +1320,31 @@ var BABYLON;
             return Color3.FromInts(r, g, b);
         };
         /**
-         * Creates a new Vector3 from the startind index of the passed array.
+         * Creates a new Vector3 from the starting index of the passed array
+         * @param array defines the source array
+         * @param offset defines an offset in the source array
+         * @returns a new Color3 object
          */
         Color3.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color3(array[offset], array[offset + 1], array[offset + 2]);
         };
         /**
-         * Creates a new Color3 from integer values ( < 256).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color3.FromInts = function (r, g, b) {
             return new Color3(r / 255.0, g / 255.0, b / 255.0);
         };
         /**
-         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3.
+         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3
+         * @param start defines the start Color3 value
+         * @param end defines the end Color3 value
+         * @param amount defines the gradient value between start and end
+         * @returns a new Color3 object
          */
         Color3.Lerp = function (start, end, amount) {
             var r = start.r + ((end.r - start.r) * amount);
@@ -1280,25 +1352,92 @@ var BABYLON;
             var b = start.b + ((end.b - start.b) * amount);
             return new Color3(r, g, b);
         };
+        /**
+         * Returns a Color3 value containing a red color
+         * @returns a new Color3 object
+         */
         Color3.Red = function () { return new Color3(1, 0, 0); };
+        /**
+         * Returns a Color3 value containing a green color
+         * @returns a new Color3 object
+         */
         Color3.Green = function () { return new Color3(0, 1, 0); };
+        /**
+         * Returns a Color3 value containing a blue color
+         * @returns a new Color3 object
+         */
         Color3.Blue = function () { return new Color3(0, 0, 1); };
+        /**
+         * Returns a Color3 value containing a black color
+         * @returns a new Color3 object
+         */
         Color3.Black = function () { return new Color3(0, 0, 0); };
+        /**
+         * Returns a Color3 value containing a white color
+         * @returns a new Color3 object
+         */
         Color3.White = function () { return new Color3(1, 1, 1); };
+        /**
+         * Returns a Color3 value containing a purple color
+         * @returns a new Color3 object
+         */
         Color3.Purple = function () { return new Color3(0.5, 0, 0.5); };
+        /**
+         * Returns a Color3 value containing a magenta color
+         * @returns a new Color3 object
+         */
         Color3.Magenta = function () { return new Color3(1, 0, 1); };
+        /**
+         * Returns a Color3 value containing a yellow color
+         * @returns a new Color3 object
+         */
         Color3.Yellow = function () { return new Color3(1, 1, 0); };
+        /**
+         * Returns a Color3 value containing a gray color
+         * @returns a new Color3 object
+         */
         Color3.Gray = function () { return new Color3(0.5, 0.5, 0.5); };
+        /**
+         * Returns a Color3 value containing a teal color
+         * @returns a new Color3 object
+         */
         Color3.Teal = function () { return new Color3(0, 1.0, 1.0); };
+        /**
+         * Returns a Color3 value containing a random color
+         * @returns a new Color3 object
+         */
         Color3.Random = function () { return new Color3(Math.random(), Math.random(), Math.random()); };
         return Color3;
     }());
     BABYLON.Color3 = Color3;
+    /**
+     * Class used to hold a RBGA color
+     */
     var Color4 = /** @class */ (function () {
         /**
-         * Creates a new Color4 object from the passed float values ( < 1) : red, green, blue, alpha.
+         * Creates a new Color4 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
+         * @param a defines the alpha component (between 0 and 1, default is 1)
          */
-        function Color4(r, g, b, a) {
+        function Color4(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b, 
+            /**
+             * Defines the alpha component (between 0 and 1, default is 1)
+             */
+            a) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1310,8 +1449,9 @@ var BABYLON;
         }
         // Operators
         /**
-         * Adds in place the passed Color4 values to the current Color4.
-         * Returns the updated Color4.
+         * Adds in place the passed Color4 values to the current Color4 object
+         * @param right defines the second operand
+         * @returns the current updated Color4 object
          */
         Color4.prototype.addInPlace = function (right) {
             this.r += right.r;
@@ -1321,7 +1461,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new array populated with 4 numeric elements : red, green, blue, alpha values.
+         * Creates a new array populated with 4 numeric elements : red, green, blue, alpha values
+         * @returns the new array
          */
         Color4.prototype.asArray = function () {
             var result = new Array();
@@ -1329,8 +1470,10 @@ var BABYLON;
             return result;
         };
         /**
-         * Stores from the starting index in the passed array the Color4 successive values.
-         * Returns the Color4.
+         * Stores from the starting index in the passed array the Color4 successive values
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color4 object
          */
         Color4.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1343,20 +1486,26 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 set with the added values of the current Color4 and of the passed one.
+         * Creates a new Color4 set with the added values of the current Color4 and of the passed one
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.add = function (right) {
             return new Color4(this.r + right.r, this.g + right.g, this.b + right.b, this.a + right.a);
         };
         /**
-         * Returns a new Color4 set with the subtracted values of the passed one from the current Color4.
+         * Creates a new Color4 set with the subtracted values of the passed one from the current Color4
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.subtract = function (right) {
             return new Color4(this.r - right.r, this.g - right.g, this.b - right.b, this.a - right.a);
         };
         /**
-         * Subtracts the passed ones from the current Color4 values and stores the results in "result".
-         * Returns the Color4.
+         * Subtracts the passed ones from the current Color4 values and stores the results in "result"
+         * @param right defines the second operand
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4 object
          */
         Color4.prototype.subtractToRef = function (right, result) {
             result.r = this.r - right.r;
@@ -1366,14 +1515,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Creates a new Color4 with the current Color4 values multiplied by scale.
+         * Creates a new Color4 with the current Color4 values multiplied by scale
+         * @param scale defines the scaling factor to apply
+         * @returns a new Color4 object
          */
         Color4.prototype.scale = function (scale) {
             return new Color4(this.r * scale, this.g * scale, this.b * scale, this.a * scale);
         };
         /**
-         * Multiplies the current Color4 values by scale and stores the result in "result".
-         * Returns the Color4.
+         * Multiplies the current Color4 values by scale and stores the result in "result"
+         * @param scale defines the scaling factor to apply
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4.
          */
         Color4.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1383,12 +1536,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color4.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color4
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into.
+         * @returns the cuurent Color4
          */
         Color4.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1400,18 +1552,18 @@ var BABYLON;
             return this;
         };
         /**
-          * Multipy an RGBA Color4 value by another and return a new Color4 object
-          * @param color The Color4 (RGBA) value to multiply by
-          * @returns A new Color4.
+          * Multipy an Color4 value by another and return a new Color4 object
+          * @param color defines the Color4 value to multiply by
+          * @returns a new Color4 object
           */
         Color4.prototype.multiply = function (color) {
             return new Color4(this.r * color.r, this.g * color.g, this.b * color.b, this.a * color.a);
         };
         /**
-         * Multipy an RGBA Color4 value by another and push the result in a reference value
-         * @param color The Color4 (RGBA) value to multiply by
-         * @param result The Color4 (RGBA) to fill the result in
-         * @returns the result Color4.
+         * Multipy a Color4 value by another and push the result in a reference value
+         * @param color defines the Color4 value to multiply by
+         * @param result defines the Color4 to fill the result in
+         * @returns the result Color4
          */
         Color4.prototype.multiplyToRef = function (color, result) {
             result.r = this.r * color.r;
@@ -1421,19 +1573,22 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns a string with the Color4 values.
+         * Creates a string with the Color4 current values
+         * @returns the string representation of the Color4 object
          */
         Color4.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + " A:" + this.a + "}";
         };
         /**
          * Returns the string "Color4"
+         * @returns "Color4"
          */
         Color4.prototype.getClassName = function () {
             return "Color4";
         };
         /**
-         * Return the Color4 hash code as a number.
+         * Compute the Color4 hash code
+         * @returns an unique number that can be used to hash Color4 objects
          */
         Color4.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1443,14 +1598,16 @@ var BABYLON;
             return hash;
         };
         /**
-         * Creates a new Color4 copied from the current one.
+         * Creates a new Color4 copied from the current one
+         * @returns a new Color4 object
          */
         Color4.prototype.clone = function () {
             return new Color4(this.r, this.g, this.b, this.a);
         };
         /**
-         * Copies the passed Color4 values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed Color4 values into the current one
+         * @param source defines the source Color4 object
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1460,8 +1617,12 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFromFloats = function (r, g, b, a) {
             this.r = r;
@@ -1471,14 +1632,19 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.set = function (r, g, b, a) {
             return this.copyFromFloats(r, g, b, a);
         };
         /**
-         * Returns a string containing the hexadecimal Color4 code.
+         * Compute the Color4 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color4 object
          */
         Color4.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1488,7 +1654,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB) + BABYLON.Scalar.ToHex(intA);
         };
         /**
-         * Returns a new Color4 converted to linear space.
+         * Computes a new Color4 converted from the current one to linear space
+         * @returns a new Color4 object
          */
         Color4.prototype.toLinearSpace = function () {
             var convertedColor = new Color4();
@@ -1496,8 +1663,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the linear space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1507,7 +1675,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 converted to gamma space.
+         * Computes a new Color4 converted from the current one to gamma space
+         * @returns a new Color4 object
          */
         Color4.prototype.toGammaSpace = function () {
             var convertedColor = new Color4();
@@ -1515,8 +1684,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the gamma space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1527,7 +1697,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color4 from the valid hexadecimal value contained in the passed string.
+         * Creates a new Color4 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color4 object
          */
         Color4.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 9) {
@@ -1541,7 +1713,11 @@ var BABYLON;
             return Color4.FromInts(r, g, b, a);
         };
         /**
-         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @returns a new Color4 object
          */
         Color4.Lerp = function (left, right, amount) {
             var result = new Color4(0.0, 0.0, 0.0, 0.0);
@@ -1549,7 +1725,11 @@ var BABYLON;
             return result;
         };
         /**
-         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @param result defines the Color4 object where to store data
          */
         Color4.LerpToRef = function (left, right, amount, result) {
             result.r = left.r + (right.r - left.r) * amount;
@@ -1558,18 +1738,33 @@ var BABYLON;
             result.a = left.a + (right.a - left.a) * amount;
         };
         /**
-         * Creates a new Color4 from the starting index element of the passed array.
+         * Creates a new Color4 from the starting index element of the passed array
+         * @param array defines the source array to read from
+         * @param offset defines the offset in the source array
+         * @returns a new Color4 object
          */
         Color4.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color4(array[offset], array[offset + 1], array[offset + 2], array[offset + 3]);
         };
         /**
-         * Creates a new Color4 from the passed integers ( < 256 ).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @param a defines the alpha component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color4.FromInts = function (r, g, b, a) {
             return new Color4(r / 255.0, g / 255.0, b / 255.0, a / 255.0);
         };
+        /**
+         * Check the content of a given array and convert it to an array containing RGBA data
+         * If the original array was already containing count * 4 values then it is returned directly
+         * @param colors defines the array to check
+         * @param count defines the number of RGBA data to expect
+         * @returns an array containing count * 4 values (RGBA)
+         */
         Color4.CheckColors4 = function (colors, count) {
             // Check if color3 was used
             if (colors.length === count * 3) {
@@ -4161,7 +4356,7 @@ var BABYLON;
          * - a scale vector3 passed as a reference to update,
          * - a rotation quaternion passed as a reference to update,
          * - a translation vector3 passed as a reference to update.
-         * Returns the boolean `true`.
+         * Returns the true if operation was successful.
          */
         Matrix.prototype.decompose = function (scale, rotation, translation) {
             translation.x = this.m[12];
@@ -6518,14 +6713,15 @@ var BABYLON;
             state.target = target;
             state.currentTarget = currentTarget;
             state.skipNextObservers = false;
+            state.lastReturnValue = eventData;
             for (var _i = 0, _a = this._observers; _i < _a.length; _i++) {
                 var obs = _a[_i];
                 if (obs.mask & mask) {
                     if (obs.scope) {
-                        obs.callback.apply(obs.scope, [eventData, state]);
+                        state.lastReturnValue = obs.callback.apply(obs.scope, [eventData, state]);
                     }
                     else {
-                        obs.callback(eventData, state);
+                        state.lastReturnValue = obs.callback(eventData, state);
                     }
                 }
                 if (state.skipNextObservers) {
@@ -6535,6 +6731,55 @@ var BABYLON;
             return true;
         };
         /**
+         * Calling this will execute each callback, expecting it to be a promise or return a value.
+         * If at any point in the chain one function fails, the promise will fail and the execution will not continue.
+         * This is useful when a chain of events (sometimes async events) is needed to initialize a certain object
+         * and it is crucial that all callbacks will be executed.
+         * The order of the callbacks is kept, callbacks are not executed parallel.
+         *
+         * @param eventData The data to be sent to each callback
+         * @param mask is used to filter observers defaults to -1
+         * @param target the callback target (see EventState)
+         * @param currentTarget The current object in the bubbling phase
+         * @returns {Promise<T>} will return a Promise than resolves when all callbacks executed successfully.
+         */
+        Observable.prototype.notifyObserversWithPromise = function (eventData, mask, target, currentTarget) {
+            if (mask === void 0) { mask = -1; }
+            // create an empty promise
+            var p = Promise.resolve(eventData);
+            // no observers? return this promise.
+            if (!this._observers.length) {
+                return p;
+            }
+            var state = this._eventState;
+            state.mask = mask;
+            state.target = target;
+            state.currentTarget = currentTarget;
+            state.skipNextObservers = false;
+            // execute one callback after another (not using Promise.all, the order is important)
+            this._observers.forEach(function (obs) {
+                if (state.skipNextObservers) {
+                    return;
+                }
+                if (obs.mask & mask) {
+                    if (obs.scope) {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback.apply(obs.scope, [eventData, state]);
+                        });
+                    }
+                    else {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback(eventData, state);
+                        });
+                    }
+                }
+            });
+            // return the eventData
+            return p.then(function () { return eventData; });
+        };
+        /**
          * Notify a specific observer
          * @param eventData
          * @param mask
@@ -48931,7 +49176,7 @@ var BABYLON;
 
 
 
-//# sourceMappingURL=babylon.IParticleEmitterType.js.map
+//# sourceMappingURL=babylon.iParticleEmitterType.js.map
 
 var BABYLON;
 (function (BABYLON) {

dist/preview release/customConfigurations/minimalGLTFViewer/es6.js

@@ -990,11 +990,29 @@ var BABYLON;
     BABYLON.ToGammaSpace = 1 / 2.2;
     BABYLON.ToLinearSpace = 2.2;
     BABYLON.Epsilon = 0.001;
+    /**
+     * Class used to hold a RBG color
+     */
     var Color3 = /** @class */ (function () {
         /**
-         * Creates a new Color3 object from red, green, blue values, all between 0 and 1.
+         * Creates a new Color3 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
          */
-        function Color3(r, g, b) {
+        function Color3(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1003,19 +1021,22 @@ var BABYLON;
             this.b = b;
         }
         /**
-         * Returns a string with the Color3 current values.
+         * Creates a string with the Color3 current values
+         * @returns the string representation of the Color3 object
          */
         Color3.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + "}";
         };
         /**
-         * Returns the string "Color3".
+         * Returns the string "Color3"
+         * @returns "Color3"
          */
         Color3.prototype.getClassName = function () {
             return "Color3";
         };
         /**
-         * Returns the Color3 hash code.
+         * Compute the Color3 hash code
+         * @returns an unique number that can be used to hash Color3 objects
          */
         Color3.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1025,8 +1046,10 @@ var BABYLON;
         };
         // Operators
         /**
-         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements.
-         * Returns the Color3.
+         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color3 object
          */
         Color3.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1038,14 +1061,17 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 object from the current Color3 and the passed alpha.
+         * Returns a new {BABYLON.Color4} object from the current Color3 and the passed alpha
+         * @param alpha defines the alpha component on the new {BABYLON.Color4} object (default is 1)
+         * @returns a new {BABYLON.Color4} object
          */
         Color3.prototype.toColor4 = function (alpha) {
             if (alpha === void 0) { alpha = 1; }
             return new Color4(this.r, this.g, this.b, alpha);
         };
         /**
-         * Returns a new array populated with 3 numeric elements : red, green and blue values.
+         * Returns a new array populated with 3 numeric elements : red, green and blue values
+         * @returns the new array
          */
         Color3.prototype.asArray = function () {
             var result = new Array();
@@ -1053,21 +1079,25 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns the luminance value (float).
+         * Returns the luminance value
+         * @returns a float value
          */
         Color3.prototype.toLuminance = function () {
             return this.r * 0.3 + this.g * 0.59 + this.b * 0.11;
         };
         /**
-         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object.
-         * Returns this new object.
+         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object
+         * @param otherColor defines the second operand
+         * @returns the new Color3 object
          */
         Color3.prototype.multiply = function (otherColor) {
             return new Color3(this.r * otherColor.r, this.g * otherColor.g, this.b * otherColor.b);
         };
         /**
-         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result".
-         * Returns the current Color3.
+         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result"
+         * @param otherColor defines the second operand
+         * @param result defines the Color3 object where to store the result
+         * @returns the current Color3
          */
         Color3.prototype.multiplyToRef = function (otherColor, result) {
             result.r = this.r * otherColor.r;
@@ -1076,27 +1106,36 @@ var BABYLON;
             return this;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between Color3 objects
+         * @param otherColor defines the second operand
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equals = function (otherColor) {
             return otherColor && this.r === otherColor.r && this.g === otherColor.g && this.b === otherColor.b;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between the current Color3 object and a set of r,b,g values
+         * @param r defines the red component to check
+         * @param g defines the green component to check
+         * @param b defines the blue component to check
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equalsFloats = function (r, g, b) {
             return this.r === r && this.g === g && this.b === b;
         };
         /**
-         * Multiplies in place each rgb value by scale.
-         * Returns the updated Color3.
+         * Multiplies in place each rgb value by scale
+         * @param scale defines the scaling factor
+         * @returns the updated Color3.
          */
         Color3.prototype.scale = function (scale) {
             return new Color3(this.r * scale, this.g * scale, this.b * scale);
         };
         /**
-         * Multiplies the rgb values by scale and stores the result into "result".
-         * Returns the unmodified current Color3.
+         * Multiplies the rgb values by scale and stores the result into "result"
+         * @param scale defines the scaling factor
+         * @param result defines the Color3 object where to store the result
+         * @returns the unmodified current Color3.
          */
         Color3.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1105,12 +1144,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color3.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color3
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into
+         * @returns the original Color3
          */
         Color3.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1121,14 +1159,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the added values of the current Color3 and of the passed one.
+         * Creates a new Color3 set with the added values of the current Color3 and of the passed one
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.add = function (otherColor) {
             return new Color3(this.r + otherColor.r, this.g + otherColor.g, this.b + otherColor.b);
         };
         /**
-         * Stores the result of the addition of the current Color3 and passed one rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the addition of the current Color3 and passed one rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.addToRef = function (otherColor, result) {
             result.r = this.r + otherColor.r;
@@ -1137,14 +1179,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3 .
+         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.subtract = function (otherColor) {
             return new Color3(this.r - otherColor.r, this.g - otherColor.g, this.b - otherColor.b);
         };
         /**
-         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.subtractToRef = function (otherColor, result) {
             result.r = this.r - otherColor.r;
@@ -1153,14 +1199,16 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 copied the current one.
+         * Copy the current object
+         * @returns a new Color3 copied the current one
          */
         Color3.prototype.clone = function () {
             return new Color3(this.r, this.g, this.b);
         };
         /**
-         * Copies the rgb values from the source in the current Color3.
-         * Returns the updated Color3.
+         * Copies the rgb values from the source in the current Color3
+         * @param source defines the source Color3 object
+         * @returns the updated Color3 object
          */
         Color3.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1169,8 +1217,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.copyFromFloats = function (r, g, b) {
             this.r = r;
@@ -1179,14 +1230,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.set = function (r, g, b) {
             return this.copyFromFloats(r, g, b);
         };
         /**
-         * Returns the Color3 hexadecimal code as a string.
+         * Compute the Color3 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color3 object
          */
         Color3.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1195,7 +1250,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB);
         };
         /**
-         * Returns a new Color3 converted to linear space.
+         * Computes a new Color3 converted from the current one to linear space
+         * @returns a new Color3 object
          */
         Color3.prototype.toLinearSpace = function () {
             var convertedColor = new Color3();
@@ -1203,8 +1259,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the linear space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1213,7 +1270,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 converted to gamma space.
+         * Computes a new Color3 converted from the current one to gamma space
+         * @returns a new Color3 object
          */
         Color3.prototype.toGammaSpace = function () {
             var convertedColor = new Color3();
@@ -1221,8 +1279,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the gamma space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1232,7 +1291,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color3 from the string containing valid hexadecimal values.
+         * Creates a new Color3 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color3 object
          */
         Color3.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 7) {
@@ -1245,20 +1306,31 @@ var BABYLON;
             return Color3.FromInts(r, g, b);
         };
         /**
-         * Creates a new Vector3 from the startind index of the passed array.
+         * Creates a new Vector3 from the starting index of the passed array
+         * @param array defines the source array
+         * @param offset defines an offset in the source array
+         * @returns a new Color3 object
          */
         Color3.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color3(array[offset], array[offset + 1], array[offset + 2]);
         };
         /**
-         * Creates a new Color3 from integer values ( < 256).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color3.FromInts = function (r, g, b) {
             return new Color3(r / 255.0, g / 255.0, b / 255.0);
         };
         /**
-         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3.
+         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3
+         * @param start defines the start Color3 value
+         * @param end defines the end Color3 value
+         * @param amount defines the gradient value between start and end
+         * @returns a new Color3 object
          */
         Color3.Lerp = function (start, end, amount) {
             var r = start.r + ((end.r - start.r) * amount);
@@ -1266,25 +1338,92 @@ var BABYLON;
             var b = start.b + ((end.b - start.b) * amount);
             return new Color3(r, g, b);
         };
+        /**
+         * Returns a Color3 value containing a red color
+         * @returns a new Color3 object
+         */
         Color3.Red = function () { return new Color3(1, 0, 0); };
+        /**
+         * Returns a Color3 value containing a green color
+         * @returns a new Color3 object
+         */
         Color3.Green = function () { return new Color3(0, 1, 0); };
+        /**
+         * Returns a Color3 value containing a blue color
+         * @returns a new Color3 object
+         */
         Color3.Blue = function () { return new Color3(0, 0, 1); };
+        /**
+         * Returns a Color3 value containing a black color
+         * @returns a new Color3 object
+         */
         Color3.Black = function () { return new Color3(0, 0, 0); };
+        /**
+         * Returns a Color3 value containing a white color
+         * @returns a new Color3 object
+         */
         Color3.White = function () { return new Color3(1, 1, 1); };
+        /**
+         * Returns a Color3 value containing a purple color
+         * @returns a new Color3 object
+         */
         Color3.Purple = function () { return new Color3(0.5, 0, 0.5); };
+        /**
+         * Returns a Color3 value containing a magenta color
+         * @returns a new Color3 object
+         */
         Color3.Magenta = function () { return new Color3(1, 0, 1); };
+        /**
+         * Returns a Color3 value containing a yellow color
+         * @returns a new Color3 object
+         */
         Color3.Yellow = function () { return new Color3(1, 1, 0); };
+        /**
+         * Returns a Color3 value containing a gray color
+         * @returns a new Color3 object
+         */
         Color3.Gray = function () { return new Color3(0.5, 0.5, 0.5); };
+        /**
+         * Returns a Color3 value containing a teal color
+         * @returns a new Color3 object
+         */
         Color3.Teal = function () { return new Color3(0, 1.0, 1.0); };
+        /**
+         * Returns a Color3 value containing a random color
+         * @returns a new Color3 object
+         */
         Color3.Random = function () { return new Color3(Math.random(), Math.random(), Math.random()); };
         return Color3;
     }());
     BABYLON.Color3 = Color3;
+    /**
+     * Class used to hold a RBGA color
+     */
     var Color4 = /** @class */ (function () {
         /**
-         * Creates a new Color4 object from the passed float values ( < 1) : red, green, blue, alpha.
+         * Creates a new Color4 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
+         * @param a defines the alpha component (between 0 and 1, default is 1)
          */
-        function Color4(r, g, b, a) {
+        function Color4(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b, 
+            /**
+             * Defines the alpha component (between 0 and 1, default is 1)
+             */
+            a) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1296,8 +1435,9 @@ var BABYLON;
         }
         // Operators
         /**
-         * Adds in place the passed Color4 values to the current Color4.
-         * Returns the updated Color4.
+         * Adds in place the passed Color4 values to the current Color4 object
+         * @param right defines the second operand
+         * @returns the current updated Color4 object
          */
         Color4.prototype.addInPlace = function (right) {
             this.r += right.r;
@@ -1307,7 +1447,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new array populated with 4 numeric elements : red, green, blue, alpha values.
+         * Creates a new array populated with 4 numeric elements : red, green, blue, alpha values
+         * @returns the new array
          */
         Color4.prototype.asArray = function () {
             var result = new Array();
@@ -1315,8 +1456,10 @@ var BABYLON;
             return result;
         };
         /**
-         * Stores from the starting index in the passed array the Color4 successive values.
-         * Returns the Color4.
+         * Stores from the starting index in the passed array the Color4 successive values
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color4 object
          */
         Color4.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1329,20 +1472,26 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 set with the added values of the current Color4 and of the passed one.
+         * Creates a new Color4 set with the added values of the current Color4 and of the passed one
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.add = function (right) {
             return new Color4(this.r + right.r, this.g + right.g, this.b + right.b, this.a + right.a);
         };
         /**
-         * Returns a new Color4 set with the subtracted values of the passed one from the current Color4.
+         * Creates a new Color4 set with the subtracted values of the passed one from the current Color4
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.subtract = function (right) {
             return new Color4(this.r - right.r, this.g - right.g, this.b - right.b, this.a - right.a);
         };
         /**
-         * Subtracts the passed ones from the current Color4 values and stores the results in "result".
-         * Returns the Color4.
+         * Subtracts the passed ones from the current Color4 values and stores the results in "result"
+         * @param right defines the second operand
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4 object
          */
         Color4.prototype.subtractToRef = function (right, result) {
             result.r = this.r - right.r;
@@ -1352,14 +1501,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Creates a new Color4 with the current Color4 values multiplied by scale.
+         * Creates a new Color4 with the current Color4 values multiplied by scale
+         * @param scale defines the scaling factor to apply
+         * @returns a new Color4 object
          */
         Color4.prototype.scale = function (scale) {
             return new Color4(this.r * scale, this.g * scale, this.b * scale, this.a * scale);
         };
         /**
-         * Multiplies the current Color4 values by scale and stores the result in "result".
-         * Returns the Color4.
+         * Multiplies the current Color4 values by scale and stores the result in "result"
+         * @param scale defines the scaling factor to apply
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4.
          */
         Color4.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1369,12 +1522,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color4.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color4
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into.
+         * @returns the cuurent Color4
          */
         Color4.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1386,18 +1538,18 @@ var BABYLON;
             return this;
         };
         /**
-          * Multipy an RGBA Color4 value by another and return a new Color4 object
-          * @param color The Color4 (RGBA) value to multiply by
-          * @returns A new Color4.
+          * Multipy an Color4 value by another and return a new Color4 object
+          * @param color defines the Color4 value to multiply by
+          * @returns a new Color4 object
           */
         Color4.prototype.multiply = function (color) {
             return new Color4(this.r * color.r, this.g * color.g, this.b * color.b, this.a * color.a);
         };
         /**
-         * Multipy an RGBA Color4 value by another and push the result in a reference value
-         * @param color The Color4 (RGBA) value to multiply by
-         * @param result The Color4 (RGBA) to fill the result in
-         * @returns the result Color4.
+         * Multipy a Color4 value by another and push the result in a reference value
+         * @param color defines the Color4 value to multiply by
+         * @param result defines the Color4 to fill the result in
+         * @returns the result Color4
          */
         Color4.prototype.multiplyToRef = function (color, result) {
             result.r = this.r * color.r;
@@ -1407,19 +1559,22 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns a string with the Color4 values.
+         * Creates a string with the Color4 current values
+         * @returns the string representation of the Color4 object
          */
         Color4.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + " A:" + this.a + "}";
         };
         /**
          * Returns the string "Color4"
+         * @returns "Color4"
          */
         Color4.prototype.getClassName = function () {
             return "Color4";
         };
         /**
-         * Return the Color4 hash code as a number.
+         * Compute the Color4 hash code
+         * @returns an unique number that can be used to hash Color4 objects
          */
         Color4.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1429,14 +1584,16 @@ var BABYLON;
             return hash;
         };
         /**
-         * Creates a new Color4 copied from the current one.
+         * Creates a new Color4 copied from the current one
+         * @returns a new Color4 object
          */
         Color4.prototype.clone = function () {
             return new Color4(this.r, this.g, this.b, this.a);
         };
         /**
-         * Copies the passed Color4 values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed Color4 values into the current one
+         * @param source defines the source Color4 object
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1446,8 +1603,12 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFromFloats = function (r, g, b, a) {
             this.r = r;
@@ -1457,14 +1618,19 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.set = function (r, g, b, a) {
             return this.copyFromFloats(r, g, b, a);
         };
         /**
-         * Returns a string containing the hexadecimal Color4 code.
+         * Compute the Color4 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color4 object
          */
         Color4.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1474,7 +1640,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB) + BABYLON.Scalar.ToHex(intA);
         };
         /**
-         * Returns a new Color4 converted to linear space.
+         * Computes a new Color4 converted from the current one to linear space
+         * @returns a new Color4 object
          */
         Color4.prototype.toLinearSpace = function () {
             var convertedColor = new Color4();
@@ -1482,8 +1649,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the linear space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1493,7 +1661,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 converted to gamma space.
+         * Computes a new Color4 converted from the current one to gamma space
+         * @returns a new Color4 object
          */
         Color4.prototype.toGammaSpace = function () {
             var convertedColor = new Color4();
@@ -1501,8 +1670,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the gamma space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1513,7 +1683,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color4 from the valid hexadecimal value contained in the passed string.
+         * Creates a new Color4 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color4 object
          */
         Color4.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 9) {
@@ -1527,7 +1699,11 @@ var BABYLON;
             return Color4.FromInts(r, g, b, a);
         };
         /**
-         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @returns a new Color4 object
          */
         Color4.Lerp = function (left, right, amount) {
             var result = new Color4(0.0, 0.0, 0.0, 0.0);
@@ -1535,7 +1711,11 @@ var BABYLON;
             return result;
         };
         /**
-         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @param result defines the Color4 object where to store data
          */
         Color4.LerpToRef = function (left, right, amount, result) {
             result.r = left.r + (right.r - left.r) * amount;
@@ -1544,18 +1724,33 @@ var BABYLON;
             result.a = left.a + (right.a - left.a) * amount;
         };
         /**
-         * Creates a new Color4 from the starting index element of the passed array.
+         * Creates a new Color4 from the starting index element of the passed array
+         * @param array defines the source array to read from
+         * @param offset defines the offset in the source array
+         * @returns a new Color4 object
          */
         Color4.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color4(array[offset], array[offset + 1], array[offset + 2], array[offset + 3]);
         };
         /**
-         * Creates a new Color4 from the passed integers ( < 256 ).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @param a defines the alpha component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color4.FromInts = function (r, g, b, a) {
             return new Color4(r / 255.0, g / 255.0, b / 255.0, a / 255.0);
         };
+        /**
+         * Check the content of a given array and convert it to an array containing RGBA data
+         * If the original array was already containing count * 4 values then it is returned directly
+         * @param colors defines the array to check
+         * @param count defines the number of RGBA data to expect
+         * @returns an array containing count * 4 values (RGBA)
+         */
         Color4.CheckColors4 = function (colors, count) {
             // Check if color3 was used
             if (colors.length === count * 3) {
@@ -4147,7 +4342,7 @@ var BABYLON;
          * - a scale vector3 passed as a reference to update,
          * - a rotation quaternion passed as a reference to update,
          * - a translation vector3 passed as a reference to update.
-         * Returns the boolean `true`.
+         * Returns the true if operation was successful.
          */
         Matrix.prototype.decompose = function (scale, rotation, translation) {
             translation.x = this.m[12];
@@ -6504,14 +6699,15 @@ var BABYLON;
             state.target = target;
             state.currentTarget = currentTarget;
             state.skipNextObservers = false;
+            state.lastReturnValue = eventData;
             for (var _i = 0, _a = this._observers; _i < _a.length; _i++) {
                 var obs = _a[_i];
                 if (obs.mask & mask) {
                     if (obs.scope) {
-                        obs.callback.apply(obs.scope, [eventData, state]);
+                        state.lastReturnValue = obs.callback.apply(obs.scope, [eventData, state]);
                     }
                     else {
-                        obs.callback(eventData, state);
+                        state.lastReturnValue = obs.callback(eventData, state);
                     }
                 }
                 if (state.skipNextObservers) {
@@ -6521,6 +6717,55 @@ var BABYLON;
             return true;
         };
         /**
+         * Calling this will execute each callback, expecting it to be a promise or return a value.
+         * If at any point in the chain one function fails, the promise will fail and the execution will not continue.
+         * This is useful when a chain of events (sometimes async events) is needed to initialize a certain object
+         * and it is crucial that all callbacks will be executed.
+         * The order of the callbacks is kept, callbacks are not executed parallel.
+         *
+         * @param eventData The data to be sent to each callback
+         * @param mask is used to filter observers defaults to -1
+         * @param target the callback target (see EventState)
+         * @param currentTarget The current object in the bubbling phase
+         * @returns {Promise<T>} will return a Promise than resolves when all callbacks executed successfully.
+         */
+        Observable.prototype.notifyObserversWithPromise = function (eventData, mask, target, currentTarget) {
+            if (mask === void 0) { mask = -1; }
+            // create an empty promise
+            var p = Promise.resolve(eventData);
+            // no observers? return this promise.
+            if (!this._observers.length) {
+                return p;
+            }
+            var state = this._eventState;
+            state.mask = mask;
+            state.target = target;
+            state.currentTarget = currentTarget;
+            state.skipNextObservers = false;
+            // execute one callback after another (not using Promise.all, the order is important)
+            this._observers.forEach(function (obs) {
+                if (state.skipNextObservers) {
+                    return;
+                }
+                if (obs.mask & mask) {
+                    if (obs.scope) {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback.apply(obs.scope, [eventData, state]);
+                        });
+                    }
+                    else {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback(eventData, state);
+                        });
+                    }
+                }
+            });
+            // return the eventData
+            return p.then(function () { return eventData; });
+        };
+        /**
          * Notify a specific observer
          * @param eventData
          * @param mask
@@ -48917,7 +49162,7 @@ var BABYLON;
 
 
 
-//# sourceMappingURL=babylon.IParticleEmitterType.js.map
+//# sourceMappingURL=babylon.iParticleEmitterType.js.map
 
 var BABYLON;
 (function (BABYLON) {

dist/preview release/es6.js

@@ -990,11 +990,29 @@ var BABYLON;
     BABYLON.ToGammaSpace = 1 / 2.2;
     BABYLON.ToLinearSpace = 2.2;
     BABYLON.Epsilon = 0.001;
+    /**
+     * Class used to hold a RBG color
+     */
     var Color3 = /** @class */ (function () {
         /**
-         * Creates a new Color3 object from red, green, blue values, all between 0 and 1.
+         * Creates a new Color3 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
          */
-        function Color3(r, g, b) {
+        function Color3(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1003,19 +1021,22 @@ var BABYLON;
             this.b = b;
         }
         /**
-         * Returns a string with the Color3 current values.
+         * Creates a string with the Color3 current values
+         * @returns the string representation of the Color3 object
          */
         Color3.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + "}";
         };
         /**
-         * Returns the string "Color3".
+         * Returns the string "Color3"
+         * @returns "Color3"
          */
         Color3.prototype.getClassName = function () {
             return "Color3";
         };
         /**
-         * Returns the Color3 hash code.
+         * Compute the Color3 hash code
+         * @returns an unique number that can be used to hash Color3 objects
          */
         Color3.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1025,8 +1046,10 @@ var BABYLON;
         };
         // Operators
         /**
-         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements.
-         * Returns the Color3.
+         * Stores in the passed array from the passed starting index the red, green, blue values as successive elements
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color3 object
          */
         Color3.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1038,14 +1061,17 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 object from the current Color3 and the passed alpha.
+         * Returns a new {BABYLON.Color4} object from the current Color3 and the passed alpha
+         * @param alpha defines the alpha component on the new {BABYLON.Color4} object (default is 1)
+         * @returns a new {BABYLON.Color4} object
          */
         Color3.prototype.toColor4 = function (alpha) {
             if (alpha === void 0) { alpha = 1; }
             return new Color4(this.r, this.g, this.b, alpha);
         };
         /**
-         * Returns a new array populated with 3 numeric elements : red, green and blue values.
+         * Returns a new array populated with 3 numeric elements : red, green and blue values
+         * @returns the new array
          */
         Color3.prototype.asArray = function () {
             var result = new Array();
@@ -1053,21 +1079,25 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns the luminance value (float).
+         * Returns the luminance value
+         * @returns a float value
          */
         Color3.prototype.toLuminance = function () {
             return this.r * 0.3 + this.g * 0.59 + this.b * 0.11;
         };
         /**
-         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object.
-         * Returns this new object.
+         * Multiply each Color3 rgb values by the passed Color3 rgb values in a new Color3 object
+         * @param otherColor defines the second operand
+         * @returns the new Color3 object
          */
         Color3.prototype.multiply = function (otherColor) {
             return new Color3(this.r * otherColor.r, this.g * otherColor.g, this.b * otherColor.b);
         };
         /**
-         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result".
-         * Returns the current Color3.
+         * Multiply the rgb values of the Color3 and the passed Color3 and stores the result in the object "result"
+         * @param otherColor defines the second operand
+         * @param result defines the Color3 object where to store the result
+         * @returns the current Color3
          */
         Color3.prototype.multiplyToRef = function (otherColor, result) {
             result.r = this.r * otherColor.r;
@@ -1076,27 +1106,36 @@ var BABYLON;
             return this;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between Color3 objects
+         * @param otherColor defines the second operand
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equals = function (otherColor) {
             return otherColor && this.r === otherColor.r && this.g === otherColor.g && this.b === otherColor.b;
         };
         /**
-         * Boolean : True if the rgb values are equal to the passed ones.
+         * Determines equality between the current Color3 object and a set of r,b,g values
+         * @param r defines the red component to check
+         * @param g defines the green component to check
+         * @param b defines the blue component to check
+         * @returns true if the rgb values are equal to the passed ones
          */
         Color3.prototype.equalsFloats = function (r, g, b) {
             return this.r === r && this.g === g && this.b === b;
         };
         /**
-         * Multiplies in place each rgb value by scale.
-         * Returns the updated Color3.
+         * Multiplies in place each rgb value by scale
+         * @param scale defines the scaling factor
+         * @returns the updated Color3.
          */
         Color3.prototype.scale = function (scale) {
             return new Color3(this.r * scale, this.g * scale, this.b * scale);
         };
         /**
-         * Multiplies the rgb values by scale and stores the result into "result".
-         * Returns the unmodified current Color3.
+         * Multiplies the rgb values by scale and stores the result into "result"
+         * @param scale defines the scaling factor
+         * @param result defines the Color3 object where to store the result
+         * @returns the unmodified current Color3.
          */
         Color3.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1105,12 +1144,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color3.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color3
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into
+         * @returns the original Color3
          */
         Color3.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1121,14 +1159,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the added values of the current Color3 and of the passed one.
+         * Creates a new Color3 set with the added values of the current Color3 and of the passed one
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.add = function (otherColor) {
             return new Color3(this.r + otherColor.r, this.g + otherColor.g, this.b + otherColor.b);
         };
         /**
-         * Stores the result of the addition of the current Color3 and passed one rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the addition of the current Color3 and passed one rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.addToRef = function (otherColor, result) {
             result.r = this.r + otherColor.r;
@@ -1137,14 +1179,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3 .
+         * Returns a new Color3 set with the subtracted values of the passed one from the current Color3
+         * @param otherColor defines the second operand
+         * @returns the new Color3
          */
         Color3.prototype.subtract = function (otherColor) {
             return new Color3(this.r - otherColor.r, this.g - otherColor.g, this.b - otherColor.b);
         };
         /**
-         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result".
-         * Returns the unmodified current Color3.
+         * Stores the result of the subtraction of passed one from the current Color3 rgb values into "result"
+         * @param otherColor defines the second operand
+         * @param result defines Color3 object to store the result into
+         * @returns the unmodified current Color3
          */
         Color3.prototype.subtractToRef = function (otherColor, result) {
             result.r = this.r - otherColor.r;
@@ -1153,14 +1199,16 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 copied the current one.
+         * Copy the current object
+         * @returns a new Color3 copied the current one
          */
         Color3.prototype.clone = function () {
             return new Color3(this.r, this.g, this.b);
         };
         /**
-         * Copies the rgb values from the source in the current Color3.
-         * Returns the updated Color3.
+         * Copies the rgb values from the source in the current Color3
+         * @param source defines the source Color3 object
+         * @returns the updated Color3 object
          */
         Color3.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1169,8 +1217,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.copyFromFloats = function (r, g, b) {
             this.r = r;
@@ -1179,14 +1230,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Updates the Color3 rgb values from the passed floats.
-         * Returns the Color3.
+         * Updates the Color3 rgb values from the passed floats
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @returns the current Color3 object
          */
         Color3.prototype.set = function (r, g, b) {
             return this.copyFromFloats(r, g, b);
         };
         /**
-         * Returns the Color3 hexadecimal code as a string.
+         * Compute the Color3 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color3 object
          */
         Color3.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1195,7 +1250,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB);
         };
         /**
-         * Returns a new Color3 converted to linear space.
+         * Computes a new Color3 converted from the current one to linear space
+         * @returns a new Color3 object
          */
         Color3.prototype.toLinearSpace = function () {
             var convertedColor = new Color3();
@@ -1203,8 +1259,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the linear space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1213,7 +1270,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color3 converted to gamma space.
+         * Computes a new Color3 converted from the current one to gamma space
+         * @returns a new Color3 object
          */
         Color3.prototype.toGammaSpace = function () {
             var convertedColor = new Color3();
@@ -1221,8 +1279,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color3 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color3.
+         * Converts the Color3 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color3 object where to store the gamma space version
+         * @returns the unmodified Color3
          */
         Color3.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1232,7 +1291,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color3 from the string containing valid hexadecimal values.
+         * Creates a new Color3 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color3 object
          */
         Color3.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 7) {
@@ -1245,20 +1306,31 @@ var BABYLON;
             return Color3.FromInts(r, g, b);
         };
         /**
-         * Creates a new Vector3 from the startind index of the passed array.
+         * Creates a new Vector3 from the starting index of the passed array
+         * @param array defines the source array
+         * @param offset defines an offset in the source array
+         * @returns a new Color3 object
          */
         Color3.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color3(array[offset], array[offset + 1], array[offset + 2]);
         };
         /**
-         * Creates a new Color3 from integer values ( < 256).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color3.FromInts = function (r, g, b) {
             return new Color3(r / 255.0, g / 255.0, b / 255.0);
         };
         /**
-         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3.
+         * Creates a new Color3 with values linearly interpolated of "amount" between the start Color3 and the end Color3
+         * @param start defines the start Color3 value
+         * @param end defines the end Color3 value
+         * @param amount defines the gradient value between start and end
+         * @returns a new Color3 object
          */
         Color3.Lerp = function (start, end, amount) {
             var r = start.r + ((end.r - start.r) * amount);
@@ -1266,25 +1338,92 @@ var BABYLON;
             var b = start.b + ((end.b - start.b) * amount);
             return new Color3(r, g, b);
         };
+        /**
+         * Returns a Color3 value containing a red color
+         * @returns a new Color3 object
+         */
         Color3.Red = function () { return new Color3(1, 0, 0); };
+        /**
+         * Returns a Color3 value containing a green color
+         * @returns a new Color3 object
+         */
         Color3.Green = function () { return new Color3(0, 1, 0); };
+        /**
+         * Returns a Color3 value containing a blue color
+         * @returns a new Color3 object
+         */
         Color3.Blue = function () { return new Color3(0, 0, 1); };
+        /**
+         * Returns a Color3 value containing a black color
+         * @returns a new Color3 object
+         */
         Color3.Black = function () { return new Color3(0, 0, 0); };
+        /**
+         * Returns a Color3 value containing a white color
+         * @returns a new Color3 object
+         */
         Color3.White = function () { return new Color3(1, 1, 1); };
+        /**
+         * Returns a Color3 value containing a purple color
+         * @returns a new Color3 object
+         */
         Color3.Purple = function () { return new Color3(0.5, 0, 0.5); };
+        /**
+         * Returns a Color3 value containing a magenta color
+         * @returns a new Color3 object
+         */
         Color3.Magenta = function () { return new Color3(1, 0, 1); };
+        /**
+         * Returns a Color3 value containing a yellow color
+         * @returns a new Color3 object
+         */
         Color3.Yellow = function () { return new Color3(1, 1, 0); };
+        /**
+         * Returns a Color3 value containing a gray color
+         * @returns a new Color3 object
+         */
         Color3.Gray = function () { return new Color3(0.5, 0.5, 0.5); };
+        /**
+         * Returns a Color3 value containing a teal color
+         * @returns a new Color3 object
+         */
         Color3.Teal = function () { return new Color3(0, 1.0, 1.0); };
+        /**
+         * Returns a Color3 value containing a random color
+         * @returns a new Color3 object
+         */
         Color3.Random = function () { return new Color3(Math.random(), Math.random(), Math.random()); };
         return Color3;
     }());
     BABYLON.Color3 = Color3;
+    /**
+     * Class used to hold a RBGA color
+     */
     var Color4 = /** @class */ (function () {
         /**
-         * Creates a new Color4 object from the passed float values ( < 1) : red, green, blue, alpha.
+         * Creates a new Color4 object from red, green, blue values, all between 0 and 1
+         * @param r defines the red component (between 0 and 1, default is 0)
+         * @param g defines the green component (between 0 and 1, default is 0)
+         * @param b defines the blue component (between 0 and 1, default is 0)
+         * @param a defines the alpha component (between 0 and 1, default is 1)
          */
-        function Color4(r, g, b, a) {
+        function Color4(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            r, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0)
+             */
+            g, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            b, 
+            /**
+             * Defines the alpha component (between 0 and 1, default is 1)
+             */
+            a) {
             if (r === void 0) { r = 0; }
             if (g === void 0) { g = 0; }
             if (b === void 0) { b = 0; }
@@ -1296,8 +1435,9 @@ var BABYLON;
         }
         // Operators
         /**
-         * Adds in place the passed Color4 values to the current Color4.
-         * Returns the updated Color4.
+         * Adds in place the passed Color4 values to the current Color4 object
+         * @param right defines the second operand
+         * @returns the current updated Color4 object
          */
         Color4.prototype.addInPlace = function (right) {
             this.r += right.r;
@@ -1307,7 +1447,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new array populated with 4 numeric elements : red, green, blue, alpha values.
+         * Creates a new array populated with 4 numeric elements : red, green, blue, alpha values
+         * @returns the new array
          */
         Color4.prototype.asArray = function () {
             var result = new Array();
@@ -1315,8 +1456,10 @@ var BABYLON;
             return result;
         };
         /**
-         * Stores from the starting index in the passed array the Color4 successive values.
-         * Returns the Color4.
+         * Stores from the starting index in the passed array the Color4 successive values
+         * @param array defines the array where to store the r,g,b components
+         * @param index defines an optional index in the target array to define where to start storing values
+         * @returns the current Color4 object
          */
         Color4.prototype.toArray = function (array, index) {
             if (index === undefined) {
@@ -1329,20 +1472,26 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 set with the added values of the current Color4 and of the passed one.
+         * Creates a new Color4 set with the added values of the current Color4 and of the passed one
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.add = function (right) {
             return new Color4(this.r + right.r, this.g + right.g, this.b + right.b, this.a + right.a);
         };
         /**
-         * Returns a new Color4 set with the subtracted values of the passed one from the current Color4.
+         * Creates a new Color4 set with the subtracted values of the passed one from the current Color4
+         * @param right defines the second operand
+         * @returns a new Color4 object
          */
         Color4.prototype.subtract = function (right) {
             return new Color4(this.r - right.r, this.g - right.g, this.b - right.b, this.a - right.a);
         };
         /**
-         * Subtracts the passed ones from the current Color4 values and stores the results in "result".
-         * Returns the Color4.
+         * Subtracts the passed ones from the current Color4 values and stores the results in "result"
+         * @param right defines the second operand
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4 object
          */
         Color4.prototype.subtractToRef = function (right, result) {
             result.r = this.r - right.r;
@@ -1352,14 +1501,18 @@ var BABYLON;
             return this;
         };
         /**
-         * Creates a new Color4 with the current Color4 values multiplied by scale.
+         * Creates a new Color4 with the current Color4 values multiplied by scale
+         * @param scale defines the scaling factor to apply
+         * @returns a new Color4 object
          */
         Color4.prototype.scale = function (scale) {
             return new Color4(this.r * scale, this.g * scale, this.b * scale, this.a * scale);
         };
         /**
-         * Multiplies the current Color4 values by scale and stores the result in "result".
-         * Returns the Color4.
+         * Multiplies the current Color4 values by scale and stores the result in "result"
+         * @param scale defines the scaling factor to apply
+         * @param result defines the Color4 object where to store the result
+         * @returns the current Color4.
          */
         Color4.prototype.scaleToRef = function (scale, result) {
             result.r = this.r * scale;
@@ -1369,12 +1522,11 @@ var BABYLON;
             return this;
         };
         /**
-         * Clamps the rgb values by the min and max values and stores the result into "result".
-         * Returns the unmodified current Color4.
-         * @param min - minimum clamping value.  Defaults to 0
-         * @param max - maximum clamping value.  Defaults to 1
-         * @param result - color to store the result into.
-         * @returns - the original Color4
+         * Clamps the rgb values by the min and max values and stores the result into "result"
+         * @param min defines minimum clamping value (default is 0)
+         * @param max defines maximum clamping value (default is 1)
+         * @param result defines color to store the result into.
+         * @returns the cuurent Color4
          */
         Color4.prototype.clampToRef = function (min, max, result) {
             if (min === void 0) { min = 0; }
@@ -1386,18 +1538,18 @@ var BABYLON;
             return this;
         };
         /**
-          * Multipy an RGBA Color4 value by another and return a new Color4 object
-          * @param color The Color4 (RGBA) value to multiply by
-          * @returns A new Color4.
+          * Multipy an Color4 value by another and return a new Color4 object
+          * @param color defines the Color4 value to multiply by
+          * @returns a new Color4 object
           */
         Color4.prototype.multiply = function (color) {
             return new Color4(this.r * color.r, this.g * color.g, this.b * color.b, this.a * color.a);
         };
         /**
-         * Multipy an RGBA Color4 value by another and push the result in a reference value
-         * @param color The Color4 (RGBA) value to multiply by
-         * @param result The Color4 (RGBA) to fill the result in
-         * @returns the result Color4.
+         * Multipy a Color4 value by another and push the result in a reference value
+         * @param color defines the Color4 value to multiply by
+         * @param result defines the Color4 to fill the result in
+         * @returns the result Color4
          */
         Color4.prototype.multiplyToRef = function (color, result) {
             result.r = this.r * color.r;
@@ -1407,19 +1559,22 @@ var BABYLON;
             return result;
         };
         /**
-         * Returns a string with the Color4 values.
+         * Creates a string with the Color4 current values
+         * @returns the string representation of the Color4 object
          */
         Color4.prototype.toString = function () {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + " A:" + this.a + "}";
         };
         /**
          * Returns the string "Color4"
+         * @returns "Color4"
          */
         Color4.prototype.getClassName = function () {
             return "Color4";
         };
         /**
-         * Return the Color4 hash code as a number.
+         * Compute the Color4 hash code
+         * @returns an unique number that can be used to hash Color4 objects
          */
         Color4.prototype.getHashCode = function () {
             var hash = this.r || 0;
@@ -1429,14 +1584,16 @@ var BABYLON;
             return hash;
         };
         /**
-         * Creates a new Color4 copied from the current one.
+         * Creates a new Color4 copied from the current one
+         * @returns a new Color4 object
          */
         Color4.prototype.clone = function () {
             return new Color4(this.r, this.g, this.b, this.a);
         };
         /**
-         * Copies the passed Color4 values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed Color4 values into the current one
+         * @param source defines the source Color4 object
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFrom = function (source) {
             this.r = source.r;
@@ -1446,8 +1603,12 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.copyFromFloats = function (r, g, b, a) {
             this.r = r;
@@ -1457,14 +1618,19 @@ var BABYLON;
             return this;
         };
         /**
-         * Copies the passed float values into the current one.
-         * Returns the updated Color4.
+         * Copies the passed float values into the current one
+         * @param r defines the red component to read from
+         * @param g defines the green component to read from
+         * @param b defines the blue component to read from
+         * @param a defines the alpha component to read from
+         * @returns the current updated Color4 object
          */
         Color4.prototype.set = function (r, g, b, a) {
             return this.copyFromFloats(r, g, b, a);
         };
         /**
-         * Returns a string containing the hexadecimal Color4 code.
+         * Compute the Color4 hexadecimal code as a string
+         * @returns a string containing the hexadecimal representation of the Color4 object
          */
         Color4.prototype.toHexString = function () {
             var intR = (this.r * 255) | 0;
@@ -1474,7 +1640,8 @@ var BABYLON;
             return "#" + BABYLON.Scalar.ToHex(intR) + BABYLON.Scalar.ToHex(intG) + BABYLON.Scalar.ToHex(intB) + BABYLON.Scalar.ToHex(intA);
         };
         /**
-         * Returns a new Color4 converted to linear space.
+         * Computes a new Color4 converted from the current one to linear space
+         * @returns a new Color4 object
          */
         Color4.prototype.toLinearSpace = function () {
             var convertedColor = new Color4();
@@ -1482,8 +1649,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to linear space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to linear space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the linear space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toLinearSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToLinearSpace);
@@ -1493,7 +1661,8 @@ var BABYLON;
             return this;
         };
         /**
-         * Returns a new Color4 converted to gamma space.
+         * Computes a new Color4 converted from the current one to gamma space
+         * @returns a new Color4 object
          */
         Color4.prototype.toGammaSpace = function () {
             var convertedColor = new Color4();
@@ -1501,8 +1670,9 @@ var BABYLON;
             return convertedColor;
         };
         /**
-         * Converts the Color4 values to gamma space and stores the result in "convertedColor".
-         * Returns the unmodified Color4.
+         * Converts the Color4 values to gamma space and stores the result in "convertedColor"
+         * @param convertedColor defines the Color4 object where to store the gamma space version
+         * @returns the unmodified Color4
          */
         Color4.prototype.toGammaSpaceToRef = function (convertedColor) {
             convertedColor.r = Math.pow(this.r, BABYLON.ToGammaSpace);
@@ -1513,7 +1683,9 @@ var BABYLON;
         };
         // Statics
         /**
-         * Creates a new Color4 from the valid hexadecimal value contained in the passed string.
+         * Creates a new Color4 from the string containing valid hexadecimal values
+         * @param hex defines a string containing valid hexadecimal values
+         * @returns a new Color4 object
          */
         Color4.FromHexString = function (hex) {
             if (hex.substring(0, 1) !== "#" || hex.length !== 9) {
@@ -1527,7 +1699,11 @@ var BABYLON;
             return Color4.FromInts(r, g, b, a);
         };
         /**
-         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Creates a new Color4 object set with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @returns a new Color4 object
          */
         Color4.Lerp = function (left, right, amount) {
             var result = new Color4(0.0, 0.0, 0.0, 0.0);
@@ -1535,7 +1711,11 @@ var BABYLON;
             return result;
         };
         /**
-         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 and the right Color4.
+         * Set the passed "result" with the linearly interpolated values of "amount" between the left Color4 object and the right Color4 object
+         * @param left defines the start value
+         * @param right defines the end value
+         * @param amount defines the gradient factor
+         * @param result defines the Color4 object where to store data
          */
         Color4.LerpToRef = function (left, right, amount, result) {
             result.r = left.r + (right.r - left.r) * amount;
@@ -1544,18 +1724,33 @@ var BABYLON;
             result.a = left.a + (right.a - left.a) * amount;
         };
         /**
-         * Creates a new Color4 from the starting index element of the passed array.
+         * Creates a new Color4 from the starting index element of the passed array
+         * @param array defines the source array to read from
+         * @param offset defines the offset in the source array
+         * @returns a new Color4 object
          */
         Color4.FromArray = function (array, offset) {
             if (offset === void 0) { offset = 0; }
             return new Color4(array[offset], array[offset + 1], array[offset + 2], array[offset + 3]);
         };
         /**
-         * Creates a new Color4 from the passed integers ( < 256 ).
+         * Creates a new Color3 from integer values (< 256)
+         * @param r defines the red component to read from (value between 0 and 255)
+         * @param g defines the green component to read from (value between 0 and 255)
+         * @param b defines the blue component to read from (value between 0 and 255)
+         * @param a defines the alpha component to read from (value between 0 and 255)
+         * @returns a new Color3 object
          */
         Color4.FromInts = function (r, g, b, a) {
             return new Color4(r / 255.0, g / 255.0, b / 255.0, a / 255.0);
         };
+        /**
+         * Check the content of a given array and convert it to an array containing RGBA data
+         * If the original array was already containing count * 4 values then it is returned directly
+         * @param colors defines the array to check
+         * @param count defines the number of RGBA data to expect
+         * @returns an array containing count * 4 values (RGBA)
+         */
         Color4.CheckColors4 = function (colors, count) {
             // Check if color3 was used
             if (colors.length === count * 3) {
@@ -4147,7 +4342,7 @@ var BABYLON;
          * - a scale vector3 passed as a reference to update,
          * - a rotation quaternion passed as a reference to update,
          * - a translation vector3 passed as a reference to update.
-         * Returns the boolean `true`.
+         * Returns the true if operation was successful.
          */
         Matrix.prototype.decompose = function (scale, rotation, translation) {
             translation.x = this.m[12];
@@ -6504,14 +6699,15 @@ var BABYLON;
             state.target = target;
             state.currentTarget = currentTarget;
             state.skipNextObservers = false;
+            state.lastReturnValue = eventData;
             for (var _i = 0, _a = this._observers; _i < _a.length; _i++) {
                 var obs = _a[_i];
                 if (obs.mask & mask) {
                     if (obs.scope) {
-                        obs.callback.apply(obs.scope, [eventData, state]);
+                        state.lastReturnValue = obs.callback.apply(obs.scope, [eventData, state]);
                     }
                     else {
-                        obs.callback(eventData, state);
+                        state.lastReturnValue = obs.callback(eventData, state);
                     }
                 }
                 if (state.skipNextObservers) {
@@ -6521,6 +6717,55 @@ var BABYLON;
             return true;
         };
         /**
+         * Calling this will execute each callback, expecting it to be a promise or return a value.
+         * If at any point in the chain one function fails, the promise will fail and the execution will not continue.
+         * This is useful when a chain of events (sometimes async events) is needed to initialize a certain object
+         * and it is crucial that all callbacks will be executed.
+         * The order of the callbacks is kept, callbacks are not executed parallel.
+         *
+         * @param eventData The data to be sent to each callback
+         * @param mask is used to filter observers defaults to -1
+         * @param target the callback target (see EventState)
+         * @param currentTarget The current object in the bubbling phase
+         * @returns {Promise<T>} will return a Promise than resolves when all callbacks executed successfully.
+         */
+        Observable.prototype.notifyObserversWithPromise = function (eventData, mask, target, currentTarget) {
+            if (mask === void 0) { mask = -1; }
+            // create an empty promise
+            var p = Promise.resolve(eventData);
+            // no observers? return this promise.
+            if (!this._observers.length) {
+                return p;
+            }
+            var state = this._eventState;
+            state.mask = mask;
+            state.target = target;
+            state.currentTarget = currentTarget;
+            state.skipNextObservers = false;
+            // execute one callback after another (not using Promise.all, the order is important)
+            this._observers.forEach(function (obs) {
+                if (state.skipNextObservers) {
+                    return;
+                }
+                if (obs.mask & mask) {
+                    if (obs.scope) {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback.apply(obs.scope, [eventData, state]);
+                        });
+                    }
+                    else {
+                        p = p.then(function (lastReturnedValue) {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback(eventData, state);
+                        });
+                    }
+                }
+            });
+            // return the eventData
+            return p.then(function () { return eventData; });
+        };
+        /**
          * Notify a specific observer
          * @param eventData
          * @param mask
@@ -48917,7 +49162,7 @@ var BABYLON;
 
 
 
-//# sourceMappingURL=babylon.IParticleEmitterType.js.map
+//# sourceMappingURL=babylon.iParticleEmitterType.js.map
 
 var BABYLON;
 (function (BABYLON) {

dist/preview release/typedocValidationBaseline.json

@@ -1,7 +1,7 @@
 {
-  "errors": 8780,
+  "errors": 8631,
   "babylon.typedoc.json": {
-    "errors": 8780,
+    "errors": 8631,
     "AnimationKeyInterpolation": {
       "Enumeration": {
         "Comments": {