Merge remote-tracking branch 'BabylonJS/master' into viewer-changes-new

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"
@@ -792,7 +841,6 @@
         "renderingPipeline": {
             "files": [
                 "../../src/PostProcess/RenderPipeline/babylon.postProcessRenderPipelineManager.js",
-                "../../src/PostProcess/RenderPipeline/babylon.postProcessRenderPass.js",
                 "../../src/PostProcess/RenderPipeline/babylon.postProcessRenderEffect.js",
                 "../../src/PostProcess/RenderPipeline/babylon.postProcessRenderPipeline.js"
             ],
@@ -827,7 +875,10 @@
             ],
             "dependUpon": [
                 "renderingPipeline",
-                "additionalPostProcess_fxaa"
+                "additionalPostProcess_fxaa",
+                "additionalPostProcess_circleOfConfusion",
+                "additionalPostProcess_depthOfFieldMerge",
+                "additionalPostProcess_depthOfFieldEffect"
             ]
         },
         "bones": {
@@ -1600,7 +1651,29 @@
         ],
         "build": {
             "srcOutputDirectory": "../../Viewer/",
-            "distOutputDirectory": "/viewer/"
+            "outputs": [
+                {
+                    "destination": [
+                        {
+                            "filename": "viewer.min.js",
+                            "outputDirectory": "/../../Viewer/dist/"
+                        },
+                        {
+                            "filename": "babylon.viewer.js",
+                            "outputDirectory": "/viewer/"
+                        }
+                    ],
+                    "minified": true
+                },
+                {
+                    "destination": [
+                        {
+                            "filename": "viewer.js",
+                            "outputDirectory": "/../../Viewer/dist/"
+                        }
+                    ]
+                }
+            ]
         }
     }
 }

Tools/Gulp/gulpfile.js

@@ -426,14 +426,40 @@ var buildExternalLibrary = function (library, settings, watch) {
         }
 
         if (library.webpack) {
-            return waitAll.on("end", function () {
-                return webpack(require(library.webpack))
-                    .pipe(rename(library.output.replace(".js", library.noBundleInName ? '.js' : ".bundle.js")))
-                    .pipe(addModuleExports(library.moduleDeclaration, false, false, true))
-                    .pipe(uglify())
-                    .pipe(optimisejs())
-                    .pipe(gulp.dest(outputDirectory))
-            });
+            let sequence = [waitAll];
+            let wpBuild = webpack(require(library.webpack));
+            if (settings.build.outputs) {
+                let build = wpBuild
+                    .pipe(addModuleExports(library.moduleDeclaration, false, false, true));
+
+                settings.build.outputs.forEach(out => {
+                    let outBuild = build;
+                    if (out.minified) {
+                        outBuild = build
+                            .pipe(uglify())
+                            .pipe(optimisejs())
+                    }
+
+                    out.destination.forEach(dest => {
+                        var outputDirectory = config.build.outputDirectory + dest.outputDirectory;
+                        let destBuild = outBuild
+                            .pipe(rename(dest.filename.replace(".js", library.noBundleInName ? '.js' : ".bundle.js")))
+                            .pipe(gulp.dest(outputDirectory));
+                        sequence.push(destBuild);
+                    });
+                })
+            } else {
+                sequence.push(
+                    wpBuild
+                        .pipe(rename(library.output.replace(".js", library.noBundleInName ? '.js' : ".bundle.js")))
+                        .pipe(addModuleExports(library.moduleDeclaration, false, false, true))
+                        .pipe(uglify())
+                        .pipe(optimisejs())
+                        .pipe(gulp.dest(outputDirectory))
+                )
+            }
+
+            return merge2(sequence);
         }
         else {
             return waitAll;
@@ -911,14 +937,14 @@ gulp.task("tests-unit-transpile", function (done) {
 
     var tsResult = gulp.src("../../tests/unit/**/*.ts", { base: "../../" })
         .pipe(tsProject());
-    
+
     tsResult.once("error", function () {
         tsResult.once("finish", function () {
             console.log("Typescript compile failed");
             process.exit(1);
         });
     });
- 
+
     return tsResult.js.pipe(gulp.dest("../../"));
 });
 
@@ -951,7 +977,7 @@ gulp.task("tests-unit", ["tests-unit-transpile"], function (done) {
     server.start();
 });
 
-gulp.task("tests-whatsnew", function(done) {
+gulp.task("tests-whatsnew", function (done) {
     // Only checks on Travis
     if (!process.env.TRAVIS) {
         done();
@@ -980,12 +1006,12 @@ gulp.task("tests-whatsnew", function(done) {
             oldData += data;
         });
         res.on("end", () => {
-            fs.readFile("../../dist/preview release/what's new.md", "utf-8", function(err, newData) {
+            fs.readFile("../../dist/preview release/what's new.md", "utf-8", function (err, newData) {
                 if (err || oldData != newData) {
                     done();
                     return;
                 }
-                
+
                 console.error("What's new file did not change.");
                 process.exit(1);
             });

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/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)
@@ -32,10 +33,15 @@
 - VRHelper will notify now onSelectedMeshUnselected observable to subscribers when the applied ray selection predicate does not produce a hit and a mesh compliant with the meshSelectionPredicate was previously selected
    ([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))
+- 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))
+- Gulp process now supports multiple outputs when using webpack. ([RaananW](https://github.com/RaananW))
 
 ## 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
-
-
+- Removed unused PostProcessRenderPass class and extended postProcessingRenderingEffect to support multiple PostProcesses ([trevordev](https://github.com/trevordev))

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/Shadows/babylon.shadowGenerator.ts

@@ -3,23 +3,76 @@
      * Interface to implement to create a shadow generator compatible with BJS.
      */
     export interface IShadowGenerator {
+        /**
+         * Gets the main RTT containing the shadow map (usually storing depth from the light point of view).
+         * @returns The render target texture if present otherwise, null
+         */
         getShadowMap(): Nullable<RenderTargetTexture>;
+        /**
+         * Gets the RTT used during rendering (can be a blurred version of the shadow map or the shadow map itself).
+         * @returns The render target texture if the shadow map is present otherwise, null
+         */
         getShadowMapForRendering(): Nullable<RenderTargetTexture>;
 
+        /**
+         * Determine wheter the shadow generator is ready or not (mainly all effects and related post processes needs to be ready).
+         * @param subMesh The submesh we want to render in the shadow map
+         * @param useInstances Defines wether will draw in the map using instances
+         * @returns true if ready otherwise, false
+         */
         isReady(subMesh: SubMesh, useInstances: boolean): boolean;
 
+        /**
+         * Prepare all the defines in a material relying on a shadow map at the specified light index.
+         * @param defines Defines of the material we want to update
+         * @param lightIndex Index of the light in the enabled light list of the material
+         */
         prepareDefines(defines: MaterialDefines, lightIndex: number): void;
+        /**
+         * Binds the shadow related information inside of an effect (information like near, far, darkness...
+         * defined in the generator but impacting the effect).
+         * It implies the unifroms available on the materials are the standard BJS ones.
+         * @param lightIndex Index of the light in the enabled light list of the material owning the effect
+         * @param effect The effect we are binfing the information for 
+         */
         bindShadowLight(lightIndex: string, effect: Effect): void;
+        /**
+         * Gets the transformation matrix used to project the meshes into the map from the light point of view.
+         * (eq to shadow prjection matrix * light transform matrix)
+         * @returns The transform matrix used to create the shadow map
+         */
         getTransformMatrix(): Matrix;
 
+        /**
+         * Recreates the shadow map dependencies like RTT and post processes. This can be used during the switch between
+         * Cube and 2D textures for instance.
+         */
         recreateShadowMap(): void;
 
+        /**
+         * Forces all the attached effect to compile to enable rendering only once ready vs. lazyly compiling effects.
+         * @param onCompiled Callback triggered at the and of the effects compilation
+         * @param options Sets of optional options forcing the compilation with different modes 
+         */
         forceCompilation(onCompiled?: (generator: ShadowGenerator) => void, options?: Partial<{ useInstances: boolean }>): void;
 
+        /**
+         * Serializes the shadow generator setup to a json object.
+         * @returns The serialized JSON object 
+         */
         serialize(): any;
+
+        /**
+         * Disposes the Shadow map and related Textures and effects.
+         */
         dispose(): void;
     }
 
+    /**
+     * Default implementation of @see IShadowGenerator.
+     * This is the main object responsible of generating shadows in the framework.
+     * Documentation: https://doc.babylonjs.com/babylon101/shadows
+     */
     export class ShadowGenerator implements IShadowGenerator {
         private static _FILTER_NONE = 0;
         private static _FILTER_EXPONENTIALSHADOWMAP = 1;
@@ -28,44 +81,81 @@
         private static _FILTER_CLOSEEXPONENTIALSHADOWMAP = 4;
         private static _FILTER_BLURCLOSEEXPONENTIALSHADOWMAP = 5;
 
-        // Static
+        /**
+         * Shadow generator mode None: no filtering applied.
+         */
         public static get FILTER_NONE(): number {
             return ShadowGenerator._FILTER_NONE;
         }
 
+        /**
+         * Shadow generator mode Poisson Sampling: Percentage Closer Filtering.
+         * (Multiple Tap around evenly distributed around the pixel are used to evaluate the shadow strength)
+         */
         public static get FILTER_POISSONSAMPLING(): number {
             return ShadowGenerator._FILTER_POISSONSAMPLING;
         }
 
+        /**
+         * Shadow generator mode ESM: Exponential Shadow Mapping.
+         * (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
+         */
         public static get FILTER_EXPONENTIALSHADOWMAP(): number {
             return ShadowGenerator._FILTER_EXPONENTIALSHADOWMAP;
         }
 
+        /**
+         * Shadow generator mode ESM: Blurred Exponential Shadow Mapping.
+         * (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
+         */
         public static get FILTER_BLUREXPONENTIALSHADOWMAP(): number {
             return ShadowGenerator._FILTER_BLUREXPONENTIALSHADOWMAP;
         }
 
+        /**
+         * Shadow generator mode ESM: Exponential Shadow Mapping using the inverse of the exponential preventing 
+         * edge artifacts on steep falloff.
+         * (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
+         */
         public static get FILTER_CLOSEEXPONENTIALSHADOWMAP(): number {
             return ShadowGenerator._FILTER_CLOSEEXPONENTIALSHADOWMAP;
         }
 
+        /**
+         * Shadow generator mode ESM: Blurred Exponential Shadow Mapping using the inverse of the exponential preventing 
+         * edge artifacts on steep falloff.
+         * (http://developer.download.nvidia.com/presentations/2008/GDC/GDC08_SoftShadowMapping.pdf)
+         */
         public static get FILTER_BLURCLOSEEXPONENTIALSHADOWMAP(): number {
             return ShadowGenerator._FILTER_BLURCLOSEEXPONENTIALSHADOWMAP;
         }
 
-        // Members
         private _bias = 0.00005;
+        /**
+         * Gets the bias: offset applied on the depth preventing acnea.
+         */
         public get bias(): number {
             return this._bias;
         }
+        /**
+         * Sets the bias: offset applied on the depth preventing acnea.
+         */
         public set bias(bias: number) {
             this._bias = bias;
         }
 
         private _blurBoxOffset = 1;
+        /**
+         * Gets the blur box offset: offset applied during the blur pass.
+         * Only usefull if useKernelBlur = false
+         */
         public get blurBoxOffset(): number {
             return this._blurBoxOffset;
         }
+        /**
+         * Sets the blur box offset: offset applied during the blur pass.
+         * Only usefull if useKernelBlur = false
+         */
         public set blurBoxOffset(value: number) {
             if (this._blurBoxOffset === value) {
                 return;
@@ -76,9 +166,17 @@
         }
 
         private _blurScale = 2;
+        /**
+         * Gets the blur scale: scale of the blurred texture compared to the main shadow map.
+         * 2 means half of the size.
+         */
         public get blurScale(): number {
             return this._blurScale;
         }
+        /**
+         * Sets the blur scale: scale of the blurred texture compared to the main shadow map.
+         * 2 means half of the size.
+         */
         public set blurScale(value: number) {
             if (this._blurScale === value) {
                 return;
@@ -89,9 +187,17 @@
         }
 
         private _blurKernel = 1;
+        /**
+         * Gets the blur kernel: kernel size of the blur pass.
+         * Only usefull if useKernelBlur = true
+         */
         public get blurKernel(): number {
             return this._blurKernel;
         }
+        /**
+         * Sets the blur kernel: kernel size of the blur pass.
+         * Only usefull if useKernelBlur = true
+         */
         public set blurKernel(value: number) {
             if (this._blurKernel === value) {
                 return;
@@ -102,9 +208,17 @@
         }
 
         private _useKernelBlur = false;
+        /**
+         * Gets whether the blur pass is a kernel blur (if true) or box blur.
+         * Only usefull in filtered mode (useBlurExponentialShadowMap...)
+         */
         public get useKernelBlur(): boolean {
             return this._useKernelBlur;
         }
+        /**
+         * Sets whether the blur pass is a kernel blur (if true) or box blur.
+         * Only usefull in filtered mode (useBlurExponentialShadowMap...)
+         */
         public set useKernelBlur(value: boolean) {
             if (this._useKernelBlur === value) {
                 return;
@@ -115,17 +229,32 @@
         }
 
         private _depthScale: number;
+        /**
+         * Gets the depth scale used in ESM mode.
+         */
         public get depthScale(): number {
             return this._depthScale !== undefined ? this._depthScale : this._light.getDepthScale();
         }
+        /**
+         * Sets the depth scale used in ESM mode.
+         * This can override the scale stored on the light.
+         */
         public set depthScale(value: number) {
             this._depthScale = value;
         }
 
         private _filter = ShadowGenerator.FILTER_NONE;
+        /**
+         * Gets the current mode of the shadow generator (normal, PCF, ESM...).
+         * The returned value is a number equal to one of the available mode defined in ShadowMap.FILTER_x like _FILTER_NONE
+         */
         public get filter(): number {
             return this._filter;
         }
+        /**
+         * Sets the current mode of the shadow generator (normal, PCF, ESM...).
+         * The returned value is a number equal to one of the available mode defined in ShadowMap.FILTER_x like _FILTER_NONE
+         */
         public set filter(value: number) {
             // Blurring the cubemap is going to be too expensive. Reverting to unblurred version
             if (this._light.needCube()) {
@@ -149,10 +278,15 @@
             this._light._markMeshesAsLightDirty();
         }
 
+        /**
+         * Gets if the current filter is set to Poisson Sampling aka PCF.
+         */
         public get usePoissonSampling(): boolean {
             return this.filter === ShadowGenerator.FILTER_POISSONSAMPLING;
         }
-
+        /**
+         * Sets the current filter to Poisson Sampling aka PCF.
+         */
         public set usePoissonSampling(value: boolean) {
             if (!value && this.filter !== ShadowGenerator.FILTER_POISSONSAMPLING) {
                 return;
@@ -161,27 +295,49 @@
             this.filter = (value ? ShadowGenerator.FILTER_POISSONSAMPLING : ShadowGenerator.FILTER_NONE);
         }
 
+        /**
+         * Gets if the current filter is set to VSM.
+         * DEPRECATED. Should use useExponentialShadowMap instead.
+         */
         public get useVarianceShadowMap(): boolean {
             Tools.Warn("VSM are now replaced by ESM. Please use useExponentialShadowMap instead.");
             return this.useExponentialShadowMap;
         }
+        /**
+         * Sets the current filter is to VSM.
+         * DEPRECATED. Should use useExponentialShadowMap instead.
+         */
         public set useVarianceShadowMap(value: boolean) {
             Tools.Warn("VSM are now replaced by ESM. Please use useExponentialShadowMap instead.");
             this.useExponentialShadowMap = value;
         }
 
+        /**
+         * Gets if the current filter is set to blurred VSM.
+         * DEPRECATED. Should use useBlurExponentialShadowMap instead.
+         */
         public get useBlurVarianceShadowMap(): boolean {
             Tools.Warn("VSM are now replaced by ESM. Please use useBlurExponentialShadowMap instead.");
             return this.useBlurExponentialShadowMap;
         }
+        /**
+         * Sets the current filter is to blurred VSM.
+         * DEPRECATED. Should use useBlurExponentialShadowMap instead.
+         */
         public set useBlurVarianceShadowMap(value: boolean) {
             Tools.Warn("VSM are now replaced by ESM. Please use useBlurExponentialShadowMap instead.");
             this.useBlurExponentialShadowMap = value;
         }
 
+        /**
+         * Gets if the current filter is set to ESM.
+         */
         public get useExponentialShadowMap(): boolean {
             return this.filter === ShadowGenerator.FILTER_EXPONENTIALSHADOWMAP;
         }
+        /**
+         * Sets the current filter is to ESM.
+         */
         public set useExponentialShadowMap(value: boolean) {
             if (!value && this.filter !== ShadowGenerator.FILTER_EXPONENTIALSHADOWMAP) {
                 return;
@@ -189,9 +345,15 @@
             this.filter = (value ? ShadowGenerator.FILTER_EXPONENTIALSHADOWMAP : ShadowGenerator.FILTER_NONE);
         }
 
+        /**
+         * Gets if the current filter is set to filtered ESM.
+         */
         public get useBlurExponentialShadowMap(): boolean {
             return this.filter === ShadowGenerator.FILTER_BLUREXPONENTIALSHADOWMAP;
         }
+        /**
+         * Gets if the current filter is set to filtered  ESM.
+         */
         public set useBlurExponentialShadowMap(value: boolean) {
             if (!value && this.filter !== ShadowGenerator.FILTER_BLUREXPONENTIALSHADOWMAP) {
                 return;
@@ -199,9 +361,17 @@
             this.filter = (value ? ShadowGenerator.FILTER_BLUREXPONENTIALSHADOWMAP : ShadowGenerator.FILTER_NONE);
         }
 
+        /**
+         * Gets if the current filter is set to "close ESM" (using the inverse of the 
+         * exponential to prevent steep falloff artifacts).
+         */
         public get useCloseExponentialShadowMap(): boolean {
             return this.filter === ShadowGenerator.FILTER_CLOSEEXPONENTIALSHADOWMAP;
         }
+        /**
+         * Sets the current filter to "close ESM" (using the inverse of the 
+         * exponential to prevent steep falloff artifacts).
+         */
         public set useCloseExponentialShadowMap(value: boolean) {
             if (!value && this.filter !== ShadowGenerator.FILTER_CLOSEEXPONENTIALSHADOWMAP) {
                 return;
@@ -209,9 +379,17 @@
             this.filter = (value ? ShadowGenerator.FILTER_CLOSEEXPONENTIALSHADOWMAP : ShadowGenerator.FILTER_NONE);
         }
 
+        /**
+         * Gets if the current filter is set to filtered "close ESM" (using the inverse of the 
+         * exponential to prevent steep falloff artifacts).
+         */
         public get useBlurCloseExponentialShadowMap(): boolean {
             return this.filter === ShadowGenerator.FILTER_BLURCLOSEEXPONENTIALSHADOWMAP;
         }
+        /**
+         * Sets the current filter to fileterd "close ESM" (using the inverse of the 
+         * exponential to prevent steep falloff artifacts).
+         */
         public set useBlurCloseExponentialShadowMap(value: boolean) {
             if (!value && this.filter !== ShadowGenerator.FILTER_BLURCLOSEEXPONENTIALSHADOWMAP) {
                 return;
@@ -221,14 +399,17 @@
 
         private _darkness = 0;
         /**
-         * Returns the darkness value (float).  
+         * Returns the darkness value (float). This can only decrease the actual darkness of a shadow.
+         * 0 means strongest and 1 would means no shadow.
+         * @returns the darkness.
          */
         public getDarkness(): number {
             return this._darkness;
         }
         /**
-         * Sets the ShadowGenerator darkness value (float <= 1.0).  
-         * Returns the ShadowGenerator.  
+         * Sets the darkness value (float). This can only decrease the actual darkness of a shadow.
+         * @param darkness The darkness value 0 means strongest and 1 would means no shadow.
+         * @returns the shadow generator allowing fluent coding.
          */
         public setDarkness(darkness: number): ShadowGenerator {
             if (darkness >= 1.0)
@@ -242,24 +423,27 @@
 
         private _transparencyShadow = false;
         /**
-         * Sets the ability to have transparent shadow (boolean).  
-         * Returns the ShadowGenerator.  
+         * Sets the ability to have transparent shadow (boolean).
+         * @param transparent True if transparent else False
+         * @returns the shadow generator allowing fluent coding
          */
-        public setTransparencyShadow(hasShadow: boolean): ShadowGenerator {
-            this._transparencyShadow = hasShadow;
+        public setTransparencyShadow(transparent: boolean): ShadowGenerator {
+            this._transparencyShadow = transparent;
             return this;
         }
 
         private _shadowMap: Nullable<RenderTargetTexture>;
         private _shadowMap2: Nullable<RenderTargetTexture>;
         /**
-         * Returns a RenderTargetTexture object : the shadow map texture.  
+         * Gets the main RTT containing the shadow map (usually storing depth from the light point of view).
+         * @returns The render target texture if present otherwise, null
          */
         public getShadowMap(): Nullable<RenderTargetTexture> {
             return this._shadowMap;
         }
         /**
-         * Returns the most ready computed shadow map as a RenderTargetTexture object.  
+         * Gets the RTT used during rendering (can be a blurred version of the shadow map or the shadow map itself).
+         * @returns The render target texture if the shadow map is present otherwise, null
          */
         public getShadowMapForRendering(): Nullable<RenderTargetTexture> {
             if (this._shadowMap2) {
@@ -270,9 +454,10 @@
         }
 
         /**
-         * Helper function to add a mesh and its descendants to the list of shadow casters
+         * Helper function to add a mesh and its descendants to the list of shadow casters.
          * @param mesh Mesh to add
          * @param includeDescendants boolean indicating if the descendants should be added. Default to true
+         * @returns the Shadow Generator itself
          */
         public addShadowCaster(mesh: AbstractMesh, includeDescendants = true): ShadowGenerator {
             if (!this._shadowMap) {
@@ -296,6 +481,7 @@
          * Helper function to remove a mesh and its descendants from the list of shadow casters
          * @param mesh Mesh to remove
          * @param includeDescendants boolean indicating if the descendants should be removed. Default to true
+         * @returns the Shadow Generator itself
          */
         public removeShadowCaster(mesh: AbstractMesh, includeDescendants = true): ShadowGenerator {
             if (!this._shadowMap || !this._shadowMap.renderList) {
@@ -318,19 +504,25 @@
         }
 
         /**
-		 * Controls the extent to which the shadows fade out at the edge of the frustum
+         * Controls the extent to which the shadows fade out at the edge of the frustum
          * Used only by directionals and spots
-		 */
+         */
         public frustumEdgeFalloff = 0;
 
         private _light: IShadowLight;
         /**
-         * Returns the associated light object.  
+         * Returns the associated light object.
+         * @returns the light generating the shadow
          */
         public getLight(): IShadowLight {
             return this._light;
         }
 
+        /**
+         * If true the shadow map is generated by rendering the back face of the mesh instead of the front face.
+         * This can help with self-shadowing as the geometry making up the back of objects is slightly offset.
+         * It might on the other hand introduce peter panning.
+         */
         public forceBackFacesOnly = false;
 
         private _scene: Scene;
@@ -356,14 +548,13 @@
         private _defaultTextureMatrix = Matrix.Identity();
 
         /**
-         * Creates a ShadowGenerator object.  
-         * A ShadowGenerator is the required tool to use the shadows.  
-         * Each light casting shadows needs to use its own ShadowGenerator.  
-         * Required parameters : 
-         * - `mapSize` (integer): the size of the texture what stores the shadows. Example : 1024.    
-         * - `light`: the light object generating the shadows.  
-         * - `useFullFloatFirst`: by default the generator will try to use half float textures but if you need precision (for self shadowing for instance), you can use this option to enforce full float texture.
+         * Creates a ShadowGenerator object.
+         * A ShadowGenerator is the required tool to use the shadows.
+         * Each light casting shadows needs to use its own ShadowGenerator.
          * Documentation : http://doc.babylonjs.com/tutorials/shadows  
+         * @param mapSize The size of the texture what stores the shadows. Example : 1024.
+         * @param light The light object generating the shadows.  
+         * @param useFullFloatFirst By default the generator will try to use half float textures but if you need precision (for self shadowing for instance), you can use this option to enforce full float texture.
          */
         constructor(mapSize: number, light: IShadowLight, useFullFloatFirst?: boolean) {
             this._mapSize = mapSize;
@@ -595,7 +786,9 @@
         }
 
         /**
-         * Force shader compilation including textures ready check
+         * Forces all the attached effect to compile to enable rendering only once ready vs. lazyly compiling effects.
+         * @param onCompiled Callback triggered at the and of the effects compilation
+         * @param options Sets of optional options forcing the compilation with different modes 
          */
         public forceCompilation(onCompiled?: (generator: ShadowGenerator) => void, options?: Partial<{ useInstances: boolean }>): void {
             let localOptions = {
@@ -653,7 +846,10 @@
         }
 
         /**
-         * Boolean : true when the ShadowGenerator is finally computed.  
+         * Determine wheter the shadow generator is ready or not (mainly all effects and related post processes needs to be ready).
+         * @param subMesh The submesh we want to render in the shadow map
+         * @param useInstances Defines wether will draw in the map using instances
+         * @returns true if ready otherwise, false
          */
         public isReady(subMesh: SubMesh, useInstances: boolean): boolean {
             var defines = [];
@@ -746,7 +942,9 @@
         }
 
         /**
-         * This creates the defines related to the standard BJS materials.
+         * Prepare all the defines in a material relying on a shadow map at the specified light index.
+         * @param defines Defines of the material we want to update
+         * @param lightIndex Index of the light in the enabled light list of the material
          */
         public prepareDefines(defines: any, lightIndex: number): void {
             var scene = this._scene;
@@ -774,8 +972,10 @@
         }
 
         /**
-         * This binds shadow lights related to the standard BJS materials.
-         * It implies the unifroms available on the materials are the standard BJS ones.
+         * Binds the shadow related information inside of an effect (information like near, far, darkness...
+         * defined in the generator but impacting the effect).
+         * @param lightIndex Index of the light in the enabled light list of the material owning the effect
+         * @param effect The effect we are binfing the information for 
          */
         public bindShadowLight(lightIndex: string, effect: Effect): void {
             var light = this._light;
@@ -804,9 +1004,10 @@
             light._uniformBuffer.updateFloat2("depthValues", this.getLight().getDepthMinZ(camera), this.getLight().getDepthMinZ(camera) + this.getLight().getDepthMaxZ(camera), lightIndex);
         }
 
-        // Methods
         /**
-         * Returns a Matrix object : the updated transformation matrix.  
+         * Gets the transformation matrix used to project the meshes into the map from the light point of view.
+         * (eq to shadow prjection matrix * light transform matrix)
+         * @returns The transform matrix used to create the shadow map
          */
         public getTransformMatrix(): Matrix {
             var scene = this._scene;
@@ -850,6 +1051,10 @@
             return this._transformMatrix;
         }
 
+        /**
+         * Recreates the shadow map dependencies like RTT and post processes. This can be used during the switch between
+         * Cube and 2D textures for instance.
+         */
         public recreateShadowMap(): void {
             let shadowMap = this._shadowMap;
             if (!shadowMap) {
@@ -915,8 +1120,10 @@
                 this._light._markMeshesAsLightDirty();
             }
         }
+
         /**
-         * Serializes the ShadowGenerator and returns a serializationObject.  
+         * Serializes the shadow generator setup to a json object.
+         * @returns The serialized JSON object 
          */
         public serialize(): any {
             var serializationObject: any = {};
@@ -953,8 +1160,12 @@
 
             return serializationObject;
         }
+
         /**
-         * Parses a serialized ShadowGenerator and returns a new ShadowGenerator.  
+         * Parses a serialized ShadowGenerator and returns a new ShadowGenerator.
+         * @param parsedShadowGenerator The JSON object to parse
+         * @param scene The scene to create the shadow map for
+         * @returns The parsed shadow generator
          */
         public static Parse(parsedShadowGenerator: any, scene: Scene): ShadowGenerator {
             //casting to point light, as light is missing the position attr and typescript complains.

src/Lights/babylon.directionalLight.ts

@@ -1,4 +1,10 @@
 module BABYLON {
+    /**
+     * A directional light is defined by a direction (what a surprise!). 
+     * The light is emitted from everywhere in the specified direction, and has an infinite range. 
+     * An example of a directional light is when a distance planet is lit by the apparently parallel lines of light from its sun. Light in a downward direction will light the top of an object.
+     * Documentation: https://doc.babylonjs.com/babylon101/lights
+     */
     export class DirectionalLight extends ShadowLight {
 
         private _shadowFrustumSize = 0;
@@ -18,15 +24,29 @@
         }
 
         private _shadowOrthoScale = 0.5;
+        /**
+         * Gets the shadow projection scale against the optimal computed one.
+         * 0.1 by default which means that the projection window is increase by 10% from the optimal size.
+         * This does not impact in fixed frustum size (shadowFrustumSize being set)
+         */
         @serialize()
         public get shadowOrthoScale(): number {
             return this._shadowOrthoScale
         }
+        /**
+         * Sets the shadow projection scale against the optimal computed one.
+         * 0.1 by default which means that the projection window is increase by 10% from the optimal size.
+         * This does not impact in fixed frustum size (shadowFrustumSize being set)
+         */
         public set shadowOrthoScale(value: number) {
             this._shadowOrthoScale = value;
             this.forceProjectionMatrixCompute();
         }
 
+        /**
+         * Automatically compute the projection matrix to best fit (including all the casters)
+         * on each frame.
+         */
         @serialize()
         public autoUpdateExtends = true;
 
@@ -39,8 +59,11 @@
         /**
          * Creates a DirectionalLight object in the scene, oriented towards the passed direction (Vector3).  
          * The directional light is emitted from everywhere in the given direction.  
-         * It can cast shawdows.  
-         * Documentation : http://doc.babylonjs.com/tutorials/lights  
+         * It can cast shawdows.
+         * Documentation : http://doc.babylonjs.com/tutorials/lights
+         * @param name The friendly name of the light
+         * @param direction The direction of the light
+         * @param scene The scene the light belongs to
          */
         constructor(name: string, direction: Vector3, scene: Scene) {
             super(name, scene);
@@ -49,7 +72,8 @@
         }
 
         /**
-         * Returns the string "DirectionalLight".  
+         * Returns the string "DirectionalLight".
+         * @return The class name
          */
         public getClassName(): string {
             return "DirectionalLight";
@@ -57,6 +81,7 @@
 
         /**
          * Returns the integer 1.
+         * @return The light Type id as a constant defines in Light.LIGHTTYPEID_x
          */
         public getTypeID(): number {
             return Light.LIGHTTYPEID_DIRECTIONALLIGHT;
@@ -155,7 +180,9 @@
 
         /**
          * Sets the passed Effect object with the DirectionalLight transformed position (or position if not parented) and the passed name.  
-         * Returns the DirectionalLight.  
+         * @param effect The effect to update
+         * @param lightIndex The index of the light in the effect to update
+         * @returns The directional light
          */
         public transferToEffect(effect: Effect, lightIndex: string): DirectionalLight {
             if (this.computeTransformedInformation()) {
@@ -171,7 +198,8 @@
          * 
          * Values are fixed on directional lights as it relies on an ortho projection hence the need to convert being
          * -1 and 1 to 0 and 1 doing (depth + min) / (min + max) -> (depth + 1) / (1 + 1) -> (depth * 0.5) + 0.5.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the min for
+         * @returns the depth min z
          */
         public getDepthMinZ(activeCamera: Camera): number {
             return 1;
@@ -182,7 +210,8 @@
          * 
          * Values are fixed on directional lights as it relies on an ortho projection hence the need to convert being
          * -1 and 1 to 0 and 1 doing (depth + min) / (min + max) -> (depth + 1) / (1 + 1) -> (depth * 0.5) + 0.5.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the max for
+         * @returns the depth max z
          */
         public getDepthMaxZ(activeCamera: Camera): number {
             return 1;

src/Lights/babylon.hemisphericLight.ts

@@ -1,8 +1,19 @@
 module BABYLON {
+    /**
+     * The HemisphericLight simulates the ambient environment light,
+     * so the passed direction is the light reflection direction, not the incoming direction.
+     */
     export class HemisphericLight extends Light {
+        /**
+         * The groundColor is the light in the opposite direction to the one specified during creation.
+         * You can think of the diffuse and specular light as coming from the centre of the object in the given direction and the groundColor light in the opposite direction.
+         */
         @serializeAsColor3()
         public groundColor = new Color3(0.0, 0.0, 0.0);
 
+        /**
+         * The light reflection direction, not the incoming direction.
+         */
         @serializeAsVector3()
         public direction: Vector3
 
@@ -12,7 +23,10 @@
          * Creates a HemisphericLight object in the scene according to the passed direction (Vector3).  
          * The HemisphericLight simulates the ambient environment light, so the passed direction is the light reflection direction, not the incoming direction.  
          * The HemisphericLight can't cast shadows.  
-         * Documentation : http://doc.babylonjs.com/tutorials/lights  
+         * Documentation : http://doc.babylonjs.com/tutorials/lights
+         * @param name The friendly name of the light
+         * @param direction The direction of the light reflection
+         * @param scene The scene the light belongs to
          */
         constructor(name: string, direction: Vector3, scene: Scene) {
             super(name, scene);
@@ -30,27 +44,37 @@
         }
 
         /**
-         * Returns the string "HemisphericLight".  
+         * Returns the string "HemisphericLight".
+         * @return The class name
          */
         public getClassName(): string {
             return "HemisphericLight";
-        }          
+        }
+
         /**
          * Sets the HemisphericLight direction towards the passed target (Vector3).  
-         * Returns the updated direction.  
+         * Returns the updated direction.
+         * @param target The target the direction should point to
+         * @return The computed direction
          */
         public setDirectionToTarget(target: Vector3): Vector3 {
             this.direction = Vector3.Normalize(target.subtract(Vector3.Zero()));
             return this.direction;
         }
 
+        /**
+         * Returns the shadow generator associated to the light.
+         * @returns Always null for hemispheric lights because it does not support shadows.
+         */
         public getShadowGenerator(): Nullable<ShadowGenerator> {
             return null;
         }
 
         /**
          * Sets the passed Effect object with the HemisphericLight normalized direction and color and the passed name (string).  
-         * Returns the HemisphericLight.  
+         * @param effect The effect to update
+         * @param lightIndex The index of the light in the effect to update
+         * @returns The hemispheric light
          */
         public transferToEffect(effect: Effect, lightIndex: string): HemisphericLight {
             var normalizeDirection = Vector3.Normalize(this.direction);
@@ -64,14 +88,19 @@
             return this;
         }
 
+        /**
+         * @ignore internal use only.
+         */
         public _getWorldMatrix(): Matrix {
             if (!this._worldMatrix) {
                 this._worldMatrix = Matrix.Identity();
             }
             return this._worldMatrix;
         }
+
         /**
-         * Returns the integer 3.  
+         * Returns the integer 3.
+         * @return The light Type id as a constant defines in Light.LIGHTTYPEID_x
          */
         public getTypeID(): number {
             return Light.LIGHTTYPEID_HEMISPHERICLIGHT;

src/Lights/babylon.light.ts

@@ -1,5 +1,10 @@
-module BABYLON {
-    export class Light extends Node {
+module BABYLON {
+    /**
+     * Base class of all the lights in Babylon. It groups all the generic information about lights.
+     * Lights are used, as you would expect, to affect how meshes are seen, in terms of both illumination and colour. 
+     * All meshes allow light to pass through them unless shadow generation is activated. The default number of lights allowed is four but this can be increased.
+     */
+    export abstract class Light extends Node {
 
         //lightmapMode Consts
         private static _LIGHTMAP_DEFAULT = 0;
@@ -112,15 +117,31 @@
             return Light._LIGHTTYPEID_HEMISPHERICLIGHT;
         }
 
+        /**
+         * Diffuse gives the basic color to an object.
+         */
         @serializeAsColor3()
         public diffuse = new Color3(1.0, 1.0, 1.0);
 
+        /**
+         * Specular produces a highlight color on an object.
+         * Note: This is note affecting PBR materials.
+         */
         @serializeAsColor3()
         public specular = new Color3(1.0, 1.0, 1.0);
 
+        /**
+         * Strength of the light.
+         * Note: By default it is define in the framework own unit.
+         * Note: In PBR materials the intensityMode can be use to chose what unit the intensity is defined in.
+         */
         @serialize()
         public intensity = 1.0;
 
+        /**
+         * Defines how far from the source the light is impacting in scene units.
+         * Note: Unused in PBR material as the distance light falloff is defined following the inverse squared falloff.
+         */
         @serialize()
         public range = Number.MAX_VALUE;
 
@@ -164,12 +185,13 @@
             this._computePhotometricScale();
         };
 
+        
+        @serialize()
+        private _renderPriority: number;
         /**
          * Defines the rendering priority of the lights. It can help in case of fallback or number of lights
          * exceeding the number allowed of the materials.
          */
-        @serialize()
-        private _renderPriority: number;
         @expandToProperty("_reorderLightsInScene")
         public renderPriority: number = 0;
 
@@ -181,19 +203,30 @@
         public shadowEnabled: boolean = true;
 
         private _includedOnlyMeshes: AbstractMesh[];
+        /**
+         * Gets the only meshes impacted by this light.
+         */
         public get includedOnlyMeshes(): AbstractMesh[] {
             return this._includedOnlyMeshes;
         }
-
+        /**
+         * Sets the only meshes impacted by this light.
+         */
         public set includedOnlyMeshes(value: AbstractMesh[]) {
             this._includedOnlyMeshes = value;
             this._hookArrayForIncludedOnly(value);
         }
 
         private _excludedMeshes: AbstractMesh[];
+        /**
+         * Gets the meshes not impacted by this light.
+         */
         public get excludedMeshes(): AbstractMesh[] {
             return this._excludedMeshes;
         }
+        /**
+         * Sets the meshes not impacted by this light.
+         */
         public set excludedMeshes(value: AbstractMesh[]) {
             this._excludedMeshes = value;
             this._hookArrayForExcluded(value);
@@ -201,10 +234,17 @@
 
         @serialize("excludeWithLayerMask")
         private _excludeWithLayerMask = 0;
+        /**
+         * Gets the layer id use to find what meshes are not impacted by the light.
+         * Inactive if 0
+         */
         public get excludeWithLayerMask(): number {
             return this._excludeWithLayerMask;
         }
-
+        /**
+         * Sets the layer id use to find what meshes are not impacted by the light.
+         * Inactive if 0
+         */
         public set excludeWithLayerMask(value: number) {
             this._excludeWithLayerMask = value;
             this._resyncMeshes();
@@ -212,10 +252,17 @@
 
         @serialize("includeOnlyWithLayerMask")
         private _includeOnlyWithLayerMask = 0;
+        /**
+         * Gets the layer id use to find what meshes are impacted by the light.
+         * Inactive if 0
+         */
         public get includeOnlyWithLayerMask(): number {
             return this._includeOnlyWithLayerMask;
         }
-
+        /**
+         * Sets the layer id use to find what meshes are impacted by the light.
+         * Inactive if 0
+         */
         public set includeOnlyWithLayerMask(value: number) {
             this._includeOnlyWithLayerMask = value;
             this._resyncMeshes();
@@ -223,10 +270,15 @@
 
         @serialize("lightmapMode")
         private _lightmapMode = 0;
+        /**
+         * Gets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)
+         */
         public get lightmapMode(): number {
             return this._lightmapMode;
         }
-
+        /**
+         * Sets the lightmap mode of this light (should be one of the constants defined by Light.LIGHTMAP_x)
+         */
         public set lightmapMode(value: number) {
             if (this._lightmapMode === value) {
                 return;
@@ -237,16 +289,34 @@
         }
 
         private _parentedWorldMatrix: Matrix;
+
+        /**
+         * Shadow generator associted to the light.
+         * Internal use only.
+         */
         public _shadowGenerator: Nullable<IShadowGenerator>;
+
+        /**
+         * @ignore Internal use only.
+         */
         public _excludedMeshesIds = new Array<string>();
+
+        /**
+         * @ignore Internal use only.
+         */
         public _includedOnlyMeshesIds = new Array<string>();
 
-        // Light uniform buffer
+        /**
+         * The current light unifom buffer.
+         * @ignore Internal use only.
+         */
         public _uniformBuffer: UniformBuffer;
 
         /**
          * Creates a Light object in the scene.  
          * Documentation : http://doc.babylonjs.com/tutorials/lights  
+         * @param name The firendly name of the light
+         * @param scene The scene the light belongs too 
          */
         constructor(name: string, scene: Scene) {
             super(name, scene);
@@ -260,19 +330,33 @@
             this._resyncMeshes();
         }
 
-        protected _buildUniformLayout(): void {
-            // Overridden
-        }
+        protected abstract _buildUniformLayout(): void;
+
+        /**
+         * Sets the passed Effect "effect" with the Light information.
+         * @param effect The effect to update
+         * @param lightIndex The index of the light in the effect to update
+         * @returns The light
+         */
+        public abstract transferToEffect(effect: Effect, lightIndex: string): Light;
 
         /**
-         * Returns the string "Light".  
+         * @ignore internal use only.
+         */
+        public abstract _getWorldMatrix(): Matrix;
+
+        /**
+         * Returns the string "Light".
+         * @returns the class name
          */
         public getClassName(): string {
             return "Light";
         }
 
         /**
-         * @param {boolean} fullDetails - support for multiple levels of logging within scene loading
+         * Converts the light information to a readable string for debug purpose.
+         * @param fullDetails Supports for multiple levels of logging within scene loading
+         * @returns the human readable light info
          */
         public toString(fullDetails?: boolean): string {
             var ret = "Name: " + this.name;
@@ -287,10 +371,9 @@
             return ret;
         }
 
-
         /**
          * Set the enabled state of this node.
-         * @param {boolean} value - the new enabled state
+         * @param value - the new enabled state
          * @see isEnabled
          */
         public setEnabled(value: boolean): void {
@@ -300,7 +383,8 @@
         }
 
         /**
-         * Returns the Light associated shadow generator.  
+         * Returns the Light associated shadow generator if any.
+         * @return the associated shadow generator.
          */
         public getShadowGenerator(): Nullable<IShadowGenerator> {
             return this._shadowGenerator;
@@ -308,20 +392,16 @@
 
         /**
          * Returns a Vector3, the absolute light position in the World.  
+         * @returns the world space position of the light
          */
         public getAbsolutePosition(): Vector3 {
             return Vector3.Zero();
         }
 
-        public transferToEffect(effect: Effect, lightIndex: string): void {
-        }
-
-        public _getWorldMatrix(): Matrix {
-            return Matrix.Identity();
-        }
-
         /**
-         * Boolean : True if the light will affect the passed mesh.  
+         * Specifies if the light will affect the passed mesh.
+         * @param mesh The mesh to test against the light
+         * @return true the mesh is affected otherwise, false.
          */
         public canAffectMesh(mesh: AbstractMesh): boolean {
             if (!mesh) {
@@ -348,7 +428,8 @@
         }
 
         /**
-         * Returns the light World matrix.  
+         * Computes and Returns the light World matrix.
+         * @returns the world matrix 
          */
         public getWorldMatrix(): Matrix {
             this._currentRenderId = this.getScene().getRenderId();
@@ -376,7 +457,7 @@
 		 * @param b Second Light object to compare first.
 		 * @return -1 to reduce's a's index relative to be, 0 for no change, 1 to increase a's index relative to b.
 		 */
-        public static compareLightsPriority(a: Light, b: Light): number {
+        public static CompareLightsPriority(a: Light, b: Light): number {
             //shadow-casting lights have priority over non-shadow-casting lights
             //the renderPrioirty is a secondary sort criterion
             if (a.shadowEnabled !== b.shadowEnabled) {
@@ -397,6 +478,11 @@
             // Animations
             this.getScene().stopAnimation(this);
 
+            // Remove from meshes
+            for (var mesh of this.getScene().meshes) {
+                mesh._removeLightSource(this);
+            }
+
             this._uniformBuffer.dispose();
 
             // Remove from scene
@@ -405,7 +491,8 @@
         }
 
         /**
-         * Returns the light type ID (integer).  
+         * Returns the light type ID (integer).
+         * @returns The light Type id as a constant defines in Light.LIGHTTYPEID_x
          */
         public getTypeID(): number {
             return 0;
@@ -413,13 +500,16 @@
 
         /**
          * Returns the intensity scaled by the Photometric Scale according to the light type and intensity mode.
+         * @returns the scaled intensity in intensity mode unit
          */
         public getScaledIntensity() {
             return this._photometricScale * this.intensity;
         }
 
         /**
-         * Returns a new Light object, named "name", from the current one.  
+         * Returns a new Light object, named "name", from the current one.
+         * @param name The name of the cloned light
+         * @returns the new created light
          */
         public clone(name: string): Nullable<Light> {
             let constructor = Light.GetConstructorFromName(this.getTypeID(), name, this.getScene());
@@ -429,9 +519,10 @@
             }
             return SerializationHelper.Clone(constructor, this);
         }
+
         /**
          * Serializes the current light into a Serialization object.  
-         * Returns the serialized object.  
+         * @returns the serialized object.
          */
         public serialize(): any {
             var serializationObject = SerializationHelper.Serialize(this);
@@ -468,9 +559,13 @@
 
         /**
          * Creates a new typed light from the passed type (integer) : point light = 0, directional light = 1, spot light = 2, hemispheric light = 3.  
-         * This new light is named "name" and added to the passed scene.  
+         * This new light is named "name" and added to the passed scene.
+         * @param type Type according to the types available in Light.LIGHTTYPEID_x
+         * @param name The friendly name of the light
+         * @param scene The scene the new light will belong to
+         * @returns the constructor function
          */
-        static GetConstructorFromName(type: number, name: string, scene: Scene): Nullable<() => Light> {
+        public static GetConstructorFromName(type: number, name: string, scene: Scene): Nullable<() => Light> {
             switch (type) {
                 case 0:
                     return () => new PointLight(name, Vector3.Zero(), scene);
@@ -486,7 +581,10 @@
         }
 
         /**
-         * Parses the passed "parsedLight" and returns a new instanced Light from this parsing.  
+         * Parses the passed "parsedLight" and returns a new instanced Light from this parsing.
+         * @param parsedLight The JSON representation of the light
+         * @param scene The scene to create the parsed light in
+         * @returns the created light after parsing
          */
         public static Parse(parsedLight: any, scene: Scene): Nullable<Light> {
             let constructor = Light.GetConstructorFromName(parsedLight.type, parsedLight.name, scene);
@@ -584,6 +682,10 @@
             }
         }
 
+        /**
+         * Forces the meshes to update their light related information in their rendering used effects
+         * @ignore Internal Use Only
+         */
         public _markMeshesAsLightDirty() {
             for (var mesh of this.getScene().meshes) {
                 if (mesh._lightSources.indexOf(this) !== -1) {
@@ -659,6 +761,10 @@
             return photometricScale;
         }
 
+        /**
+         * Reorder the light in the scene according to their defined priority.
+         * @ignore Internal Use Only
+         */
         public _reorderLightsInScene(): void {
             var scene = this.getScene();
             if (this._renderPriority != 0) {

src/Lights/babylon.pointLight.ts

@@ -1,4 +1,10 @@
 module BABYLON {
+    /**
+     * A point light is a light defined by an unique point in world space. 
+     * The light is emitted in every direction from this point.
+     * A good example of a point light is a standard light bulb.
+     * Documentation: https://doc.babylonjs.com/babylon101/lights
+     */
     export class PointLight extends ShadowLight {
 
         private _shadowAngle = Math.PI / 2;
@@ -23,6 +29,10 @@
             this.forceProjectionMatrixCompute();
         }
 
+        /**
+         * Gets the direction if it has been set.
+         * In case of direction provided, the shadow will not use a cube texture but simulate a spot shadow as a fallback
+         */
         public get direction(): Vector3 {
             return this._direction;
         }
@@ -47,6 +57,9 @@
          * var pointLight = new BABYLON.PointLight("pl", camera.position, scene);
          * ```
          * Documentation : http://doc.babylonjs.com/tutorials/lights  
+         * @param name The light friendly name
+         * @param position The position of the point light in the scene
+         * @param scene The scene the lights belongs to
          */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, scene);
@@ -55,13 +68,15 @@
 
         /**
          * Returns the string "PointLight"
+         * @returns the class name
          */
         public getClassName(): string {
             return "PointLight";
         }
         
         /**
-         * Returns the integer 0.  
+         * Returns the integer 0.
+         * @returns The light Type id as a constant defines in Light.LIGHTTYPEID_x
          */
         public getTypeID(): number {
             return Light.LIGHTTYPEID_POINTLIGHT;
@@ -69,13 +84,16 @@
 
         /**
          * Specifies wether or not the shadowmap should be a cube texture.
+         * @returns true if the shadowmap needs to be a cube texture.
          */
         public needCube(): boolean {
             return !this.direction;
         }
 
         /**
-         * Returns a new Vector3 aligned with the PointLight cube system according to the passed cube face index (integer).  
+         * Returns a new Vector3 aligned with the PointLight cube system according to the passed cube face index (integer).
+         * @param faceIndex The index of the face we are computed the direction to generate shadow
+         * @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
          */
         public getShadowDirection(faceIndex?: number): Vector3 {
             if (this.direction) {
@@ -130,7 +148,9 @@
 
         /**
          * Sets the passed Effect "effect" with the PointLight transformed position (or position, if none) and passed name (string).  
-         * Returns the PointLight.  
+         * @param effect The effect to update
+         * @param lightIndex The index of the light in the effect to update
+         * @returns The point light
          */
         public transferToEffect(effect: Effect, lightIndex: string): PointLight {
             if (this.computeTransformedInformation()) {

src/Lights/babylon.shadowLight.ts

@@ -1,87 +1,198 @@
 module BABYLON {
+    /**
+     * Interface describing all the common properties and methods a shadow light needs to implement.
+     * This helps both the shadow generator and materials to genrate the corresponding shadow maps
+     * as well as binding the different shadow properties to the effects.
+     */
     export interface IShadowLight extends Light {
+        /**
+         * The light id in the scene (used in scene.findLighById for instance)
+         */
         id: string;
+        /**
+         * The position the shdow will be casted from.
+         */
         position: Vector3;
+        /**
+         * In 2d mode (needCube being false), the direction used to cast the shadow.
+         */
         direction: Vector3;
+        /**
+         * The transformed position. Position of the light in world space taking parenting in account.
+         */
         transformedPosition: Vector3;
+        /**
+         * The transformed direction. Direction of the light in world space taking parenting in account.
+         */
         transformedDirection: Vector3;
+        /**
+         * The friendly name of the light in the scene.
+         */
         name: string;
+        /**
+         * Defines the shadow projection clipping minimum z value.
+         */
         shadowMinZ: number;
+        /**
+         * Defines the shadow projection clipping maximum z value.
+         */
         shadowMaxZ: number;
 
+        /**
+         * Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
+         * @returns true if the information has been computed, false if it does not need to (no parenting)
+         */
         computeTransformedInformation(): boolean;
+
+        /**
+         * Gets the scene the light belongs to.
+         * @returns The scene
+         */
         getScene(): Scene;
 
+        /**
+         * Callback defining a custom Projection Matrix Builder.
+         * This can be used to override the default projection matrix computation.
+         */
         customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
+
+        /**
+         * Sets the shadow projection matrix in parameter to the generated projection matrix.
+         * @param matrix The materix to updated with the projection information
+         * @param viewMatrix The transform matrix of the light
+         * @param renderList The list of mesh to render in the map
+         * @returns The current light
+         */
         setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight;
+
+        /**
+         * Gets the current depth scale used in ESM.
+         * @returns The scale
+         */
         getDepthScale(): number;
 
+        /**
+         * Returns whether or not the shadow generation require a cube texture or a 2d texture.
+         * @returns true if a cube texture needs to be use
+         */
         needCube(): boolean;
+
+        /**
+         * Detects if the projection matrix requires to be recomputed this frame.
+         * @returns true if it requires to be recomputed otherwise, false.
+         */
         needProjectionMatrixCompute(): boolean;
+
+        /**
+         * Forces the shadow generator to recompute the projection matrix even if position and direction did not changed.
+         */
         forceProjectionMatrixCompute(): void;
 
+        /**
+         * Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
+         * @param faceIndex The index of the face we are computed the direction to generate shadow
+         * @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
+         */
         getShadowDirection(faceIndex?: number): Vector3;
 
         /**
          * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the min for
+         * @returns the depth min z
          */
         getDepthMinZ(activeCamera: Camera): number;
 
         /**
-         * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * Gets the maxZ used for shadow according to both the scene and the light.
+         * @param activeCamera The camera we are returning the max for
+         * @returns the depth max z
          */
         getDepthMaxZ(activeCamera: Camera): number;
     }
 
+    /**
+     * Base implementation of @see IShadowLight
+     * It groups all the common behaviour in order to reduce dupplication and better follow the DRY pattern.
+     */
     export abstract class ShadowLight extends Light implements IShadowLight {
 
         protected abstract _setDefaultShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): void;
 
+        /**
+         * The position the shdow will be casted from.
+         */
         @serializeAsVector3()
         public position: Vector3;
 
         protected _direction: Vector3;
         @serializeAsVector3()
+        /**
+         * In 2d mode (needCube being false), gets the direction used to cast the shadow.
+         */
         public get direction(): Vector3 {
             return this._direction;
         }
+        /**
+         * In 2d mode (needCube being false), sets the direction used to cast the shadow.
+         */
         public set direction(value: Vector3) {
             this._direction = value;
         }
 
         private _shadowMinZ: number;
+        /**
+         * Gets the shadow projection clipping minimum z value.
+         */
         @serialize()
         public get shadowMinZ(): number {
             return this._shadowMinZ
         }
+        /**
+         * Sets the shadow projection clipping minimum z value.
+         */
         public set shadowMinZ(value: number) {
             this._shadowMinZ = value;
             this.forceProjectionMatrixCompute();
         }
 
         private _shadowMaxZ: number;
+        /**
+         * Sets the shadow projection clipping maximum z value.
+         */
         @serialize()
         public get shadowMaxZ(): number {
             return this._shadowMaxZ
         }
+        /**
+         * Gets the shadow projection clipping maximum z value.
+         */
         public set shadowMaxZ(value: number) {
             this._shadowMaxZ = value;
             this.forceProjectionMatrixCompute();
         }
 
+        /**
+         * Callback defining a custom Projection Matrix Builder.
+         * This can be used to override the default projection matrix computation.
+         */
         public customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
 
+        /**
+         * The transformed position. Position of the light in world space taking parenting in account.
+         */
         public transformedPosition: Vector3;
 
+        /**
+         * The transformed direction. Direction of the light in world space taking parenting in account.
+         */
         public transformedDirection: Vector3;
 
         private _worldMatrix: Matrix;
         private _needProjectionMatrixCompute: boolean = true;
 
         /**
-         * Computes the light transformed position/direction in case the light is parented. Returns true if parented, else false.
+         * Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
+         * @returns true if the information has been computed, false if it does not need to (no parenting)
          */
         public computeTransformedInformation(): boolean {
             if (this.parent && this.parent.getWorldMatrix) {
@@ -104,13 +215,16 @@
 
         /**
          * Return the depth scale used for the shadow map.
+         * @returns the depth scale.
          */
         public getDepthScale(): number {
             return 50.0;
         }
 
         /**
-         * Returns the light direction (Vector3) for any passed face index.
+         * Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
+         * @param faceIndex The index of the face we are computed the direction to generate shadow
+         * @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
          */
         public getShadowDirection(faceIndex?: number): Vector3 {
             return this.transformedDirection ? this.transformedDirection : this.direction;
@@ -118,14 +232,16 @@
 
         /**
          * Returns the ShadowLight absolute position in the World.
+         * @returns the position vector in world space
          */
         public getAbsolutePosition(): Vector3 {
             return this.transformedPosition ? this.transformedPosition : this.position;
         }
 
         /**
-         * Sets the ShadowLight direction toward the passed target (Vector3).
-         * Returns the updated ShadowLight direction (Vector3).
+         * Sets the ShadowLight direction toward the passed target.
+         * @param target The point tot target in local space
+         * @returns the updated ShadowLight direction
          */
         public setDirectionToTarget(target: Vector3): Vector3 {
             this.direction = Vector3.Normalize(target.subtract(this.position));
@@ -133,7 +249,8 @@
         }
 
         /**
-         * Returns the light rotation (Vector3).
+         * Returns the light rotation in euler definition.
+         * @returns the x y z rotation in local space.
          */
         public getRotation(): Vector3 {
             this.direction.normalize();
@@ -143,14 +260,16 @@
         }
 
         /**
-         * Boolean : false by default.
+         * Returns whether or not the shadow generation require a cube texture or a 2d texture.
+         * @returns true if a cube texture needs to be use
          */
         public needCube(): boolean {
             return false;
         }
 
         /**
-         * Specifies wether or not the projection matrix should be recomputed this frame.
+         * Detects if the projection matrix requires to be recomputed this frame.
+         * @returns true if it requires to be recomputed otherwise, false.
          */
         public needProjectionMatrixCompute(): boolean {
             return this._needProjectionMatrixCompute;
@@ -165,6 +284,7 @@
 
         /**
          * Get the world matrix of the sahdow lights.
+         * @ignore Internal Use Only
          */
         public _getWorldMatrix(): Matrix {
             if (!this._worldMatrix) {
@@ -178,7 +298,8 @@
 
         /**
          * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the min for
+         * @returns the depth min z
          */
         public getDepthMinZ(activeCamera: Camera): number {
             return this.shadowMinZ !== undefined ? this.shadowMinZ : activeCamera.minZ;
@@ -186,15 +307,19 @@
 
         /**
          * Gets the maxZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the max for
+         * @returns the depth max z
          */
         public getDepthMaxZ(activeCamera: Camera): number {
             return this.shadowMaxZ !== undefined ? this.shadowMaxZ : activeCamera.maxZ;
         }
 
         /**
-         * Sets the projection matrix according to the type of light and custom projection matrix definition.
-         * Returns the light.
+         * Sets the shadow projection matrix in parameter to the generated projection matrix.
+         * @param matrix The materix to updated with the projection information
+         * @param viewMatrix The transform matrix of the light
+         * @param renderList The list of mesh to render in the map
+         * @returns The current light
          */
         public setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight {
             if (this.customProjectionMatrixBuilder) {

src/Lights/babylon.spotLight.ts

@@ -1,10 +1,41 @@
 module BABYLON {
+    /**
+     * A spot light is defined by a position, a direction, an angle, and an exponent. 
+     * These values define a cone of light starting from the position, emitting toward the direction.
+     * The angle, in radians, defines the size (field of illumination) of the spotlight's conical beam, 
+     * and the exponent defines the speed of the decay of the light with distance (reach).
+     * Documentation: https://doc.babylonjs.com/babylon101/lights
+     */
     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.
+        */
+
         private _angle: number;
         @serialize()
+        /**
+         * Gets the cone angle of the spot light in Radians.
+         */
         public get angle(): number {
             return this._angle
         }
+        /**
+         * Sets the cone angle of the spot light in Radians.
+         */
         public set angle(value: number) {
             this._angle = value;
             this.forceProjectionMatrixCompute();
@@ -26,18 +57,86 @@
             this.forceProjectionMatrixCompute();
         }
 
+        /**
+         * The light decay speed with the distance from the emission spot.
+         */
         @serialize()
         public exponent: number;
-        
+
+        private _textureProjectionMatrix = Matrix.Zero();
+        @serialize()
+        /**
+        * Allows reading the projecton texture
+        */
+        public get textureMatrix(): Matrix{
+            return this._textureProjectionMatrix;
+        }
         /**
-         * Creates a SpotLight object in the scene with the passed parameters :   
-         * - `position` (Vector3) is the initial SpotLight position,  
-         * - `direction` (Vector3) is the initial SpotLight direction,  
-         * - `angle` (float, in radians) is the spot light cone angle,
-         * - `exponent` (float) is the light decay speed with the distance from the emission spot.  
-         * A spot light is a simply light oriented cone.   
-         * It can cast shadows.  
-         * Documentation : http://doc.babylonjs.com/tutorials/lights  
+        * Allows setting the value of projection texture
+        */
+        public set textureMatrix(value: Matrix) {
+            this._textureProjectionMatrix = value;
+        }
+
+        protected _light_near :number;
+        @serialize()
+        /**
+         * Gets the near clip of the Spotlight for texture projection.
+         */
+        public get light_near(): number {
+            return this._light_near;
+        }
+        /**
+         * Sets the near clip of the Spotlight for texture projection.
+         */
+        public set light_near(value: number) {
+            this._light_near = value;
+            this._computeTextureMatrix();
+        }
+
+        protected _light_far  :number;
+        /**
+         * Gets the far clip of the Spotlight for texture projection.
+         */
+        @serialize()
+        public get light_far(): number {
+            return this._light_far;
+        }
+        /**
+         * Sets the far clip of the Spotlight for texture projection.
+         */
+        public set light_far(value: number) {
+            this._light_far = value;
+        }
+
+        @serializeAsTexture("projectedLightTexture")
+        private _projectedLightTexture: Nullable<BaseTexture>;;
+        /** 
+         * Gets the projection texture of the light.
+        */
+        public get projectedLightTexture(): Nullable<BaseTexture> {
+            return this._projectedLightTexture;
+        }
+        /**
+        * Sets 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();
+        }
+
+        /**
+         * Creates a SpotLight object in the scene. A spot light is a simply light oriented cone.
+         * It can cast shadows.
+         * Documentation : http://doc.babylonjs.com/tutorials/lights
+         * @param name The light friendly name
+         * @param position The position of the spot light in the scene
+         * @param direction The direction of the light in the scene
+         * @param angle The cone angle of the light in Radians
+         * @param exponent The light decay speed with the distance from the emission spot
+         * @param scene The scene the lights belongs to
          */
         constructor(name: string, position: Vector3, direction: Vector3, angle: number, exponent: number, scene: Scene) {
             super(name, scene);
@@ -50,6 +149,7 @@
 
         /**
          * Returns the string "SpotLight".
+         * @returns the class name
          */
         public getClassName(): string {
             return "SpotLight";
@@ -57,6 +157,7 @@
 
         /**
          * Returns the integer 2.
+         * @returns The light Type id as a constant defines in Light.LIGHTTYPEID_x
          */
         public getTypeID(): number {
             return Light.LIGHTTYPEID_SPOTLIGHT;
@@ -80,6 +181,39 @@
             this.getDepthMinZ(activeCamera), this.getDepthMaxZ(activeCamera), matrix);
         }
 
+        /**
+         * 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);
+        }
+
         protected _buildUniformLayout(): void {
             this._uniformBuffer.addUniform("vLightData", 4);
             this._uniformBuffer.addUniform("vLightDiffuse", 4);
@@ -92,7 +226,9 @@
 
         /**
          * Sets the passed Effect object with the SpotLight transfomed position (or position if not parented) and normalized direction.  
-         * Return the SpotLight.   
+         * @param effect The effect to update
+         * @param lightIndex The index of the light in the effect to update
+         * @returns The spot light
          */
         public transferToEffect(effect: Effect, lightIndex: string): SpotLight {
             var normalizeDirection;
@@ -123,7 +259,22 @@
                 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;
         }
+
+        /**
+         * Disposes the light and the associated resources.
+         */
+        public dispose() : void {
+            super.dispose();
+            if (this._projectedLightTexture){
+                this._projectedLightTexture.dispose();
+            }
+        }
     }
 }

src/Materials/Background/babylon.backgroundMaterial.ts

@@ -1,6 +1,7 @@
 module BABYLON {
     /**
      * Background material defines definition.
+     * @ignore Mainly internal Use
      */
     class BackgroundMaterialDefines extends MaterialDefines implements IImageProcessingConfigurationDefines {
         /**
@@ -126,172 +127,172 @@
         /**
          * Standard reflectance value at parallel view angle.
          */
-        public static standardReflectance0 = 0.05;
+        public static StandardReflectance0 = 0.05;
 
         /**
          * Standard reflectance value at grazing angle.
          */
-        public static standardReflectance90 = 0.5;
+        public static StandardReflectance90 = 0.5;
 
+        @serializeAsColor3()
+        protected _primaryColor: Color3;
         /**
          * Key light Color (multiply against the R channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _primaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public primaryColor = Color3.White();
 
+        @serialize()
+        protected _primaryLevel: float;
         /**
          * Key light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _primaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public primaryLevel: float = 1;
+        @serializeAsColor3()
+        protected _secondaryColor: Color3;
         /**
          * Secondary light Color (multiply against the G channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _secondaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public secondaryColor = Color3.Gray();
 
+        @serialize()
+        protected _secondaryLevel: float;
         /**
          * Secondary light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _secondaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public secondaryLevel: float = 1;
 
+        @serializeAsColor3()
+        protected _tertiaryColor: Color3;
         /**
          * Tertiary light Color (multiply against the B channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _tertiaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public tertiaryColor = Color3.Black();
 
+        @serialize()
+        protected _tertiaryLevel: float;
         /**
          * Tertiary light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _tertiaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public tertiaryLevel: float = 1;
 
+        @serializeAsTexture()
+        protected _reflectionTexture: Nullable<BaseTexture>;
         /**
          * Reflection Texture used in the material.
          * Should be author in a specific way for the best result (refer to the documentation).
          */
-        @serializeAsTexture()
-        protected _reflectionTexture: Nullable<BaseTexture>;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionTexture: Nullable<BaseTexture> = null;
 
+        @serialize()
+        protected _reflectionBlur: float;
         /**
          * Reflection Texture level of blur.
          * 
          * Can be use to reuse an existing HDR Texture and target a specific LOD to prevent authoring the 
          * texture twice.
          */
-        @serialize()
-        protected _reflectionBlur: float;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionBlur: float = 0;
 
+        @serializeAsTexture()
+        protected _diffuseTexture: Nullable<BaseTexture>;
         /**
          * Diffuse Texture used in the material.
          * Should be author in a specific way for the best result (refer to the documentation).
          */
-        @serializeAsTexture()
-        protected _diffuseTexture: Nullable<BaseTexture>;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public diffuseTexture: Nullable<BaseTexture> = null;
 
+        protected _shadowLights: Nullable<IShadowLight[]> = null;
         /**
          * Specify the list of lights casting shadow on the material.
          * All scene shadow lights will be included if null.
          */
-        protected _shadowLights: Nullable<IShadowLight[]> = null;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowLights: Nullable<IShadowLight[]> = null;
 
+        @serialize()
+        protected _shadowBlurScale: int;
         /**
          * For the lights having a blurred shadow generator, this can add a second blur pass in order to reach
          * soft lighting on the background.
          */
-        @serialize()
-        protected _shadowBlurScale: int;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowBlurScale: int = 1;
 
+        @serialize()
+        protected _shadowLevel: float;
         /**
          * Helps adjusting the shadow to a softer level if required.
          * 0 means black shadows and 1 means no shadows.
          */
-        @serialize()
-        protected _shadowLevel: float;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowLevel: float = 0;
 
+        @serializeAsVector3()
+        protected _sceneCenter: Vector3;
         /**
          * In case of opacity Fresnel or reflection falloff, this is use as a scene center.
          * It is usually zero but might be interesting to modify according to your setup.
          */
-        @serializeAsVector3()
-        protected _sceneCenter: Vector3;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public sceneCenter: Vector3 = Vector3.Zero();
 
+        @serialize()
+        protected _opacityFresnel: boolean;
         /**
          * This helps specifying that the material is falling off to the sky box at grazing angle.
          * This helps ensuring a nice transition when the camera goes under the ground.
          */
-        @serialize()
-        protected _opacityFresnel: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public opacityFresnel: boolean = true;
 
+        @serialize()
+        protected _reflectionFresnel: boolean;
         /**
          * This helps specifying that the material is falling off from diffuse to the reflection texture at grazing angle. 
          * This helps adding a mirror texture on the ground.
          */
-        @serialize()
-        protected _reflectionFresnel: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionFresnel: boolean = false;
 
+        @serialize()
+        protected _reflectionFalloffDistance: number;
         /**
          * This helps specifying the falloff radius off the reflection texture from the sceneCenter.
          * This helps adding a nice falloff effect to the reflection if used as a mirror for instance.
          */
-        @serialize()
-        protected _reflectionFalloffDistance: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionFalloffDistance: number = 0.0;
 
+        @serialize()
+        protected _reflectionAmount: number;
         /**
          * This specifies the weight of the reflection against the background in case of reflection Fresnel.
          */
-        @serialize()
-        protected _reflectionAmount: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionAmount: number = 1.0;
 
+        @serialize()
+        protected _reflectionReflectance0: number;
         /**
          * This specifies the weight of the reflection at grazing angle.
          */
-        @serialize()
-        protected _reflectionReflectance0: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionReflectance0: number = 0.05;
 
+        @serialize()
+        protected _reflectionReflectance90: number;
         /**
          * This specifies the weight of the reflection at a perpendicular point of view.
          */
-        @serialize()
-        protected _reflectionReflectance90: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionReflectance90: number = 0.5;
 
@@ -304,37 +305,36 @@
 
             if (reflectionWeight < 0.5) {
                 reflectionWeight = reflectionWeight * 2.0;
-                this.reflectionReflectance0 = BackgroundMaterial.standardReflectance0 * reflectionWeight;
-                this.reflectionReflectance90 = BackgroundMaterial.standardReflectance90 * reflectionWeight;
+                this.reflectionReflectance0 = BackgroundMaterial.StandardReflectance0 * reflectionWeight;
+                this.reflectionReflectance90 = BackgroundMaterial.StandardReflectance90 * reflectionWeight;
             } else {
                 reflectionWeight = reflectionWeight * 2.0 - 1.0;
-                this.reflectionReflectance0 = BackgroundMaterial.standardReflectance0 + (1.0 - BackgroundMaterial.standardReflectance0) * reflectionWeight;
-                this.reflectionReflectance90 = BackgroundMaterial.standardReflectance90 + (1.0 - BackgroundMaterial.standardReflectance90) * reflectionWeight;
+                this.reflectionReflectance0 = BackgroundMaterial.StandardReflectance0 + (1.0 - BackgroundMaterial.StandardReflectance0) * reflectionWeight;
+                this.reflectionReflectance90 = BackgroundMaterial.StandardReflectance90 + (1.0 - BackgroundMaterial.StandardReflectance90) * reflectionWeight;
             }
         }
 
+        @serialize()
+        protected _useRGBColor: boolean;
         /**
          * Helps to directly use the maps channels instead of their level.
          */
-        @serialize()
-        protected _useRGBColor: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useRGBColor: boolean = true;
 
+        @serialize()
+        protected _enableNoise: boolean;
         /**
          * This helps reducing the banding effect that could occur on the background.
          */
-        @serialize()
-        protected _enableNoise: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public enableNoise: boolean = false;
 
-
+        @serialize()
+        private _maxSimultaneousLights: int = 4;
         /**
          * Number of Simultaneous lights allowed on the material.
          */
-        @serialize()
-        private _maxSimultaneousLights: int = 4;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public maxSimultaneousLights: int = 4;
 
@@ -503,8 +503,8 @@
         private _reflectionControls = Vector4.Zero();
 
         /**
-         * constructor
-         * @param name The name of the material
+         * Instantiates a Background Material in the given scene
+         * @param name The friendly name of the material
          * @param scene The scene to add the material to
          */
         constructor(name: string, scene: Scene) {
@@ -549,6 +549,7 @@
          * @param mesh The mesh to render
          * @param subMesh The submesh to check against
          * @param useInstances Specify wether or not the material is used with instances
+         * @returns true if all the dependencies are ready (Textures, Effects...)
          */
         public isReadyForSubMesh(mesh: AbstractMesh, subMesh: SubMesh, useInstances: boolean = false): boolean {
             if (subMesh.effect && this.isFrozen) {
@@ -978,8 +979,8 @@
 
         /**
          * Dispose the material.
-         * @forceDisposeEffect Force disposal of the associated effect.
-         * @forceDisposeTextures Force disposal of the associated textures.
+         * @param forceDisposeEffect Force disposal of the associated effect.
+         * @param forceDisposeTextures Force disposal of the associated textures.
          */
         public dispose(forceDisposeEffect: boolean = false, forceDisposeTextures: boolean = false): void {
             if (forceDisposeTextures) {
@@ -1002,7 +1003,7 @@
 
         /**
          * Clones the material.
-         * @name The cloned name.
+         * @param name The cloned name.
          * @returns The cloned material.
          */
         public clone(name: string): BackgroundMaterial {
@@ -1029,9 +1030,9 @@
 
         /**
          * Parse a JSON input to create back a background material.
-         * @param source 
-         * @param scene 
-         * @param rootUrl 
+         * @param source The JSON data to parse
+         * @param scene The scene to create the parsed material in 
+         * @param rootUrl The root url of the assets the material depends upon
          * @returns the instantiated BackgroundMaterial.
          */
         public static Parse(source: any, scene: Scene, rootUrl: string): BackgroundMaterial {

src/Materials/babylon.materialHelper.ts

@@ -1,6 +1,19 @@
-module BABYLON {
+module BABYLON {
+    /**
+     * "Static Class" containing the most commonly used helper while dealing with material for 
+     * rendering purpose.
+     * 
+     * It contains the basic tools to help defining defines, binding uniform for the common part of the materials.
+     * 
+     * This works by convention in BabylonJS but is meant to be use only with shader following the in place naming rules and conventions.
+     */
     export class MaterialHelper {
 
+        /**
+         * Bind the current view position to an effect.
+         * @param effect The effect to be bound
+         * @param scene The scene the eyes position is used from
+         */
         public static BindEyePosition(effect: Effect, scene: Scene): void {
             if (scene._forcedViewPosition) {
                 effect.setVector3("vEyePosition", scene._forcedViewPosition);
@@ -9,6 +22,13 @@
             effect.setVector3("vEyePosition", scene._mirroredCameraPosition ? scene._mirroredCameraPosition : scene.activeCamera!.globalPosition);
         }
 
+        /**
+         * Helps preparing the defines values about the UVs in used in the effect.
+         * UVs are shared as much as we can accross chanels in the shaders.
+         * @param texture The texture we are preparing the UVs for
+         * @param defines The defines to update
+         * @param key The chanel key "diffuse", "specular"... used in the shader
+         */
         public static PrepareDefinesForMergedUV(texture: BaseTexture, defines: any, key: string): void {
             defines._needUVs = true;
             defines[key] = true;
@@ -24,6 +44,12 @@
             }
         }
 
+        /**
+         * Binds a texture matrix value to its corrsponding uniform
+         * @param texture The texture to bind the matrix for 
+         * @param uniformBuffer The uniform buffer receivin the data
+         * @param key The chanel key "diffuse", "specular"... used in the shader
+         */
         public static BindTextureMatrix(texture: BaseTexture, uniformBuffer: UniformBuffer, key: string): void {
             var matrix = texture.getTextureMatrix();
 
@@ -58,7 +84,6 @@
          * @param engine defines the current engine
          * @param defines specifies the list of active defines
          * @param useInstances defines if instances have to be turned on
-         * @param alphaTest defines if alpha testing has to be turned on
          */
         public static PrepareDefinesForFrameBoundValues(scene: Scene, engine: Engine, defines: any, useInstances: boolean): void {
             var changed = false;
@@ -83,6 +108,16 @@
             }
         }
 
+        /**
+         * Prepares the defines used in the shader depending on the attributes data available in the mesh
+         * @param mesh The mesh containing the geometry data we will draw
+         * @param defines The defines to update
+         * @param useVertexColor Precise whether vertex colors should be used or not (override mesh info)
+         * @param useBones Precise whether bones should be used or not (override mesh info)
+         * @param useMorphTargets Precise whether morph targets should be used or not (override mesh info)
+         * @param useVertexAlpha Precise whether vertex alpha should be used or not (override mesh info)
+         * @returns false if defines are considered not dirty and have not been checked
+         */
         public static PrepareDefinesForAttributes(mesh: AbstractMesh, defines: any, useVertexColor: boolean, useBones: boolean, useMorphTargets = false, useVertexAlpha = true): boolean {
             if (!defines._areAttributesDirty && defines._needNormals === defines._normals && defines._needUVs === defines._uvs) {
                 return false;
@@ -139,6 +174,16 @@
             return true;
         }
 
+        /**
+         * Prepares the defines related to the light information passed in parameter
+         * @param scene The scene we are intending to draw
+         * @param mesh The mesh the effect is compiling for
+         * @param defines The defines to update
+         * @param specularSupported Specifies whether specular is supported or not (override lights data)
+         * @param maxSimultaneousLights Specfies how manuy lights can be added to the effect at max
+         * @param disableLighting Specifies whether the lighting is disabled (override scene and light)
+         * @returns true if normals will be required for the rest of the effect
+         */
         public static PrepareDefinesForLights(scene: Scene, mesh: AbstractMesh, defines: any, specularSupported: boolean, maxSimultaneousLights = 4, disableLighting = false): boolean {
             if (!defines._areLightsDirty) {
                 return defines._needNormals;
@@ -169,6 +214,7 @@
                     var type;
                     if (light.getTypeID() === Light.LIGHTTYPEID_SPOTLIGHT) {
                         type = "SPOTLIGHT" + lightIndex;
+                        defines["PROJECTEDLIGHTTEXTURE" + lightIndex] = (light as SpotLight).projectedLightTexture ? true : false;
                     } else if (light.getTypeID() === Light.LIGHTTYPEID_HEMISPHERICLIGHT) {
                         type = "HEMILIGHT" + lightIndex;
                     } else if (light.getTypeID() === Light.LIGHTTYPEID_POINTLIGHT) {
@@ -246,6 +292,14 @@
             return needNormals;
         }
 
+        /**
+         * Prepares the uniforms and samplers list to be used in the effect. This can automatically remove from the list uniforms 
+         * that won t be acctive due to defines being turned off.
+         * @param uniformsListOrOptions The uniform names to prepare or an EffectCreationOptions containing the liist and extra information
+         * @param samplersList The samplers list
+         * @param defines The defines helping in the list generation
+         * @param maxSimultaneousLights The maximum number of simultanous light allowed in the effect
+         */
         public static PrepareUniformsAndSamplersList(uniformsListOrOptions: string[] | EffectCreationOptions, samplersList?: string[], defines?: any, maxSimultaneousLights = 4): void {
             let uniformsList: string[];
             let uniformBuffersList: Nullable<string[]> = null;
@@ -285,6 +339,12 @@
                 }
 
                 samplersList.push("shadowSampler" + lightIndex);
+                if (defines["PROJECTEDLIGHTTEXTURE" + lightIndex]){
+                    samplersList.push("projectionLightSampler" + lightIndex,);
+                    uniformsList.push(
+                        "textureProjectionMatrix" + lightIndex,
+                    );
+                }
             }
 
             if (defines["NUM_MORPH_INFLUENCERS"]) {
@@ -292,6 +352,14 @@
             }
         }
 
+        /**
+         * This helps decreasing rank by rank the shadow quality (0 being the highest rank and quality)
+         * @param defines The defines to update while falling back
+         * @param fallbacks The authorized effect fallbacks
+         * @param maxSimultaneousLights The maximum number of lights allowed
+         * @param rank the current rank of the Effect
+         * @returns The newly affected rank
+         */
         public static HandleFallbacksForShadows(defines: any, fallbacks: EffectFallbacks, maxSimultaneousLights = 4, rank = 0): number {
             let lightFallbackRank = 0;
             for (var lightIndex = 0; lightIndex < maxSimultaneousLights; lightIndex++) {
@@ -321,6 +389,12 @@
             return lightFallbackRank++;
         }
 
+        /**
+         * Prepares the list of attributes required for morph targets according to the effect defines.
+         * @param attribs The current list of supported attribs
+         * @param mesh The mesh to prepare the morph targets attributes for
+         * @param defines The current Defines of the effect
+         */
         public static PrepareAttributesForMorphTargets(attribs: string[], mesh: AbstractMesh, defines: any): void {
             var influencers = defines["NUM_MORPH_INFLUENCERS"];
 
@@ -347,6 +421,13 @@
             }
         }
 
+        /**
+         * Prepares the list of attributes required for bones according to the effect defines.
+         * @param attribs The current list of supported attribs
+         * @param mesh The mesh to prepare the bones attributes for
+         * @param defines The current Defines of the effect
+         * @param fallbacks The current efffect fallback strategy
+         */
         public static PrepareAttributesForBones(attribs: string[], mesh: AbstractMesh, defines: any, fallbacks: EffectFallbacks): void {
             if (defines["NUM_BONE_INFLUENCERS"] > 0) {
                 fallbacks.addCPUSkinningFallback(0, mesh);
@@ -360,6 +441,11 @@
             }
         }
 
+        /**
+         * Prepares the list of attributes required for instances according to the effect defines.
+         * @param attribs The current list of supported attribs
+         * @param defines The current Defines of the effect
+         */
         public static PrepareAttributesForInstances(attribs: string[], defines: any): void {
             if (defines["INSTANCES"]) {
                 attribs.push("world0");
@@ -369,7 +455,14 @@
             }
         }
 
-        // Bindings
+        /**
+         * Binds the light shadow information to the effect for the given mesh.
+         * @param light The light containing the generator
+         * @param scene The scene the lights belongs to
+         * @param mesh The mesh we are binding the information to render 
+         * @param lightIndex The light index in the effect used to render the mesh
+         * @param effect The effect we are binding the data to
+         */
         public static BindLightShadow(light: Light, scene: Scene, mesh: AbstractMesh, lightIndex: string, effect: Effect): void {
             if (light.shadowEnabled && mesh.receiveShadows) {
                 var shadowGenerator = light.getShadowGenerator();
@@ -379,11 +472,26 @@
             }
         }
 
+        /**
+         * Binds the light information to the effect.
+         * @param light The light containing the generator
+         * @param effect The effect we are binding the data to
+         * @param lightIndex The light index in the effect used to render
+         */
         public static BindLightProperties(light: Light, effect: Effect, lightIndex: number): void {
             light.transferToEffect(effect, lightIndex + "");
         }
 
-        public static BindLights(scene: Scene, mesh: AbstractMesh, effect: Effect, defines: any, maxSimultaneousLights = 4, usePhysicalLightFalloff = false) {
+        /**
+         * Binds the lights information from the scene to the effect for the given mesh.
+         * @param scene The scene the lights belongs to
+         * @param mesh The mesh we are binding the information to render 
+         * @param effect The effect we are binding the data to
+         * @param defines The generated defines for the effect
+         * @param maxSimultaneousLights The maximum number of light that can be bound to the effect
+         * @param usePhysicalLightFalloff Specifies whether the light falloff is defined physically or not
+         */
+        public static BindLights(scene: Scene, mesh: AbstractMesh, effect: Effect, defines: any, maxSimultaneousLights = 4, usePhysicalLightFalloff = false): void {
             let len = Math.min(mesh._lightSources.length, maxSimultaneousLights);
 
             for (var i = 0; i < len; i++) {
@@ -411,6 +519,12 @@
             }
         }
 
+        /**
+         * Binds the fog information from the scene to the effect for the given mesh.
+         * @param scene The scene the lights belongs to
+         * @param mesh The mesh we are binding the information to render 
+         * @param effect The effect we are binding the data to
+         */
         public static BindFogParameters(scene: Scene, mesh: AbstractMesh, effect: Effect): void {
             if (scene.fogEnabled && mesh.applyFog && scene.fogMode !== Scene.FOGMODE_NONE) {
                 effect.setFloat4("vFogInfos", scene.fogMode, scene.fogStart, scene.fogEnd, scene.fogDensity);
@@ -418,6 +532,11 @@
             }
         }
 
+        /**
+         * Binds the bones information from the mesh to the effect.
+         * @param mesh The mesh we are binding the information to render 
+         * @param effect The effect we are binding the data to
+         */
         public static BindBonesParameters(mesh?: AbstractMesh, effect?: Effect): void {
             if (mesh && mesh.useBones && mesh.computeBonesUsingShaders && mesh.skeleton) {
                 var matrices = mesh.skeleton.getTransformMatrices(mesh);
@@ -428,6 +547,11 @@
             }
         }
 
+        /**
+         * Binds the morph targets information from the mesh to the effect.
+         * @param abstractMesh The mesh we are binding the information to render 
+         * @param effect The effect we are binding the data to
+         */
         public static BindMorphTargetParameters(abstractMesh: AbstractMesh, effect: Effect): void {
             let manager = (<Mesh>abstractMesh).morphTargetManager;
             if (!abstractMesh || !manager) {
@@ -437,12 +561,23 @@
             effect.setFloatArray("morphTargetInfluences", manager.influences);
         }
 
+        /**
+         * Binds the logarithmic depth information from the scene to the effect for the given defines.
+         * @param defines The generated defines used in the effect
+         * @param effect The effect we are binding the data to
+         * @param scene The scene we are willing to render with logarithmic scale for
+         */
         public static BindLogDepth(defines: any, effect: Effect, scene: Scene): void {
             if (defines["LOGARITHMICDEPTH"]) {
                 effect.setFloat("logarithmicDepthConstant", 2.0 / (Math.log((<Camera>scene.activeCamera).maxZ + 1.0) / Math.LN2));
             }
         }
 
+        /**
+         * Binds the clip plane information from the scene to the effect.
+         * @param scene The scene the clip plane information are extracted from
+         * @param effect The effect we are binding the data to
+         */
         public static BindClipPlane(effect: Effect, scene: Scene): void {
             if (scene.clipPlane) {
                 var clipPlane = scene.clipPlane;

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/Particles/babylon.solidParticle.ts

@@ -84,6 +84,10 @@ module BABYLON {
          * Still set as invisible in order to skip useless computations (Internal use)
          */
         public _stillInvisible: boolean = false;
+        /**
+         * Last computed particle rotation matrix
+         */
+        public _rotationMatrix: number[] = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0];
 
         /**
          * Creates a Solid Particle object.

src/Particles/babylon.solidParticleSystem.ts

@@ -748,6 +748,15 @@
                                 this._quaternionRotationYPR();
                             }
                             this._quaternionToRotationMatrix();
+                            this._particle._rotationMatrix[0] = this._rotMatrix.m[0];
+                            this._particle._rotationMatrix[1] = this._rotMatrix.m[1];
+                            this._particle._rotationMatrix[2] = this._rotMatrix.m[2];
+                            this._particle._rotationMatrix[3] = this._rotMatrix.m[4];
+                            this._particle._rotationMatrix[4] = this._rotMatrix.m[5];
+                            this._particle._rotationMatrix[5] = this._rotMatrix.m[6];
+                            this._particle._rotationMatrix[6] = this._rotMatrix.m[8];
+                            this._particle._rotationMatrix[7] = this._rotMatrix.m[9];
+                            this._particle._rotationMatrix[8] = this._rotMatrix.m[10];
                         }
        
                         // particle vertex loop
@@ -773,9 +782,9 @@
                             this._vertex.y += this._particle.pivot.y;
                             this._vertex.z += this._particle.pivot.z;
     
-                            this._rotated.x = this._vertex.x * this._rotMatrix.m[0] + this._vertex.y * this._rotMatrix.m[4] + this._vertex.z * this._rotMatrix.m[8];
-                            this._rotated.y = this._vertex.x * this._rotMatrix.m[1] + this._vertex.y * this._rotMatrix.m[5] + this._vertex.z * this._rotMatrix.m[9];
-                            this._rotated.z = this._vertex.x * this._rotMatrix.m[2] + this._vertex.y * this._rotMatrix.m[6] + this._vertex.z * this._rotMatrix.m[10];
+                            this._rotated.x = this._vertex.x * this._particle._rotationMatrix[0] + this._vertex.y * this._particle._rotationMatrix[3] + this._vertex.z * this._particle._rotationMatrix[6];
+                            this._rotated.y = this._vertex.x * this._particle._rotationMatrix[1] + this._vertex.y * this._particle._rotationMatrix[4] + this._vertex.z * this._particle._rotationMatrix[7];
+                            this._rotated.z = this._vertex.x * this._particle._rotationMatrix[2] + this._vertex.y * this._particle._rotationMatrix[5] + this._vertex.z * this._particle._rotationMatrix[8];
     
                             this._positions32[idx] = this._particle.position.x + this._cam_axisX.x * this._rotated.x + this._cam_axisY.x * this._rotated.y + this._cam_axisZ.x * this._rotated.z;
                             this._positions32[idx + 1] = this._particle.position.y + this._cam_axisX.y * this._rotated.x + this._cam_axisY.y * this._rotated.y + this._cam_axisZ.y * this._rotated.z;
@@ -808,9 +817,9 @@
                                 this._normal.y = this._fixedNormal32[idx + 1];
                                 this._normal.z = this._fixedNormal32[idx + 2];
     
-                                this._rotated.x = this._normal.x * this._rotMatrix.m[0] + this._normal.y * this._rotMatrix.m[4] + this._normal.z * this._rotMatrix.m[8];
-                                this._rotated.y = this._normal.x * this._rotMatrix.m[1] + this._normal.y * this._rotMatrix.m[5] + this._normal.z * this._rotMatrix.m[9];
-                                this._rotated.z = this._normal.x * this._rotMatrix.m[2] + this._normal.y * this._rotMatrix.m[6] + this._normal.z * this._rotMatrix.m[10];
+                                this._rotated.x = this._normal.x * this._particle._rotationMatrix[0] + this._normal.y * this._particle._rotationMatrix[3] + this._normal.z * this._particle._rotationMatrix[6];
+                                this._rotated.y = this._normal.x * this._particle._rotationMatrix[1] + this._normal.y * this._particle._rotationMatrix[4] + this._normal.z * this._particle._rotationMatrix[7];
+                                this._rotated.z = this._normal.x * this._particle._rotationMatrix[2] + this._normal.y * this._particle._rotationMatrix[5] + this._normal.z * this._particle._rotationMatrix[8];
     
                                 this._normals32[idx] = this._cam_axisX.x * this._rotated.x + this._cam_axisY.x * this._rotated.y + this._cam_axisZ.x * this._rotated.z;
                                 this._normals32[idx + 1] = this._cam_axisX.y * this._rotated.x + this._cam_axisY.y * this._rotated.y + this._cam_axisZ.y * this._rotated.z;
@@ -868,9 +877,9 @@
                                 this._vertex.x = this._particle._modelBoundingInfo.boundingBox.vectors[b].x * this._particle.scaling.x;
                                 this._vertex.y = this._particle._modelBoundingInfo.boundingBox.vectors[b].y * this._particle.scaling.y;
                                 this._vertex.z = this._particle._modelBoundingInfo.boundingBox.vectors[b].z * this._particle.scaling.z;
-                                this._rotated.x = this._vertex.x * this._rotMatrix.m[0] + this._vertex.y * this._rotMatrix.m[4] + this._vertex.z * this._rotMatrix.m[8];
-                                this._rotated.y = this._vertex.x * this._rotMatrix.m[1] + this._vertex.y * this._rotMatrix.m[5] + this._vertex.z * this._rotMatrix.m[9];
-                                this._rotated.z = this._vertex.x * this._rotMatrix.m[2] + this._vertex.y * this._rotMatrix.m[6] + this._vertex.z * this._rotMatrix.m[10];
+                                this._rotated.x = this._vertex.x * this._particle._rotationMatrix[0] + this._vertex.y * this._particle._rotationMatrix[3] + this._vertex.z * this._particle._rotationMatrix[6];
+                                this._rotated.y = this._vertex.x * this._particle._rotationMatrix[1] + this._vertex.y * this._particle._rotationMatrix[4] + this._vertex.z * this._particle._rotationMatrix[7];
+                                this._rotated.z = this._vertex.x * this._particle._rotationMatrix[2] + this._vertex.y * this._particle._rotationMatrix[5] + this._vertex.z * this._particle._rotationMatrix[8];
                                 bBox.vectors[b].x = this._particle.position.x + this._cam_axisX.x * this._rotated.x + this._cam_axisY.x * this._rotated.y + this._cam_axisZ.x * this._rotated.z;
                                 bBox.vectors[b].y = this._particle.position.y + this._cam_axisX.y * this._rotated.x + this._cam_axisY.y * this._rotated.y + this._cam_axisZ.y * this._rotated.z;
                                 bBox.vectors[b].z = this._particle.position.z + this._cam_axisX.z * this._rotated.x + this._cam_axisY.z * this._rotated.y + this._cam_axisZ.z * this._rotated.z;

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,11 @@
                 this.copyBack.autoClear = false;
             }
 
+            if(this.depthOfFieldEnabled){
+                this.depthOfField = new DepthOfFieldEffect(this._scene, this._defaultPipelineTextureType);
+                this.addEffect(this.depthOfField);
+            }
+
             if (this._imageProcessingEnabled) {
                 this.imageProcessing = new ImageProcessingPostProcess("imageProcessing", 1.0, null, Texture.BILINEAR_SAMPLINGMODE, engine, false, this._defaultPipelineTextureType);
                 if (this._hdr) {
@@ -303,6 +330,10 @@
                 if (this.finalMerge) {
                     this.finalMerge.dispose(camera);
                 }
+
+                if(this.depthOfField){
+                    this.depthOfField.disposeEffects(camera);
+                }
             }
 
             (<any>this.pass) = null;
@@ -313,6 +344,7 @@
             (<any>this.imageProcessing) = null;
             (<any>this.fxaa) = null;
             (<any>this.finalMerge) = null;
+            (<any>this.depthOfField) = null;
         }
 
         // Dispose

src/PostProcess/RenderPipeline/babylon.postProcessRenderEffect.ts

@@ -1,22 +1,21 @@
 module BABYLON {
     export class PostProcessRenderEffect {
         private _postProcesses: any;
-        private _getPostProcess: () => Nullable<PostProcess>;
+        private _getPostProcess: () => Nullable<PostProcess | Array<PostProcess>>;
 
         private _singleInstance: boolean;
 
         private _cameras: { [key: string]: Nullable<Camera> };
         private _indicesForCamera: { [key: string]: number[] };
 
-        private _renderPasses: any;
         private _renderEffectAsPasses: any;
 
         // private
         public _name: string;
 
         public applyParameters: (postProcess: PostProcess) => void;
-
-        constructor(engine: Engine, name: string, getPostProcess: () => Nullable<PostProcess>, singleInstance?: boolean) {
+        
+        constructor(engine: Engine, name: string, getPostProcess: () => Nullable<PostProcess | Array<PostProcess>>, singleInstance?: boolean) {
             this._name = name;
             this._singleInstance = singleInstance || true;
 
@@ -27,59 +26,28 @@ module BABYLON {
 
             this._postProcesses = {};
 
-            this._renderPasses = {};
             this._renderEffectAsPasses = {};
         }
 
         public get isSupported(): boolean {
             for (var index in this._postProcesses) {
-                if (!this._postProcesses[index].isSupported) {
-                    return false;
+                for(var ppIndex in this._postProcesses[index]){
+                    if (!this._postProcesses[index][ppIndex].isSupported) {
+                        return false;
+                    }
                 }
             }
             return true;
         }
 
         public _update(): void {
-            for (var renderPassName in this._renderPasses) {
-                this._renderPasses[renderPassName]._update();
-            }
-        }
-
-        public addPass(renderPass: PostProcessRenderPass): void {
-            this._renderPasses[renderPass._name] = renderPass;
-
-            this._linkParameters();
-        }
-
-        public removePass(renderPass: PostProcessRenderPass): void {
-            delete this._renderPasses[renderPass._name];
-
-            this._linkParameters();
         }
-
         public addRenderEffectAsPass(renderEffect: PostProcessRenderEffect): void {
             this._renderEffectAsPasses[renderEffect._name] = renderEffect;
 
             this._linkParameters();
         }
 
-        public getPass(passName: string): Nullable<PostProcessRenderPass> {
-            for (var renderPassName in this._renderPasses) {
-                if (renderPassName === passName) {
-                    return this._renderPasses[passName];
-                }
-            }
-
-            return null;
-        }
-
-        public emptyPasses(): void {
-            this._renderPasses = {};
-
-            this._linkParameters();
-        }
-
         // private
         public _attachCameras(cameras: Camera): void;
         public _attachCameras(cameras: Camera[]): void;
@@ -103,23 +71,27 @@ module BABYLON {
                     cameraKey = cameraName;
                 }
 
-                this._postProcesses[cameraKey] = this._postProcesses[cameraKey] || this._getPostProcess();
-
-                var index = camera.attachPostProcess(this._postProcesses[cameraKey]);
+                if(!this._postProcesses[cameraKey]){
+                    var postProcess = this._getPostProcess();
+                    if(postProcess){
+                        this._postProcesses[cameraKey] = Array.isArray(postProcess) ? postProcess :[postProcess];
+                    }
+                }
 
                 if (!this._indicesForCamera[cameraName]) {
                     this._indicesForCamera[cameraName] = [];
                 }
 
-                this._indicesForCamera[cameraName].push(index);
-
+                this._postProcesses[cameraKey].forEach((postProcess:PostProcess) => {
+                    var index = camera.attachPostProcess(postProcess);
+    
+                    this._indicesForCamera[cameraName].push(index);
+                });
+                
                 if (!this._cameras[cameraName]) {
                     this._cameras[cameraName] = camera;
                 }
 
-                for (var passName in this._renderPasses) {
-                    this._renderPasses[passName]._incRefCount();
-                }
             }
 
             this._linkParameters();
@@ -138,17 +110,14 @@ module BABYLON {
             for (var i = 0; i < cams.length; i++) {
                 var camera: Camera = cams[i];
                 var cameraName: string = camera.name;
-
-                camera.detachPostProcess(this._postProcesses[this._singleInstance ? 0 : cameraName]);
+                this._postProcesses[this._singleInstance ? 0 : cameraName].forEach((postProcess:PostProcess)=>{
+                    camera.detachPostProcess(postProcess);
+                })
 
                 if (this._cameras[cameraName]) {
                     //this._indicesForCamera.splice(index, 1);
                     this._cameras[cameraName] = null;
                 }
-
-                for (var passName in this._renderPasses) {
-                    this._renderPasses[passName]._decRefCount();
-                }
             }
         }
 
@@ -171,10 +140,6 @@ module BABYLON {
                         cameras[i].attachPostProcess(this._postProcesses[this._singleInstance ? 0 : cameraName], this._indicesForCamera[cameraName][j]);
                     }
                 }
-
-                for (var passName in this._renderPasses) {
-                    this._renderPasses[passName]._incRefCount();
-                }
             }
         }
 
@@ -193,43 +158,37 @@ module BABYLON {
                 var cameraName = camera.Name;
 
                 camera.detachPostProcess(this._postProcesses[this._singleInstance ? 0 : cameraName]);
-
-                for (var passName in this._renderPasses) {
-                    this._renderPasses[passName]._decRefCount();
-                }
             }
         }
 
         public getPostProcess(camera?: Camera): Nullable<PostProcess> {
             if (this._singleInstance) {
-                return this._postProcesses[0];
+                return this._postProcesses[0][0];
             }
             else {
 
                 if (!camera) {
                     return null;
                 }
-                return this._postProcesses[camera.name];
+                return this._postProcesses[camera.name][0];
             }
         }
 
         private _linkParameters(): void {
             for (var index in this._postProcesses) {
-                if (this.applyParameters) {
-                    this.applyParameters(this._postProcesses[index]);
-                }
+                this._postProcesses[index].forEach((postProcess:PostProcess)=>{
+                    if (this.applyParameters) {
+                        this.applyParameters(postProcess);
+                    }
 
-                this._postProcesses[index].onBeforeRenderObservable.add((effect: Effect) => {
-                    this._linkTextures(effect);
+                    postProcess.onBeforeRenderObservable.add((effect: Effect) => {
+                        this._linkTextures(effect);
+                    });
                 });
             }
         }
 
         private _linkTextures(effect: Effect): void {
-            for (var renderPassName in this._renderPasses) {
-                effect.setTexture(renderPassName, this._renderPasses[renderPassName].getRenderTexture());
-            }
-
             for (var renderEffectName in this._renderEffectAsPasses) {
                 effect.setTextureFromPostProcess(renderEffectName + "Sampler", this._renderEffectAsPasses[renderEffectName].getPostProcess());
             }

src/PostProcess/RenderPipeline/babylon.postProcessRenderPass.ts

@@ -1,58 +0,0 @@
-module BABYLON {
-    export class PostProcessRenderPass {
-        private _renderList: Mesh[];
-        private _renderTexture: RenderTargetTexture;
-        private _scene: Scene;
-        private _refCount: number = 0;
-
-        // private
-        public _name: string;
-
-        constructor(scene: Scene, name: string, size: number, renderList: Mesh[], beforeRender: () => void, afterRender: () => void) {
-            this._name = name;
-
-            this._renderTexture = new RenderTargetTexture(name, size, scene);
-            this.setRenderList(renderList);
-
-            this._renderTexture.onBeforeRenderObservable.add(beforeRender);
-            this._renderTexture.onAfterRenderObservable.add(afterRender);
-
-            this._scene = scene;
-
-            this._renderList = renderList;
-        }
-
-        // private
-        public _incRefCount(): number {
-            if (this._refCount === 0) {
-                this._scene.customRenderTargets.push(this._renderTexture);
-            }
-
-            return ++this._refCount;
-        }
-
-        public _decRefCount(): number {
-            this._refCount--;
-
-            if (this._refCount <= 0) {
-                this._scene.customRenderTargets.splice(this._scene.customRenderTargets.indexOf(this._renderTexture), 1);
-            }
-
-            return this._refCount;
-        }
-
-        public _update(): void {
-            this.setRenderList(this._renderList);
-        }
-
-        // public
-
-        public setRenderList(renderList: Mesh[]): void {
-            this._renderTexture.renderList = renderList;
-        }
-
-        public getRenderTexture(): RenderTargetTexture {
-            return this._renderTexture;
-        }
-    }
-}

src/PostProcess/RenderPipeline/babylon.postProcessRenderPipeline.ts

@@ -1,6 +1,5 @@
 module BABYLON {
     export class PostProcessRenderPipeline {
-        private _engine: Engine;
 
         private _renderEffects: {[key: string]: PostProcessRenderEffect};
         private _renderEffectsForIsolatedPass: PostProcessRenderEffect[];
@@ -11,11 +10,7 @@ module BABYLON {
         @serialize()
         public _name: string;
 
-        private static PASS_EFFECT_NAME: string = "passEffect";
-        private static PASS_SAMPLER_NAME: string = "passSampler";
-
         constructor(engine: Engine, name: string) {
-            this._engine = engine;
             this._name = name;
 
             this._renderEffects = {};
@@ -128,76 +123,6 @@ module BABYLON {
             }
         }
 
-        public _enableDisplayOnlyPass(passName: string, cameras: Camera): void;
-        public _enableDisplayOnlyPass(passName: string, cameras: Nullable<Camera[]>): void;
-        public _enableDisplayOnlyPass(passName: string, cameras: any): void {
-            var cams = Tools.MakeArray(cameras || this._cameras);
-
-            if (!cams) {
-                return;
-            }
-
-            var pass: Nullable<PostProcessRenderPass> = null;
-            var renderEffectName;
-            for (renderEffectName in this._renderEffects) {
-                if (this._renderEffects.hasOwnProperty(renderEffectName)) {
-                    pass = this._renderEffects[renderEffectName].getPass(passName);
-
-                    if (pass != null) {
-                        break;
-                    }
-                }
-            }
-
-            if (pass === null) {
-                return;
-            }
-
-            for (renderEffectName in this._renderEffects) {
-                if (this._renderEffects.hasOwnProperty(renderEffectName)) {
-                    this._renderEffects[renderEffectName]._disable(cams);
-                }
-            }
-
-            pass._name = PostProcessRenderPipeline.PASS_SAMPLER_NAME;
-
-            for (var i = 0; i < cams.length; i++) {
-                var camera = cams[i];
-                var cameraName = camera.name;
-
-                this._renderEffectsForIsolatedPass[cameraName] = this._renderEffectsForIsolatedPass[cameraName] || new PostProcessRenderEffect(this._engine, PostProcessRenderPipeline.PASS_EFFECT_NAME,
-                    () => {return new DisplayPassPostProcess(PostProcessRenderPipeline.PASS_EFFECT_NAME, 1.0, null, undefined, this._engine, true) });
-                this._renderEffectsForIsolatedPass[cameraName].emptyPasses();
-                this._renderEffectsForIsolatedPass[cameraName].addPass(pass);
-                this._renderEffectsForIsolatedPass[cameraName]._attachCameras(camera);
-            }
-        }
-
-        public _disableDisplayOnlyPass(cameras: Camera): void;
-        public _disableDisplayOnlyPass(cameras: Camera[]): void;
-        public _disableDisplayOnlyPass(cameras: any): void {
-            var cams = Tools.MakeArray(cameras || this._cameras);
-
-            if (!cams) {
-                return;
-            }
-
-            for (var i = 0; i < cams.length; i++) {
-                var camera = cams[i];
-                var cameraName = camera.name;
-
-                this._renderEffectsForIsolatedPass[cameraName] = this._renderEffectsForIsolatedPass[cameraName] || new PostProcessRenderEffect(this._engine, PostProcessRenderPipeline.PASS_EFFECT_NAME, 
-                                    () => {return new DisplayPassPostProcess(PostProcessRenderPipeline.PASS_EFFECT_NAME, 1.0, null, undefined, this._engine, true) });
-                this._renderEffectsForIsolatedPass[cameraName]._disable(camera);
-            }
-
-            for (var renderEffectName in this._renderEffects) {
-                if (this._renderEffects.hasOwnProperty(renderEffectName)) {
-                    this._renderEffects[renderEffectName]._enable(cams);
-                }
-            }
-        }
-
         public _update(): void {
             for (var renderEffectName in this._renderEffects) {
                 if (this._renderEffects.hasOwnProperty(renderEffectName)) {

src/PostProcess/RenderPipeline/babylon.postProcessRenderPipelineManager.ts

@@ -58,30 +58,6 @@ module BABYLON {
             renderPipeline._disableEffect(renderEffectName, cameras);
         }
 
-        public enableDisplayOnlyPassInPipeline(renderPipelineName: string, passName: string, cameras: Camera): void;
-        public enableDisplayOnlyPassInPipeline(renderPipelineName: string, passName: string, cameras: Camera[]): void;
-        public enableDisplayOnlyPassInPipeline(renderPipelineName: string, passName: string, cameras: any): void {
-            var renderPipeline: PostProcessRenderPipeline = this._renderPipelines[renderPipelineName];
-
-            if (!renderPipeline) {
-                return;
-            }
-
-            renderPipeline._enableDisplayOnlyPass(passName, cameras);
-        }
-
-        public disableDisplayOnlyPassInPipeline(renderPipelineName: string, cameras: Camera): void;
-        public disableDisplayOnlyPassInPipeline(renderPipelineName: string, cameras: Camera[]): void;
-        public disableDisplayOnlyPassInPipeline(renderPipelineName: string, cameras: any): void {
-            var renderPipeline: PostProcessRenderPipeline = this._renderPipelines[renderPipelineName];
-
-            if (!renderPipeline) {
-                return;
-            }
-
-            renderPipeline._disableDisplayOnlyPass(cameras);
-        }
-
         public update(): void {
             for (var renderPipelineName in this._renderPipelines) {
                 if (this._renderPipelines.hasOwnProperty(renderPipelineName)) {

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,93 @@
+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 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 scene The scene the effect belongs to.
+         * @param pipelineTextureType The type of texture to be used when performing the post processing.
+         */
+        constructor(scene: Scene, pipelineTextureType = 0) {
+            super(scene.getEngine(), "depth of field", ()=>{return [this.circleOfConfusion, this.depthOfFieldPass, this.depthOfFieldBlurX, this.depthOfFieldBlurY, this.depthOfFieldMerge]}, 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);
+            // Capture circle of confusion texture
+            this.depthOfFieldPass = new PassPostProcess("depthOfFieldPass", 1.0, null, Texture.BILINEAR_SAMPLINGMODE, scene.getEngine(), false, pipelineTextureType);
+            // 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);
+            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);
+            // 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);
+        }
+
+        /**
+         * 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.observable.ts

@@ -39,6 +39,12 @@
          * The current object in the bubbling phase
          */
         public currentTarget?: any;
+
+        /**
+         * This will be populated with the return value of the last function that was executed.
+         * If it is the first function in the callback chain it will be the event data.
+         */
+        public lastReturnValue?: any;
     }
 
     /**
@@ -187,13 +193,14 @@
             state.target = target;
             state.currentTarget = currentTarget;
             state.skipNextObservers = false;
+            state.lastReturnValue = eventData;
 
             for (var obs of this._observers) {
                 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) {
@@ -204,6 +211,59 @@
         }
 
         /**
+         * 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.
+         */
+        public notifyObserversWithPromise(eventData: T, mask: number = -1, target?: any, currentTarget?: any): Promise<T> {
+
+            // create an empty promise
+            let p: Promise<any> = Promise.resolve(eventData);
+
+            // no observers? return this promise.
+            if (!this._observers.length) {
+                return p;
+            }
+
+            let 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(obs => {
+                if (state.skipNextObservers) {
+                    return;
+                }
+                if (obs.mask & mask) {
+                    if (obs.scope) {
+                        p = p.then((lastReturnedValue) => {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback.apply(obs.scope, [eventData, state]);
+                        });
+                    } else {
+                        p = p.then((lastReturnedValue) => {
+                            state.lastReturnValue = lastReturnedValue;
+                            return obs.callback(eventData, state);
+                        });
+                    }
+                }
+            });
+
+            // return the eventData
+            return p.then(() => { return eventData; });
+        }
+
+        /**
          * Notify a specific observer
          * @param eventData
          * @param mask

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

@@ -2431,7 +2431,7 @@
 
         public sortLightsByPriority(): void {
             if (this.requireLightSorting) {
-                this.lights.sort(Light.compareLightsPriority);
+                this.lights.sort(Light.CompareLightsPriority);
             }
         }
 
@@ -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",