Merge branch 'master' into gltf_khr_lights_support

Tools/Gulp/config.json

@@ -57,7 +57,11 @@
             "geometryBufferRenderer",
             "additionalPostProcesses",
             "additionalPostProcess_blur",
+            "additionalPostProcess_depthOfFieldBlur",
             "additionalPostProcess_fxaa",
+            "additionalPostProcess_circleOfConfusion",
+            "additionalPostProcess_depthOfFieldMerge",
+            "additionalPostProcess_depthOfFieldEffect",
             "additionalPostProcess_imageProcessing",
             "bones",
             "hdr",
@@ -722,6 +726,51 @@
                 "kernelBlurVertex"
             ]
         },
+        "additionalPostProcess_depthOfFieldBlur": {
+            "files": [
+                "../../src/PostProcess/babylon.depthOfFieldBlurPostProcess.js"
+            ],
+            "dependUpon": [
+                "postProcesses"
+            ],
+            "shaders": [
+                "kernelBlur.vertex",
+                "kernelBlur.fragment"
+            ],
+            "shaderIncludes": [
+                "kernelBlurFragment",
+                "kernelBlurFragment2",
+                "kernelBlurVaryingDeclaration",
+                "kernelBlurVertex"
+            ]
+        },
+        "additionalPostProcess_circleOfConfusion": {
+            "files": [
+                "../../src/PostProcess/babylon.circleOfConfusionPostProcess.js"
+            ],
+            "dependUpon": [
+                "postProcesses"
+            ],
+            "shaders": [
+                "circleOfConfusion.fragment"
+            ]
+        },
+        "additionalPostProcess_depthOfFieldMerge": {
+            "files": [
+                "../../src/PostProcess/babylon.depthOfFieldMergePostProcess.js"
+            ],
+            "dependUpon": [
+                "postProcesses"
+            ],
+            "shaders": [
+                "depthOfFieldMerge.fragment"
+            ]
+        },
+        "additionalPostProcess_depthOfFieldEffect": {
+            "files": [
+                "../../src/PostProcess/babylon.depthOfFieldEffect.js"
+            ]
+        },
         "additionalPostProcess_fxaa": {
             "files": [
                 "../../src/PostProcess/babylon.fxaaPostProcess.js"
@@ -827,7 +876,10 @@
             ],
             "dependUpon": [
                 "renderingPipeline",
-                "additionalPostProcess_fxaa"
+                "additionalPostProcess_fxaa",
+                "additionalPostProcess_circleOfConfusion",
+                "additionalPostProcess_depthOfFieldMerge",
+                "additionalPostProcess_depthOfFieldEffect"
             ]
         },
         "bones": {

dist/babylon.glTFInterface.d.ts

@@ -1,7 +1,12 @@
 declare module BABYLON.GLTF2 {
-    /**
-     * Specifies if the attribute is a scalar, vector, or matrix.
-     */
+    const enum AccessorComponentType {
+        BYTE = 5120,
+        UNSIGNED_BYTE = 5121,
+        SHORT = 5122,
+        UNSIGNED_SHORT = 5123,
+        UNSIGNED_INT = 5125,
+        FLOAT = 5126,
+    }
     const enum AccessorType {
         SCALAR = "SCALAR",
         VEC2 = "VEC2",
@@ -11,33 +16,29 @@ declare module BABYLON.GLTF2 {
         MAT3 = "MAT3",
         MAT4 = "MAT4",
     }
-    const enum MaterialAlphaMode {
-        OPAQUE = "OPAQUE",
-        MASK = "MASK",
-        BLEND = "BLEND",
-    }
     const enum AnimationChannelTargetPath {
         TRANSLATION = "translation",
         ROTATION = "rotation",
         SCALE = "scale",
         WEIGHTS = "weights",
     }
+    const enum AnimationInterpolation {
+        LINEAR = "LINEAR",
+        STEP = "STEP",
+        CUBICSPLINE = "CUBICSPLINE",
+    }
     const enum CameraType {
         PERSPECTIVE = "perspective",
         ORTHOGRAPHIC = "orthographic",
     }
-    const enum AccessorComponentType {
-        BYTE = 5120,
-        UNSIGNED_BYTE = 5121,
-        SHORT = 5122,
-        UNSIGNED_SHORT = 5123,
-        UNSIGNED_INT = 5125,
-        FLOAT = 5126,
+    const enum ImageMimeType {
+        JPEG = "image/jpeg",
+        PNG = "image/png",
     }
-    const enum AnimationInterpolation {
-        LINEAR = "LINEAR",
-        STEP = "STEP",
-        CUBICSPLINE = "CUBICSPLINE",
+    const enum MaterialAlphaMode {
+        OPAQUE = "OPAQUE",
+        MASK = "MASK",
+        BLEND = "BLEND",
     }
     const enum MeshPrimitiveMode {
         POINTS = 0,
@@ -48,10 +49,6 @@ declare module BABYLON.GLTF2 {
         TRIANGLE_STRIP = 5,
         TRIANGLE_FAN = 6,
     }
-    const enum ImageMimeType {
-        JPEG = "image/jpeg",
-        PNG = "image/png",
-    }
     const enum TextureMagFilter {
         NEAREST = 9728,
         LINEAR = 9729,

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": {
@@ -8192,843 +8192,6 @@
         }
       }
     },
-    "Color3": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "b": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "g": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "r": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "add": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "addToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "asArray": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "clone": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "copyFrom": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "source": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "copyFromFloats": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "equals": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "equalsFloats": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "getClassName": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "getHashCode": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "multiply": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "multiplyToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "scale": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "scale": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "scaleToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "scale": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "set": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "subtract": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "subtractToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "otherColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toArray": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "array": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "index": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toColor4": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "alpha": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toGammaSpace": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toGammaSpaceToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "convertedColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toHexString": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toLinearSpace": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toLinearSpaceToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "convertedColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toLuminance": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "ToString": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "Black": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Blue": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "FromArray": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "array": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "offset": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "FromHexString": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "hex": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "FromInts": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "Gray": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Green": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Lerp": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "start": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "end": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "amount": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "Magenta": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Purple": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Random": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Red": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Teal": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "White": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "Yellow": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
-    "Color4": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "a": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "b": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "g": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "r": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "add": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "addInPlace": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "asArray": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "clone": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "copyFrom": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "source": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "copyFromFloats": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "a": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "getClassName": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "getHashCode": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "scale": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "scale": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "scaleToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "scale": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "set": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "a": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "subtract": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "subtractToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toArray": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "array": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "index": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toGammaSpace": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toGammaSpaceToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "convertedColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "toHexString": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toLinearSpace": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "toLinearSpaceToRef": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "convertedColor": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "ToString": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "CheckColors4": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "colors": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "count": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "FromArray": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "array": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "offset": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "FromHexString": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "hex": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "FromInts": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "r": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "g": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "b": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "a": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "Lerp": {
-          "Comments": {
-            "MissingReturn": true
-          },
-          "Parameter": {
-            "left": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "amount": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "LerpToRef": {
-          "Parameter": {
-            "left": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "right": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "amount": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "result": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
     "ColorCorrectionPostProcess": {
       "Class": {
         "Comments": {

dist/preview release/what's new.md

@@ -7,6 +7,7 @@
 - `WebVRCamera` now supports GearVR ([brianzinn](https://github.com/brianzinn))
 - New glTF [serializer](https://github.com/BabylonJS/Babylon.js/tree/master/serializers/src/glTF/2.0). You can now export glTF or glb files directly from a Babylon scene ([kcoley](https://github.com/kcoley))
 - Babylon.js now uses Promises in addition to callbacks. We created several `xxxAsync` functions all over the framework (`SceneLoader.AppendAsync` for instance, which returns a Promise). A polyfill is also integrated to support older browsers ([deltakosh](https://github.com/deltakosh))
+- Introduced Projection Texture on SpotLight (`spotLight.projectedLightTexture`). ([lostink](https://github.com/lostink))
 
 ## Updates
 - Tons of functions and classes received the code comments they deserved (All the community)
@@ -33,11 +34,13 @@
    ([carloslanderas](https://github.com/carloslanderas))
 - (Viewer) initScene and initEngine can now be extended. onProgress during model loading is implemented as observable. ([RaananW](https://github.com/RaananW))
 - glTF loader now supports the KHR_lights extension ([MiiBond](https://github.com/MiiBond))
+- Added depth of field effect to default pipeline ([trevordev](https://github.com/trevordev))
 - The observable can now notify observers using promise-based callback chain. ([RaananW](https://github.com/RaananW))
+- Added base64 helper functions to `Tools` ([bghgary](https://github.com/bghgary))
+- Added `createDefaultCamera` and `createDefaultLight` functions to `Scene` ([bghgary](https://github.com/bghgary))
 
 ## Bug fixes
 - Texture extension detection in `Engine.CreateTexture` ([sebavan](https://github.com/sebavan))
+- Fixed a bug with merging vertex data ([bghgary](https://github.com/bghgary))
 
 ## Breaking changes
-
-

serializers/src/glTF/2.0/babylon.glTFData.ts

@@ -1,4 +1,4 @@
-/// <reference path="../../../../dist/babylon.glTFInterface.d.ts"/>
+/// <reference path="../../../../dist/babylon.glTF2Interface.d.ts"/>
 
 module BABYLON {
     /**

serializers/src/glTF/2.0/babylon.glTFExporter.ts

@@ -1,4 +1,4 @@
-/// <reference path="../../../../dist/babylon.glTFInterface.d.ts"/>
+/// <reference path="../../../../dist/babylon.glTF2Interface.d.ts"/>
 
 /**
  * Module for the Babylon glTF 2.0 exporter.  Should ONLY be used internally.

serializers/src/glTF/2.0/babylon.glTFMaterial.ts

@@ -1,4 +1,4 @@
-/// <reference path="../../../../dist/babylon.glTFInterface.d.ts"/>
+/// <reference path="../../../../dist/babylon.glTF2Interface.d.ts"/>
 
 module BABYLON.GLTF2 {
     /**

src/Lights/babylon.light.ts

@@ -1,4 +1,4 @@
-module BABYLON {
+module BABYLON {
     export class Light extends Node {
 
         //lightmapMode Consts
@@ -384,7 +384,59 @@
             }
             return b.renderPriority - a.renderPriority;
         }
+        // Projection texture, if needed
+        protected _computeTextureMatrix(): void{
+            //Leave out for different light type
+        }
+        protected _light_far  :number;
+        @serialize()
+        /**
+         * Allows reading the far clip of the Spotlight for texture projection.
+         */
+        public get light_far(): number {
+            return this._light_far;
+        }
+        /**
+         * Allows setting the far clip of the Spotlight for texture projection.
+         */
+        public set light_far(value: number) {
+            this._light_far = value;
+            this._computeTextureMatrix();
+        }
+
+        protected _light_near :number;
+        @serialize()
+        /**
+         * Allows reading the near clip of the Spotlight for texture projection.
+         */
+        public get light_near(): number {
+            return this._light_near;
+        }
+        /**
+         * Allows setting the near clip of the Spotlight for texture projection.
+         */
+        public set light_near(value: number) {
+            this._light_near = value;
+            this._computeTextureMatrix();
+        }
 
+        @serializeAsTexture("projectedLightTexture")
+        private _projectedLightTexture: Nullable<BaseTexture>;;
+        /** 
+         * Allows reading the projection texture of the light.
+        */
+        public get projectedLightTexture(): Nullable<BaseTexture> {
+            return this._projectedLightTexture;
+        }
+        /**
+        * Allows setting the projection texture of the light.
+        */
+        public set projectedLightTexture(value: Nullable<BaseTexture>) {
+            this._projectedLightTexture = value;
+            this._light_far = 1000.0;
+            this._light_near = 1e-6;
+            this._computeTextureMatrix();
+        }
         /**
          * Disposes the light.  
          */
@@ -397,8 +449,15 @@
             // Animations
             this.getScene().stopAnimation(this);
 
-            this._uniformBuffer.dispose();
+            // Remove from meshes
+            for (var mesh of this.getScene().meshes) {
+                mesh._removeLightSource(this);
+            }
 
+            this._uniformBuffer.dispose();
+            if (this._projectedLightTexture){
+                this._projectedLightTexture.dispose();
+            }
             // Remove from scene
             this.getScene().removeLight(this);
             super.dispose();
@@ -658,7 +717,6 @@
             }
             return photometricScale;
         }
-
         public _reorderLightsInScene(): void {
             var scene = this.getScene();
             if (this._renderPriority != 0) {
@@ -666,5 +724,8 @@
             }
             this.getScene().sortLightsByPriority();
         }
+
+
+
     }
 }

src/Lights/babylon.spotLight.ts

@@ -1,5 +1,55 @@
 module BABYLON {
     export class SpotLight extends ShadowLight {
+        /**
+            upVector , rightVector and direction will form the coordinate system for this spot light. 
+            These three vectors will be used as projection matrix when doing texture projection.
+            
+            Also we have the following rules always holds:
+            direction cross up   = right
+            right cross dirction = up
+            up cross right       = forward
+
+            light_near and light_far will control the range of the texture projection. If a plane is 
+            out of the range in spot light space, there is no texture projection.
+
+            Warning:
+            Change the angle of the Spotlight, direction of the SpotLight will not re-compute the 
+            projection matrix. Need to call computeTextureMatrix() to recompute manually. Add inheritance
+            to the setting function of the 2 attributes will solve the problem.
+        */
+        /**
+         * Main function for light texture projection matrix computing.
+         */
+        protected _computeTextureMatrix(): void{    
+
+            var viewLightMatrix = Matrix.Zero();
+            Matrix.LookAtLHToRef(this.position, this.position.add(this.direction), Vector3.Up(), viewLightMatrix);
+
+            var light_far = this.light_far;
+            var light_near = this.light_near;
+
+            var P = light_far / (light_far - light_near);
+            var Q = - P * light_near;
+            var S = 1.0 / Math.tan(this._angle / 2.0);
+            var A = 1.0;
+            
+            var projectionLightMatrix = Matrix.Zero();
+            Matrix.FromValuesToRef(S/A, 0.0, 0.0, 0.0,
+                0.0, S, 0.0, 0.0,
+                0.0, 0.0, P, 1.0,
+                0.0, 0.0, Q, 0.0, projectionLightMatrix);
+
+            var scaleMatrix = Matrix.Zero();
+            Matrix.FromValuesToRef(0.5, 0.0, 0.0, 0.0,
+                0.0, 0.5, 0.0, 0.0,
+                0.0, 0.0, 0.5, 0.0,
+                0.5, 0.5, 0.5, 1.0, scaleMatrix);
+                
+            this._textureProjectionMatrix.copyFrom(viewLightMatrix);
+            this._textureProjectionMatrix.multiplyToRef(projectionLightMatrix, this._textureProjectionMatrix);
+            this._textureProjectionMatrix.multiplyToRef(scaleMatrix, this._textureProjectionMatrix);
+        }
+
         private _angle: number;
         @serialize()
         public get angle(): number {
@@ -25,10 +75,24 @@
             this._shadowAngleScale = value;
             this.forceProjectionMatrixCompute();
         }
-
         @serialize()
         public exponent: number;
-        
+
+        private _textureProjectionMatrix = Matrix.Zero();
+        @serialize()
+        /**
+        * Allows reading the projecton texture
+        */
+        public get textureMatrix(): Matrix{
+            return this._textureProjectionMatrix;
+        }
+        /**
+        * Allows setting the value of projection texture
+        */
+        public set textureMatrix(value: Matrix) {
+            this._textureProjectionMatrix = value;
+        }
+
         /**
          * Creates a SpotLight object in the scene with the passed parameters :   
          * - `position` (Vector3) is the initial SpotLight position,  
@@ -123,6 +187,11 @@
                 normalizeDirection.z,
                 Math.cos(this.angle * 0.5),
                 lightIndex);
+
+            effect.setMatrix("textureProjectionMatrix" + lightIndex, this._textureProjectionMatrix);
+            if (this.projectedLightTexture){
+                effect.setTexture("projectionLightSampler" + lightIndex, this.projectedLightTexture);
+            }
             return this;
         }
     }

src/Materials/babylon.materialHelper.ts

@@ -1,4 +1,4 @@
-module BABYLON {
+module BABYLON {
     export class MaterialHelper {
 
         public static BindEyePosition(effect: Effect, scene: Scene): void {
@@ -207,6 +207,12 @@
                         defines["LIGHTMAPNOSPECULAR" + lightIndex] = false;
                     }
 
+                    //Projection texture
+                    if (light.projectedLightTexture){
+                        defines["PROJECTEDLIGHTTEXTURE" + lightIndex] = true;
+                    }else{
+                        defines["PROJECTEDLIGHTTEXTURE" + lightIndex] = false;                        
+                    }
                     lightIndex++;
                     if (lightIndex === maxSimultaneousLights)
                         break;
@@ -285,6 +291,12 @@
                 }
 
                 samplersList.push("shadowSampler" + lightIndex);
+                if (defines["PROJECTEDLIGHTTEXTURE" + lightIndex]){
+                    samplersList.push("projectionLightSampler" + lightIndex,);
+                    uniformsList.push(
+                        "textureProjectionMatrix" + lightIndex,
+                    );
+                }
             }
 
             if (defines["NUM_MORPH_INFLUENCERS"]) {

src/Math/babylon.math.ts

@@ -3,28 +3,51 @@
     export const ToLinearSpace = 2.2;
     export const Epsilon = 0.001;
 
+    /**
+     * Class used to hold a RBG color
+     */
     export class Color3 {
+
         /**
-         * 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)
          */
-        constructor(public r: number = 0, public g: number = 0, public b: number = 0) {
+        constructor(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            public r: number = 0, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0) 
+             */
+            public g: number = 0, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            public b: number = 0) {
         }
 
         /**
-         * Returns a string with the Color3 current values.  
+         * Creates a string with the Color3 current values
+         * @returns the string representation of the Color3 object
          */
         public toString(): string {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + "}";
         }
 
         /**
-         * Returns the string "Color3".
+         * Returns the string "Color3"
+         * @returns "Color3"
          */
         public getClassName(): string {
             return "Color3";
         }
+
         /**
-         * Returns the Color3 hash code.  
+         * Compute the Color3 hash code
+         * @returns an unique number that can be used to hash Color3 objects
          */
         public getHashCode(): number {
             let hash = this.r || 0;
@@ -34,9 +57,12 @@
         }
 
         // 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
          */
         public toArray(array: FloatArray, index?: number): Color3 {
             if (index === undefined) {
@@ -51,14 +77,17 @@
         }
 
         /**
-         * 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
          */
         public toColor4(alpha = 1): Color4 {
             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
          */
         public asArray(): number[] {
             var result = new Array<number>();
@@ -67,23 +96,27 @@
         }
 
         /**
-         * Returns the luminance value (float).  
+         * Returns the luminance value
+         * @returns a float value
          */
         public toLuminance(): number {
             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
          */
         public multiply(otherColor: Color3): Color3 {
             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
          */
         public multiplyToRef(otherColor: Color3, result: Color3): Color3 {
             result.r = this.r * otherColor.r;
@@ -93,30 +126,39 @@
         }
 
         /**
-         * 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 
          */
         public equals(otherColor: Color3): boolean {
             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 
          */
         public equalsFloats(r: number, g: number, b: number): boolean {
             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.  
          */
         public scale(scale: number): Color3 {
             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.  
          */
         public scaleToRef(scale: number, result: Color3): Color3 {
             result.r = this.r * scale;
@@ -126,12 +168,11 @@
         }
 
         /**
-         * 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
          */
         public clampToRef(min: number = 0, max: number = 1, result: Color3): Color3 {
             result.r = BABYLON.Scalar.Clamp(this.r, min, max);
@@ -141,15 +182,19 @@
         }
 
         /**
-         * 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
          */
         public add(otherColor: Color3): Color3 {
             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
          */
         public addToRef(otherColor: Color3, result: Color3): Color3 {
             result.r = this.r + otherColor.r;
@@ -159,15 +204,19 @@
         }
 
         /**
-         * 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
          */
         public subtract(otherColor: Color3): Color3 {
             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
          */
         public subtractToRef(otherColor: Color3, result: Color3): Color3 {
             result.r = this.r - otherColor.r;
@@ -177,15 +226,17 @@
         }
 
         /**
-         * Returns a new Color3 copied the current one.  
+         * Copy the current object
+         * @returns a new Color3 copied the current one
          */
         public clone(): Color3 {
             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
          */
         public copyFrom(source: Color3): Color3 {
             this.r = source.r;
@@ -193,9 +244,13 @@
             this.b = source.b;
             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
          */
         public copyFromFloats(r: number, g: number, b: number): Color3 {
             this.r = r;
@@ -205,15 +260,19 @@
         }
 
         /**
-         * 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
          */
         public set(r: number, g: number, b: number): Color3 {
             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
          */
         public toHexString(): string {
             var intR = (this.r * 255) | 0;
@@ -223,7 +282,8 @@
         }
 
         /**
-         * 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
          */
         public toLinearSpace(): Color3 {
             var convertedColor = new Color3();
@@ -232,8 +292,9 @@
         }
 
         /**
-         * 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
          */
         public toLinearSpaceToRef(convertedColor: Color3): Color3 {
             convertedColor.r = Math.pow(this.r, ToLinearSpace);
@@ -243,7 +304,8 @@
         }
 
         /**
-         * 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
          */
         public toGammaSpace(): Color3 {
             var convertedColor = new Color3();
@@ -252,8 +314,9 @@
         }
 
         /**
-         * 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
          */
         public toGammaSpaceToRef(convertedColor: Color3): Color3 {
             convertedColor.r = Math.pow(this.r, ToGammaSpace);
@@ -263,8 +326,11 @@
         }
 
         // 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 
          */
         public static FromHexString(hex: string): Color3 {
             if (hex.substring(0, 1) !== "#" || hex.length !== 7) {
@@ -280,21 +346,32 @@
         }
 
         /**
-         * 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
          */
         public static FromArray(array: ArrayLike<number>, offset: number = 0): Color3 {
             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
          */
         public static FromInts(r: number, g: number, b: number): Color3 {
             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
          */
         public static Lerp(start: Color3, end: Color3, amount: number): Color3 {
             var r = start.r + ((end.r - start.r) * amount);
@@ -303,30 +380,99 @@
             return new Color3(r, g, b);
         }
 
+        /**
+         * Returns a Color3 value containing a red color
+         * @returns a new Color3 object
+         */
         public static Red(): Color3 { return new Color3(1, 0, 0); }
+        /**
+         * Returns a Color3 value containing a green color
+         * @returns a new Color3 object
+         */        
         public static Green(): Color3 { return new Color3(0, 1, 0); }
+        /**
+         * Returns a Color3 value containing a blue color
+         * @returns a new Color3 object
+         */        
         public static Blue(): Color3 { return new Color3(0, 0, 1); }
+        /**
+         * Returns a Color3 value containing a black color
+         * @returns a new Color3 object
+         */        
         public static Black(): Color3 { return new Color3(0, 0, 0); }
+        /**
+         * Returns a Color3 value containing a white color
+         * @returns a new Color3 object
+         */        
         public static White(): Color3 { return new Color3(1, 1, 1); }
+        /**
+         * Returns a Color3 value containing a purple color
+         * @returns a new Color3 object
+         */        
         public static Purple(): Color3 { return new Color3(0.5, 0, 0.5); }
+        /**
+         * Returns a Color3 value containing a magenta color
+         * @returns a new Color3 object
+         */        
         public static Magenta(): Color3 { return new Color3(1, 0, 1); }
+        /**
+         * Returns a Color3 value containing a yellow color
+         * @returns a new Color3 object
+         */        
         public static Yellow(): Color3 { return new Color3(1, 1, 0); }
+        /**
+         * Returns a Color3 value containing a gray color
+         * @returns a new Color3 object
+         */        
         public static Gray(): Color3 { return new Color3(0.5, 0.5, 0.5); }
+        /**
+         * Returns a Color3 value containing a teal color
+         * @returns a new Color3 object
+         */        
         public static Teal(): Color3 { return new Color3(0, 1.0, 1.0); }
+        /**
+         * Returns a Color3 value containing a random color
+         * @returns a new Color3 object
+         */     
         public static Random(): Color3 { return new Color3(Math.random(), Math.random(), Math.random()); }
     }
 
+    /**
+     * Class used to hold a RBGA color
+     */    
     export class Color4 {
         /**
-         * Creates a new Color4 object from the passed float values ( < 1) : red, green, blue, alpha.  
-         */
-        constructor(public r: number = 0, public g: number = 0, public b: number = 0, public a: number = 1) {
+         * 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)
+         */
+        constructor(
+            /**
+             * Defines the red component (between 0 and 1, default is 0)
+             */
+            public r: number = 0, 
+            /**
+             * Defines the green component (between 0 and 1, default is 0) 
+             */
+            public g: number = 0, 
+            /**
+             * Defines the blue component (between 0 and 1, default is 0)
+             */
+            public b: number = 0, 
+            /**
+             * Defines the alpha component (between 0 and 1, default is 1)
+             */
+            public a: number = 1) {
         }
 
         // 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
          */
         public addInPlace(right: Color4): Color4 {
             this.r += right.r;
@@ -337,7 +483,8 @@
         }
 
         /**
-         * 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
          */
         public asArray(): number[] {
             var result = new Array<number>();
@@ -346,8 +493,10 @@
         }
 
         /**
-         * 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
          */
         public toArray(array: number[], index?: number): Color4 {
             if (index === undefined) {
@@ -361,21 +510,28 @@
         }
 
         /**
-         * 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
          */
         public add(right: Color4): Color4 {
             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
          */
         public subtract(right: Color4): Color4 {
             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 
          */
         public subtractToRef(right: Color4, result: Color4): Color4 {
             result.r = this.r - right.r;
@@ -384,16 +540,21 @@
             result.a = this.a - right.a;
             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  
          */
         public scale(scale: number): Color4 {
             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.  
          */
         public scaleToRef(scale: number, result: Color4): Color4 {
             result.r = this.r * scale;
@@ -404,12 +565,11 @@
         }
 
         /**
-         * 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
          */
         public clampToRef(min: number = 0, max: number = 1, result: Color4): Color4 {
             result.r = BABYLON.Scalar.Clamp(this.r, min, max);
@@ -420,19 +580,19 @@
         }
 
         /**
-          * 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
           */
         public multiply(color: Color4): Color4 {
             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
          */
         public multiplyToRef(color: Color4, result: Color4): Color4 {
             result.r = this.r * color.r;
@@ -441,20 +601,26 @@
             result.a = this.a * color.a;
             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
          */
         public toString(): string {
             return "{R: " + this.r + " G:" + this.g + " B:" + this.b + " A:" + this.a + "}";
         }
+
         /**
          * Returns the string "Color4"
+         * @returns "Color4"
          */
         public getClassName(): string {
             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
          */
         public getHashCode(): number {
             let hash = this.r || 0;
@@ -463,15 +629,19 @@
             hash = (hash * 397) ^ (this.a || 0);
             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
          */
         public clone(): Color4 {
             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
          */
         public copyFrom(source: Color4): Color4 {
             this.r = source.r;
@@ -482,8 +652,12 @@
         }
 
         /**
-         * 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 
          */
         public copyFromFloats(r: number, g: number, b: number, a: number): Color4 {
             this.r = r;
@@ -494,14 +668,20 @@
         }
 
         /**
-         * 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 
          */
         public set(r: number, g: number, b: number, a: number): Color4 {
             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
          */
         public toHexString(): string {
             var intR = (this.r * 255) | 0;
@@ -512,7 +692,8 @@
         }
 
         /**
-         * 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
          */
         public toLinearSpace(): Color4 {
             var convertedColor = new Color4();
@@ -521,8 +702,9 @@
         }
 
         /**
-         * 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
          */
         public toLinearSpaceToRef(convertedColor: Color4): Color4 {
             convertedColor.r = Math.pow(this.r, ToLinearSpace);
@@ -533,7 +715,8 @@
         }
 
         /**
-         * 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
          */
         public toGammaSpace(): Color4 {
             var convertedColor = new Color4();
@@ -542,8 +725,9 @@
         }
 
         /**
-         * 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
          */
         public toGammaSpaceToRef(convertedColor: Color4): Color4 {
             convertedColor.r = Math.pow(this.r, ToGammaSpace);
@@ -554,8 +738,11 @@
         }
 
         // 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 
          */
         public static FromHexString(hex: string): Color4 {
             if (hex.substring(0, 1) !== "#" || hex.length !== 9) {
@@ -572,15 +759,24 @@
         }
 
         /**
-         * 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
          */
         public static Lerp(left: Color4, right: Color4, amount: number): Color4 {
             var result = new Color4(0.0, 0.0, 0.0, 0.0);
             Color4.LerpToRef(left, right, amount, result);
             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
          */
         public static LerpToRef(left: Color4, right: Color4, amount: number, result: Color4): void {
             result.r = left.r + (right.r - left.r) * amount;
@@ -590,19 +786,34 @@
         }
 
         /**
-         * 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
          */
         public static FromArray(array: ArrayLike<number>, offset: number = 0): Color4 {
             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
          */
         public static FromInts(r: number, g: number, b: number, a: number): Color4 {
             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)
+         */
         public static CheckColors4(colors: number[], count: number): number[] {
             // Check if color3 was used
             if (colors.length === count * 3) {
@@ -3393,7 +3604,7 @@
          * - 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.  
          */
         public decompose(scale: Vector3, rotation: Quaternion, translation: Vector3): boolean {
             translation.x = this.m[12];

src/Mesh/babylon.mesh.vertexData.ts

@@ -336,7 +336,7 @@
             }
 
             if (!other) {
-                var padding = new Float32Array((<FloatArray>source).length);
+                var padding = new Float32Array(length);
                 padding.fill(defaultValue);
                 return this._mergeElement(source, padding, length);
             }

src/PostProcess/RenderPipeline/Pipelines/babylon.defaultRenderingPipeline.ts

@@ -17,6 +17,10 @@
         public blurX: BlurPostProcess;
         public blurY: BlurPostProcess;
         public copyBack: PassPostProcess;
+        /**
+         * Depth of field effect, applies a blur based on how far away objects are from the focus distance.
+         */
+        public depthOfField: DepthOfFieldEffect;
         public fxaa: FxaaPostProcess;
         public imageProcessing: ImageProcessingPostProcess;
         public finalMerge: PassPostProcess;
@@ -26,6 +30,7 @@
 
         // Values       
         private _bloomEnabled: boolean = false;
+        private _depthOfFieldEnabled: boolean = false;
         private _fxaaEnabled: boolean = false;
         private _imageProcessingEnabled: boolean = true;
         private _defaultPipelineTextureType: number;
@@ -92,6 +97,23 @@
             return this._bloomEnabled;
         }
 
+        /**
+         * If the depth of field is enabled.
+         */
+        @serialize()
+        public get depthOfFieldEnabled(): boolean {
+            return this._depthOfFieldEnabled;
+        }   
+        
+        public set depthOfFieldEnabled(enabled: boolean) {
+            if (this._depthOfFieldEnabled === enabled) {
+                return;
+            }
+            this._depthOfFieldEnabled = enabled;
+            
+            this._buildPipeline();
+        }
+
         public set fxaaEnabled(enabled: boolean) {
             if (this._fxaaEnabled === enabled) {
                 return;
@@ -219,6 +241,10 @@
                 this.copyBack.autoClear = false;
             }
 
+            if(this.depthOfFieldEnabled){
+                this.depthOfField = new DepthOfFieldEffect(this, this._scene, this._cameras[0], this._defaultPipelineTextureType);
+            }
+
             if (this._imageProcessingEnabled) {
                 this.imageProcessing = new ImageProcessingPostProcess("imageProcessing", 1.0, null, Texture.BILINEAR_SAMPLINGMODE, engine, false, this._defaultPipelineTextureType);
                 if (this._hdr) {
@@ -303,6 +329,10 @@
                 if (this.finalMerge) {
                     this.finalMerge.dispose(camera);
                 }
+
+                if(this.depthOfField){
+                    this.depthOfField.disposeEffects(camera);
+                }
             }
 
             (<any>this.pass) = null;
@@ -313,6 +343,7 @@
             (<any>this.imageProcessing) = null;
             (<any>this.fxaa) = null;
             (<any>this.finalMerge) = null;
+            (<any>this.depthOfField) = null;
         }
 
         // Dispose

src/PostProcess/babylon.blurPostProcess.ts

@@ -3,7 +3,7 @@
 		protected _kernel: number;
 		protected _idealKernel: number;
 		protected _packedFloat: boolean	= false;
-
+		protected _staticDefines:string = ""
 		/**
 		 * Sets the length in pixels of the blur sample region
 		 */
@@ -44,10 +44,11 @@
 		}
 
         constructor(name: string, public direction: Vector2, kernel: number, options: number | PostProcessOptions, camera: Nullable<Camera>, samplingMode: number = Texture.BILINEAR_SAMPLINGMODE, engine?: Engine, reusable?: boolean, textureType: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
-            super(name, "kernelBlur", ["delta", "direction"], null, options, camera, samplingMode, engine, reusable, null, textureType, "kernelBlur", {varyingCount: 0, depCount: 0}, true);
-            this.onApplyObservable.add((effect: Effect) => {
-                effect.setFloat2('delta', (1 / this.width) * this.direction.x, (1 / this.height) * this.direction.y);
-            });
+            super(name, "kernelBlur", ["delta", "direction", "cameraMinMaxZ"], ["depthSampler"], options, camera, samplingMode, engine, reusable, null, textureType, "kernelBlur", {varyingCount: 0, depCount: 0}, true);
+			
+			this.onApplyObservable.add((effect: Effect) => {
+				effect.setFloat2('delta', (1 / this.width) * this.direction.x, (1 / this.height) * this.direction.y);
+			});
 
             this.kernel = kernel;
         }
@@ -120,7 +121,8 @@
 
             let varyingCount = Math.min(offsets.length, freeVaryingVec2);
         
-            let defines = "";
+			let defines = "";
+			defines+=this._staticDefines;
             for (let i = 0; i < varyingCount; i++) {
                 defines += `#define KERNEL_OFFSET${i} ${this._glslFloat(offsets[i])}\r\n`;
                 defines += `#define KERNEL_WEIGHT${i} ${this._glslFloat(weights[i])}\r\n`;

src/PostProcess/babylon.circleOfConfusionPostProcess.ts

@@ -0,0 +1,53 @@
+module BABYLON {
+    /**
+     * The CircleOfConfusionPostProcess computes the circle of confusion value for each pixel given required lens parameters. See https://en.wikipedia.org/wiki/Circle_of_confusion
+     */
+    export class CircleOfConfusionPostProcess extends PostProcess {
+        /**
+         * Max lens size in scene units/1000 (eg. millimeter). Standard cameras are 50mm. (default: 50) The diamater of the resulting aperture can be computed by lensSize/fStop.
+         */
+        lensSize = 50
+        /**
+         * F-Stop of the effect's camera. The diamater of the resulting aperture can be computed by lensSize/fStop. (default: 1.4)
+         */
+        fStop = 1.4;
+        /**
+         * Distance away from the camera to focus on in scene units/1000 (eg. millimeter). (default: 2000)
+         */
+        focusDistance = 2000;
+        /**
+         * Focal length of the effect's camera in scene units/1000 (eg. millimeter). (default: 50)
+         */
+        focalLength = 50;
+        
+        /**
+         * Creates a new instance of @see CircleOfConfusionPostProcess
+         * @param name The name of the effect.
+         * @param scene The scene the effect belongs to.
+         * @param depthTexture The depth texture of the scene to compute the circle of confusion.
+         * @param options The required width/height ratio to downsize to before computing the render pass.
+         * @param camera The camera to apply the render pass to.
+         * @param samplingMode The sampling mode to be used when computing the pass. (default: 0)
+         * @param engine The engine which the post process will be applied. (default: current engine)
+         * @param reusable If the post process can be reused on the same frame. (default: false)
+         * @param textureType Type of textures used when performing the post process. (default: 0)
+         */
+        constructor(name: string, scene: Scene, depthTexture: RenderTargetTexture, options: number | PostProcessOptions, camera: Nullable<Camera>, samplingMode?: number, engine?: Engine, reusable?: boolean, textureType: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
+            super(name, "circleOfConfusion", ["cameraMinMaxZ", "focusDistance", "cocPrecalculation"], ["depthSampler"], options, camera, samplingMode, engine, reusable, null, textureType);
+            this.onApplyObservable.add((effect: Effect) => {
+                effect.setTexture("depthSampler", depthTexture);
+                
+                // Circle of confusion calculation, See https://developer.nvidia.com/gpugems/GPUGems/gpugems_ch23.html
+                var aperture = this.lensSize/this.fStop;
+                var cocPrecalculation = ((aperture * this.focalLength)/((this.focusDistance - this.focalLength)));// * ((this.focusDistance - pixelDistance)/pixelDistance) [This part is done in shader]
+                
+                effect.setFloat('focusDistance', this.focusDistance);
+                effect.setFloat('cocPrecalculation', cocPrecalculation);
+                
+                if(scene.activeCamera){
+                    effect.setFloat2('cameraMinMaxZ', scene.activeCamera.minZ, scene.activeCamera.maxZ);
+                }
+            })
+        }
+    }
+}

src/PostProcess/babylon.depthOfFieldBlurPostProcess.ts

@@ -0,0 +1,40 @@
+module BABYLON {    
+    /**
+     * The DepthOfFieldBlurPostProcess applied a blur in a give direction.
+     * This blur differs from the standard BlurPostProcess as it attempts to avoid blurring pixels 
+     * based on samples that have a large difference in distance than the center pixel.
+     * See section 2.6.2 http://fileadmin.cs.lth.se/cs/education/edan35/lectures/12dof.pdf
+     */
+    export class DepthOfFieldBlurPostProcess extends BlurPostProcess {
+        /**
+         * Creates a new instance of @see CircleOfConfusionPostProcess
+         * @param name The name of the effect.
+         * @param scene The scene the effect belongs to.
+         * @param direction The direction the blur should be applied.
+         * @param kernel The size of the kernel used to blur.
+         * @param options The required width/height ratio to downsize to before computing the render pass.
+         * @param camera The camera to apply the render pass to.
+         * @param depthMap The depth map to be used to avoid blurring accross edges
+         * @param imageToBlur The image to apply the blur to (default: Current rendered frame)
+         * @param samplingMode The sampling mode to be used when computing the pass. (default: 0)
+         * @param engine The engine which the post process will be applied. (default: current engine)
+         * @param reusable If the post process can be reused on the same frame. (default: false)
+         * @param textureType Type of textures used when performing the post process. (default: 0)
+         */
+        constructor(name: string, scene: Scene, public direction: Vector2, kernel: number, options: number | PostProcessOptions, camera: Nullable<Camera>, depthMap:RenderTargetTexture, imageToBlur:Nullable<PostProcess> = null, samplingMode: number = Texture.BILINEAR_SAMPLINGMODE, engine?: Engine, reusable?: boolean, textureType: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
+            super(name, direction, kernel, options, camera, samplingMode = Texture.BILINEAR_SAMPLINGMODE, engine, reusable, textureType = Engine.TEXTURETYPE_UNSIGNED_INT);
+            this._staticDefines += `#define DOF 1\r\n`;
+			
+			this.onApplyObservable.add((effect: Effect) => {
+                // TODO: setTextureFromPostProcess seems to be setting the input texture instead of output of the post process passed in 
+                if(imageToBlur != null){
+                    effect.setTextureFromPostProcess("textureSampler", imageToBlur);
+                }
+                effect.setTexture("depthSampler", depthMap);
+                if(scene.activeCamera){
+                    effect.setFloat2('cameraMinMaxZ', scene.activeCamera.minZ, scene.activeCamera.maxZ);
+                }
+			});
+        }
+    }
+}

src/PostProcess/babylon.depthOfFieldEffect.ts

@@ -0,0 +1,109 @@
+module BABYLON {
+    
+    /**
+     * The depth of field effect applies a blur to objects that are closer or further from where the camera is focusing.
+     */
+    export class DepthOfFieldEffect extends PostProcessRenderEffect{
+        private readonly DepthOfFieldPassPostProcessId: string = "DepthOfFieldPassPostProcessId";
+        private readonly CircleOfConfusionPostProcessId: string = "CircleOfConfusionPostProcessEffect"; 
+        private readonly DepthOfFieldBlurXPostProcessId: string = "DepthOfFieldBlurXPostProcessEffect";
+        private readonly DepthOfFieldBlurYPostProcessId: string = "DepthOfFieldBlurYPostProcessEffect";
+        private readonly DepthOfFieldMergePostProcessId: string = "DepthOfFieldMergePostProcessEffect";
+
+        private depthOfFieldPass: PassPostProcess;
+        private circleOfConfusion: CircleOfConfusionPostProcess;
+        private depthOfFieldBlurX: DepthOfFieldBlurPostProcess;
+        private depthOfFieldBlurY: DepthOfFieldBlurPostProcess;
+        private depthOfFieldMerge: DepthOfFieldMergePostProcess;
+
+        /**
+         * The size of the kernel to be used for the blur
+         */
+        public set kernelSize(value: number){
+            this.depthOfFieldBlurX.kernel = value;
+            this.depthOfFieldBlurY.kernel = value;
+        }
+        public get kernelSize(){
+            return this.depthOfFieldBlurX.kernel;
+        }
+        /**
+         * The focal the length of the camera used in the effect
+         */
+        public set focalLength(value: number){
+            this.circleOfConfusion.focalLength = value;
+        }
+        public get focalLength(){
+            return this.circleOfConfusion.focalLength;
+        }
+        /**
+         * F-Stop of the effect's camera. The diamater of the resulting aperture can be computed by lensSize/fStop. (default: 1.4)
+         */
+        public set fStop(value: number){
+            this.circleOfConfusion.fStop = value;
+        }
+        public get fStop(){
+            return this.circleOfConfusion.fStop;
+        }
+        /**
+         * Distance away from the camera to focus on in scene units/1000 (eg. millimeter). (default: 2000)
+         */
+        public set focusDistance(value: number){
+            this.circleOfConfusion.focusDistance = value;
+        }
+        public get focusDistance(){
+            return this.circleOfConfusion.focusDistance;
+        }
+        /**
+         * Max lens size in scene units/1000 (eg. millimeter). Standard cameras are 50mm. (default: 50) The diamater of the resulting aperture can be computed by lensSize/fStop.
+         */
+        public set lensSize(value: number){
+            this.circleOfConfusion.lensSize = value;
+        }
+        public get lensSize(){
+            return this.circleOfConfusion.lensSize;
+        }
+
+        /**
+         * Creates a new instance of @see DepthOfFieldEffect
+         * @param pipeline The pipeline to add the depth of field effect to.
+         * @param scene The scene the effect belongs to.
+         * @param camera The camera to apply the depth of field on.
+         * @param pipelineTextureType The type of texture to be used when performing the post processing.
+         */
+        constructor(pipeline: PostProcessRenderPipeline, scene: Scene, camera:Camera, pipelineTextureType = 0) {
+            super(scene.getEngine(), "depth of field", ()=>{return this.circleOfConfusion}, true);
+            // Enable and get current depth map
+            var depthMap = scene.enableDepthRenderer().getDepthMap();
+            // Circle of confusion value for each pixel is used to determine how much to blur that pixel
+            this.circleOfConfusion = new BABYLON.CircleOfConfusionPostProcess("circleOfConfusion", scene, depthMap, 1, null, BABYLON.Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            pipeline.addEffect(new PostProcessRenderEffect(scene.getEngine(), this.CircleOfConfusionPostProcessId, () => { return this.circleOfConfusion; }, true));  
+         
+            // Capture circle of confusion texture
+            this.depthOfFieldPass = new PassPostProcess("depthOfFieldPass", 1.0, null, Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            pipeline.addEffect(new PostProcessRenderEffect(scene.getEngine(), this.DepthOfFieldPassPostProcessId, () => { return this.depthOfFieldPass; }, true));
+
+            // Blur the image but do not blur on sharp far to near distance changes to avoid bleeding artifacts 
+            // See section 2.6.2 http://fileadmin.cs.lth.se/cs/education/edan35/lectures/12dof.pdf
+            this.depthOfFieldBlurY = new DepthOfFieldBlurPostProcess("verticle blur", scene, new Vector2(0, 1.0), 15, 1.0, null, depthMap, this.circleOfConfusion, Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            pipeline.addEffect(new PostProcessRenderEffect(scene.getEngine(), this.DepthOfFieldBlurYPostProcessId, () => { return this.depthOfFieldBlurY; }, true));
+            this.depthOfFieldBlurX = new DepthOfFieldBlurPostProcess("horizontal blur", scene, new Vector2(1.0, 0), 15, 1.0, null,  depthMap, null, Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            pipeline.addEffect(new PostProcessRenderEffect(scene.getEngine(), this.DepthOfFieldBlurXPostProcessId, () => { return this.depthOfFieldBlurX; }, true));
+
+            // Merge blurred images with original image based on circleOfConfusion
+            this.depthOfFieldMerge = new DepthOfFieldMergePostProcess("depthOfFieldMerge", this.circleOfConfusion, this.depthOfFieldPass, 1, null, BABYLON.Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            pipeline.addEffect(new PostProcessRenderEffect(scene.getEngine(), this.DepthOfFieldMergePostProcessId, () => { return this.depthOfFieldMerge; }, true));
+        }
+
+        /**
+         * Disposes each of the internal effects for a given camera.
+         * @param camera The camera to dispose the effect on.
+         */
+        public disposeEffects(camera:Camera){
+            this.depthOfFieldPass.dispose(camera);
+            this.circleOfConfusion.dispose(camera);
+            this.depthOfFieldBlurX.dispose(camera);
+            this.depthOfFieldBlurY.dispose(camera);
+            this.depthOfFieldMerge.dispose(camera);
+        }
+    }
+}

src/PostProcess/babylon.depthOfFieldMergePostProcess.ts

@@ -0,0 +1,26 @@
+module BABYLON {
+    /**
+     * The DepthOfFieldMergePostProcess merges blurred images with the original based on the values of the circle of confusion.
+     */
+    export class DepthOfFieldMergePostProcess extends PostProcess {
+        /**
+         * Creates a new instance of @see CircleOfConfusionPostProcess
+         * @param name The name of the effect.
+         * @param original The non-blurred image to be modified
+         * @param circleOfConfusion The circle of confusion post process that will determine how blurred each pixel should become.
+         * @param options The required width/height ratio to downsize to before computing the render pass.
+         * @param camera The camera to apply the render pass to.
+         * @param samplingMode The sampling mode to be used when computing the pass. (default: 0)
+         * @param engine The engine which the post process will be applied. (default: current engine)
+         * @param reusable If the post process can be reused on the same frame. (default: false)
+         * @param textureType Type of textures used when performing the post process. (default: 0)
+         */
+        constructor(name: string, original: PostProcess, circleOfConfusion: PostProcess, options: number | PostProcessOptions, camera: Nullable<Camera>, samplingMode?: number, engine?: Engine, reusable?: boolean, textureType: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
+            super(name, "depthOfFieldMerge", [], ["circleOfConfusionSampler", "originalSampler"], options, camera, samplingMode, engine, reusable, null, textureType);
+            this.onApplyObservable.add((effect: Effect) => {
+                effect.setTextureFromPostProcess("circleOfConfusionSampler", circleOfConfusion);
+                effect.setTextureFromPostProcess("originalSampler", original);
+            })
+        }
+    }
+}

src/Shaders/ShadersInclude/kernelBlurFragment.fx

@@ -1,5 +1,14 @@
-#ifdef PACKEDFLOAT
-    blend += unpack(texture2D(textureSampler, sampleCoord{X})) * KERNEL_WEIGHT{X};
+#ifdef DOF
+    sampleDepth = sampleDistance(sampleCoord{X});
+    factor = clamp(1.0-((centerSampleDepth - sampleDepth)/centerSampleDepth),0.0,1.0);
+    computedWeight = KERNEL_WEIGHT{X} * factor;
+    sumOfWeights += computedWeight;
 #else
-    blend += texture2D(textureSampler, sampleCoord{X}) * KERNEL_WEIGHT{X};
+    computedWeight = KERNEL_WEIGHT{X};
+#endif
+
+#ifdef PACKEDFLOAT
+    blend += unpack(texture2D(textureSampler, sampleCoord{X})) * computedWeight;
+#else
+    blend += texture2D(textureSampler, sampleCoord{X}) * computedWeight;
 #endif

src/Shaders/ShadersInclude/kernelBlurFragment2.fx

@@ -1,5 +1,14 @@
-#ifdef PACKEDFLOAT
-    blend += unpack(texture2D(textureSampler, sampleCenter + delta * KERNEL_DEP_OFFSET{X})) * KERNEL_DEP_WEIGHT{X};
+#ifdef DOF
+    sampleDepth = sampleDistance(sampleCoord{X});
+    factor = clamp(1.0-((centerSampleDepth - sampleDepth)/centerSampleDepth),0.0,1.0);
+    computedWeight = KERNEL_DEP_WEIGHT{X} * factor;
+    sumOfWeights += computedWeight;
 #else
-    blend += texture2D(textureSampler, sampleCenter + delta * KERNEL_DEP_OFFSET{X}) * KERNEL_DEP_WEIGHT{X};
+    computedWeight = KERNEL_DEP_WEIGHT{X};
+#endif
+
+#ifdef PACKEDFLOAT
+    blend += unpack(texture2D(textureSampler, sampleCenter + delta * KERNEL_DEP_OFFSET{X})) * computedWeight;
+#else
+    blend += texture2D(textureSampler, sampleCenter + delta * KERNEL_DEP_OFFSET{X}) * computedWeight;
 #endif

src/Shaders/ShadersInclude/lightFragment.fx

@@ -23,6 +23,9 @@
 				info = computeLighting(viewDirectionW, normalW, light{X}.vLightData, light{X}.vLightDiffuse.rgb, light{X}.vLightSpecular, light{X}.vLightDiffuse.a, glossiness);
 			#endif
 		#endif
+		#ifdef PROJECTEDLIGHTTEXTURE{X}
+			info = computeProjectionTexture(info,projectionLightSampler{X},textureProjectionMatrix{X});
+		#endif
     #endif
 	#ifdef SHADOW{X}
 		#ifdef SHADOWCLOSEESM{X}

src/Shaders/ShadersInclude/lightFragmentDeclaration.fx

@@ -25,4 +25,8 @@
 	#ifdef HEMILIGHT{X}
 		uniform vec3 vLightGround{X};
 	#endif
+	#ifdef PROJECTEDLIGHTTEXTURE{X}
+		uniform mat4 textureProjectionMatrix{X};
+		uniform sampler2D projectionLightSampler{X};
+	#endif
 #endif

src/Shaders/ShadersInclude/lightUboDeclaration.fx

@@ -13,7 +13,10 @@
 		vec4 shadowsInfo;
 		vec2 depthValues;
 	} light{X};
-
+#ifdef PROJECTEDLIGHTTEXTURE{X}
+	uniform mat4 textureProjectionMatrix{X};
+	uniform sampler2D projectionLightSampler{X};
+#endif
 #ifdef SHADOW{X}
 	#if defined(SHADOWCUBE{X})
 		uniform samplerCube shadowSampler{X};

src/Shaders/ShadersInclude/lightsFragmentFunctions.fx

@@ -1,4 +1,4 @@
-// Light Computing
+// Light Computing
 struct lightingInfo
 {
 	vec3 diffuse;
@@ -32,9 +32,7 @@ lightingInfo computeLighting(vec3 viewDirectionW, vec3 vNormal, vec4 lightData,
 #ifdef NDOTL
 	result.ndl = ndl;
 #endif
-
 	result.diffuse = ndl * diffuseColor * attenuation;
-
 #ifdef SPECULARTERM
 	// Specular
 	vec3 angleW = normalize(viewDirectionW + lightVectorW);
@@ -67,7 +65,6 @@ lightingInfo computeSpotLighting(vec3 viewDirectionW, vec3 vNormal, vec4 lightDa
 		result.ndl = ndl;
 #endif
 		result.diffuse = ndl * diffuseColor * attenuation;
-
 #ifdef SPECULARTERM
 		// Specular
 		vec3 angleW = normalize(viewDirectionW + lightVectorW);
@@ -109,6 +106,14 @@ lightingInfo computeHemisphericLighting(vec3 viewDirectionW, vec3 vNormal, vec4
 
 	result.specular = specComp * specularColor;
 #endif
+		return result;
+}
 
+lightingInfo computeProjectionTexture(lightingInfo origin,sampler2D projectionLightSampler, mat4 textureProjectionMatrix){
+	lightingInfo result = origin;
+	vec4 strq = textureProjectionMatrix * vec4(vPositionW, 1.0);
+	strq /= strq.w;
+	vec4 textureColor = texture2D(projectionLightSampler, strq.xy);
+	result.diffuse *= vec3(textureColor);
 	return result;
-}
+}

src/Shaders/circleOfConfusion.fragment.fx

@@ -0,0 +1,25 @@
+// samplers
+uniform sampler2D depthSampler;
+
+// varyings
+varying vec2 vUV;
+
+// preconputed uniforms (not effect parameters)
+uniform vec2 cameraMinMaxZ;
+
+// uniforms
+uniform float focusDistance;
+uniform float cocPrecalculation;
+
+float sampleDistance(const in vec2 offset) {
+    float depth = texture2D(depthSampler, offset).r;	// depth value from DepthRenderer: 0 to 1
+	return (cameraMinMaxZ.x + (cameraMinMaxZ.y - cameraMinMaxZ.x)*depth)*1000.0;		            // actual distance from the lens in scene units/1000 (eg. millimeter)
+}
+
+void main(void)
+{
+    float pixelDistance = sampleDistance(vUV);
+    float coc = abs(cocPrecalculation* ((focusDistance - pixelDistance)/pixelDistance));
+    coc = clamp(coc, 0.0, 1.0);
+    gl_FragColor = vec4(coc, coc, coc, 1.0);
+}

src/Shaders/depthOfFieldMerge.fragment.fx

@@ -0,0 +1,15 @@
+// samplers
+uniform sampler2D textureSampler;
+uniform sampler2D originalSampler;
+uniform sampler2D circleOfConfusionSampler;
+
+// varyings
+varying vec2 vUV;
+
+void main(void)
+{
+    vec4 blurred = texture2D(textureSampler, vUV);
+    vec4 original = texture2D(originalSampler, vUV);
+    float coc = texture2D(circleOfConfusionSampler, vUV).r;
+    gl_FragColor = mix(original, blurred, coc);
+}

src/Shaders/kernelBlur.fragment.fx

@@ -4,6 +4,18 @@ uniform vec2 delta;
 
 // Varying
 varying vec2 sampleCenter;
+
+#ifdef DOF
+	uniform sampler2D depthSampler;
+
+	uniform vec2 cameraMinMaxZ;
+
+	float sampleDistance(const in vec2 offset) {
+		float depth = texture2D(depthSampler, offset).r; // depth value from DepthRenderer: 0 to 1 
+		return cameraMinMaxZ.x + (cameraMinMaxZ.y - cameraMinMaxZ.x)*depth; // actual distance from the lens 
+	}
+#endif
+
 #include<kernelBlurVaryingDeclaration>[0..varyingCount]
 
 #ifdef PACKEDFLOAT
@@ -27,11 +39,20 @@ varying vec2 sampleCenter;
 
 void main(void)
 {
-#ifdef PACKEDFLOAT	
-	float blend = 0.;
-#else
-	vec4 blend = vec4(0.);
-#endif
+	#ifdef DOF
+		float sumOfWeights = 0.0; // Since not all values are blended, keep track of sum to devide result by at the end to get an average
+		float sampleDepth = 0.0;
+    	float factor = 0.0;
+		float centerSampleDepth = sampleDistance(sampleCenter);
+	#endif
+
+	float computedWeight = 0.0;
+
+	#ifdef PACKEDFLOAT	
+		float blend = 0.;
+	#else
+		vec4 blend = vec4(0.);
+	#endif
 
 	#include<kernelBlurFragment>[0..varyingCount]
 	#include<kernelBlurFragment2>[0..depCount]
@@ -41,4 +62,12 @@ void main(void)
 	#else
 		gl_FragColor = blend;
 	#endif
+
+	#ifdef DOF
+		// If there are no samples to blend, make pixel black.
+		if(sumOfWeights == 0.0){
+			gl_FragColor = vec4(0.0,0.0,0.0,1.0);
+		}
+		gl_FragColor /= sumOfWeights;
+	#endif
 }

src/Tools/babylon.tools.ts

@@ -1168,6 +1168,32 @@
             });
         }
 
+        /**
+        * Test if the given uri is a base64 string.
+        * @param uri The uri to test
+        * @return True if the uri is a base64 string or false otherwise.
+        */
+        public static IsBase64(uri: string): boolean {
+            return uri.length < 5 ? false : uri.substr(0, 5) === "data:";
+        }
+
+        /**
+        * Decode the given base64 uri.
+        * @param uri The uri to decode
+        * @return The decoded base64 data.
+        */
+        public static DecodeBase64(uri: string): ArrayBuffer {
+            const decodedString = atob(uri.split(",")[1]);
+            const bufferLength = decodedString.length;
+            const bufferView = new Uint8Array(new ArrayBuffer(bufferLength));
+
+            for (let i = 0; i < bufferLength; i++) {
+                bufferView[i] = decodedString.charCodeAt(i);
+            }
+
+            return bufferView.buffer;
+        }
+
         // Logs
         private static _NoneLogLevel = 0;
         private static _MessageLogLevel = 1;

src/babylon.scene.ts

@@ -4619,14 +4619,13 @@
             this.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        public createDefaultCameraOrLight(createArcRotateCamera = false, replace = false, attachCameraControls = false) {
-            // Dispose existing camera or light in replace mode.
+        /**
+         * Creates a default light for the scene.
+         * @param replace Whether to replace the existing lights in the scene.
+         */
+        public createDefaultLight(replace = false): void {
+            // Dispose existing light in replace mode.
             if (replace) {
-                if (this.activeCamera) {
-                    this.activeCamera.dispose();
-                    this.activeCamera = null;
-                }
-
                 if (this.lights) {
                     for (var i = 0; i < this.lights.length; i++) {
                         this.lights[i].dispose();
@@ -4638,6 +4637,22 @@
             if (this.lights.length === 0) {
                 new HemisphericLight("default light", Vector3.Up(), this);
             }
+        }
+
+        /**
+         * Creates a default camera for the scene.
+         * @param createArcRotateCamera Whether to create an arc rotate or a free camera.
+         * @param replace Whether to replace the existing active camera in the scene.
+         * @param attachCameraControls Whether to attach camera controls to the canvas.
+         */
+        public createDefaultCamera(createArcRotateCamera = false, replace = false, attachCameraControls = false): void {
+            // Dispose existing camera in replace mode.
+            if (replace) {
+                if (this.activeCamera) {
+                    this.activeCamera.dispose();
+                    this.activeCamera = null;
+                }
+            }
 
             // Camera
             if (!this.activeCamera) {
@@ -4670,6 +4685,11 @@
             }
         }
 
+        public createDefaultCameraOrLight(createArcRotateCamera = false, replace = false, attachCameraControls = false): void {
+            this.createDefaultLight(replace);
+            this.createDefaultCamera(createArcRotateCamera, replace, attachCameraControls);
+        }
+
         public createDefaultSkybox(environmentTexture?: BaseTexture, pbr = false, scale = 1000, blur = 0): Nullable<Mesh> {
             if (environmentTexture) {
                 this.environmentTexture = environmentTexture;

tests/unit/babylon/babylonReference.ts

@@ -1,6 +1,6 @@
 /// <reference path="../../../dist/preview release/babylon.d.ts" />
 /// <reference path="../../../dist/preview release/loaders/babylon.glTF2FileLoader.d.ts" />
-/// <reference path="../../../dist/babylon.glTFInterface.d.ts"/>
+/// <reference path="../../../dist/babylon.glTF2Interface.d.ts"/>
 /// <reference path="../../../dist/preview release/serializers/babylon.glTF2Serializer.d.ts" />
 
 /// <reference path="../node_modules/@types/chai/index.d.ts" />

tests/validation/config.json

@@ -237,6 +237,17 @@
       "referenceImage": "assetContainer.png"
     },
     {
+      "title": "Depth of field",
+      "playgroundId": "#IDSQK2#16",
+      "renderCount": 20,
+      "referenceImage": "depthOfField.png"
+    },
+    {
+      "title": "Kernel Blur",
+      "playgroundId": "#Y0WKT0",
+      "referenceImage": "KernelBlur.png"
+    },
+    {
       "title": "GLTF Mesh Primitive Attribute Test",
       "scriptToRun": "/Demos/GLTFMeshPrimitiveAttributeTest/index.js",
       "functionToCall": "createScene",