added a validateSkin function. updated readme. removed the GLTF loader from auto fixing skinned meshes. merged and resolved conflicts.

dist/preview release/glTF2Interface/package.json

@@ -1,7 +1,7 @@
 {
     "name": "babylonjs-gltf2interface",
     "description": "A typescript declaration of babylon's gltf2 inteface.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/gui/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-gui",
     "description": "The Babylon.js GUI library is an extension you can use to generate interactive user interface. It is build on top of the DynamicTexture.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/inspector/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-inspector",
     "description": "The Babylon.js inspector.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/loaders/babylon.glTF1FileLoader.js

@@ -2043,7 +2043,10 @@ var BABYLON;
                     var attribute = technique.attributes[attr];
                     var attributeParameter = technique.parameters[attribute];
                     if (attributeParameter.semantic) {
-                        attributes.push(getAttribute(attributeParameter));
+                        var name_1 = getAttribute(attributeParameter);
+                        if (name_1) {
+                            attributes.push(name_1);
+                        }
                     }
                 }
                 // Configure vertex shader

dist/preview release/loaders/babylon.glTFFileLoader.js

@@ -2043,7 +2043,10 @@ var BABYLON;
                     var attribute = technique.attributes[attr];
                     var attributeParameter = technique.parameters[attribute];
                     if (attributeParameter.semantic) {
-                        attributes.push(getAttribute(attributeParameter));
+                        var name_1 = getAttribute(attributeParameter);
+                        if (name_1) {
+                            attributes.push(name_1);
+                        }
                     }
                 }
                 // Configure vertex shader

dist/preview release/loaders/babylonjs.loaders.js

@@ -3126,7 +3126,10 @@ var BABYLON;
                     var attribute = technique.attributes[attr];
                     var attributeParameter = technique.parameters[attribute];
                     if (attributeParameter.semantic) {
-                        attributes.push(getAttribute(attributeParameter));
+                        var name_1 = getAttribute(attributeParameter);
+                        if (name_1) {
+                            attributes.push(name_1);
+                        }
                     }
                 }
                 // Configure vertex shader

dist/preview release/loaders/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-loaders",
     "description": "The Babylon.js file loaders library is an extension you can use to load different 3D file types into a Babylon scene.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"
@@ -27,7 +27,7 @@
     ],
     "license": "Apache-2.0",
     "dependencies": {
-        "babylonjs-gltf2interface": "3.3.0-rc.1"
+        "babylonjs-gltf2interface": "3.3.0-rc.2"
     },
     "peerDependencies": {
         "babylonjs": ">=3.2.0-alpha"

dist/preview release/materialsLibrary/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-materials",
     "description": "The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/postProcessesLibrary/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-post-process",
     "description": "The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/proceduralTexturesLibrary/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-procedural-textures",
     "description": "The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

dist/preview release/serializers/package.json

@@ -4,7 +4,7 @@
     },
     "name": "babylonjs-serializers",
     "description": "The Babylon.js serializers library is an extension you can use to serialize Babylon scenes.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"
@@ -27,7 +27,7 @@
     ],
     "license": "Apache-2.0",
     "dependencies": {
-        "babylonjs-gltf2interface": "3.3.0-rc.1"
+        "babylonjs-gltf2interface": "3.3.0-rc.2"
     },
     "peerDependencies": {
         "babylonjs": ">=3.2.0-alpha"

loaders/src/glTF/1.0/babylon.glTFLoader.ts

@@ -1416,9 +1416,9 @@ module BABYLON.GLTF1 {
             var pixelTokenizer = new Tokenizer(pixelShader);
 
             var unTreatedUniforms: { [key: string]: IGLTFTechniqueParameter } = {};
-            var uniforms = [];
-            var attributes = [];
-            var samplers = [];
+            var uniforms: string[] = [];
+            var attributes: string[] = [];
+            var samplers: string[] = [];
 
             // Fill uniform, sampler2D and attributes
             for (var unif in technique.uniforms) {
@@ -1450,7 +1450,10 @@ module BABYLON.GLTF1 {
                 var attributeParameter: IGLTFTechniqueParameter = technique.parameters[attribute];
 
                 if (attributeParameter.semantic) {
-                    attributes.push(getAttribute(attributeParameter));
+                    let name = getAttribute(attributeParameter);
+                    if (name) {
+                        attributes.push(name);
+                    }
                 }
             }
 

loaders/src/glTF/2.0/babylon.glTFLoader.ts

@@ -639,7 +639,6 @@ module BABYLON.GLTF2 {
             promises.push(this._loadVertexDataAsync(context, primitive, babylonMesh).then(babylonGeometry => {
                 return this._loadMorphTargetsAsync(context, primitive, babylonMesh, babylonGeometry).then(() => {
                     babylonGeometry.applyToMesh(babylonMesh);
-                    babylonMesh.normalizeSkinWeights();
                 });
             }));
 

package.json

@@ -9,7 +9,7 @@
     ],
     "name": "babylonjs",
     "description": "Babylon.js is a JavaScript 3D engine based on webgl.",
-    "version": "3.3.0-rc.1",
+    "version": "3.3.0-rc.2",
     "repository": {
         "type": "git",
         "url": "https://github.com/BabylonJS/Babylon.js.git"

src/Cameras/Inputs/babylon.arcRotateCameraKeyboardMoveInput.ts

@@ -61,6 +61,12 @@ module BABYLON {
         @serialize()
         public useAltToZoom: boolean = true;
 
+        /**
+         * Rotation speed of the camera
+         */
+        @serialize()
+        public angularSpeed = 0.01;
+
         private _keys = new Array<number>();
         private _ctrlPressed: boolean;
         private _altPressed: boolean;
@@ -166,7 +172,7 @@ module BABYLON {
                         if (this._ctrlPressed && this.camera._useCtrlForPanning) {
                             camera.inertialPanningX -= 1 / this.panningSensibility;
                         } else {
-                            camera.inertialAlphaOffset -= 0.01;
+                            camera.inertialAlphaOffset -= this.angularSpeed;
                         }
                     } else if (this.keysUp.indexOf(keyCode) !== -1) {
                         if (this._ctrlPressed && this.camera._useCtrlForPanning) {
@@ -176,13 +182,13 @@ module BABYLON {
                             camera.inertialRadiusOffset += 1 / this.zoomingSensibility;
                         }
                         else {
-                            camera.inertialBetaOffset -= 0.01;
+                            camera.inertialBetaOffset -= this.angularSpeed;
                         }
                     } else if (this.keysRight.indexOf(keyCode) !== -1) {
                         if (this._ctrlPressed && this.camera._useCtrlForPanning) {
                             camera.inertialPanningX += 1 / this.panningSensibility;
                         } else {
-                            camera.inertialAlphaOffset += 0.01;
+                            camera.inertialAlphaOffset += this.angularSpeed;
                         }
                     } else if (this.keysDown.indexOf(keyCode) !== -1) {
                         if (this._ctrlPressed && this.camera._useCtrlForPanning) {
@@ -192,7 +198,7 @@ module BABYLON {
                             camera.inertialRadiusOffset -= 1 / this.zoomingSensibility;
                         }
                         else {
-                            camera.inertialBetaOffset += 0.01;
+                            camera.inertialBetaOffset += this.angularSpeed;
                         }
                     } else if (this.keysReset.indexOf(keyCode) !== -1) {
                         if (camera.useInputToRestoreState) {

src/Engine/babylon.engine.ts

@@ -475,7 +475,7 @@
          * Returns the current version of the framework
          */
         public static get Version(): string {
-            return "3.3.0-rc.1";
+            return "3.3.0-rc.2";
         }
 
         // Updatable statics so stick with vars here

src/Materials/PBR/babylon.pbrBaseMaterial.ts

@@ -286,7 +286,7 @@
         protected _roughness: Nullable<number>;
 
         /**
-         * Used to enable roughness/glossiness fetch from a separate chanel depending on the current mode.
+         * Used to enable roughness/glossiness fetch from a separate channel depending on the current mode.
          * Gray Scale represents roughness in metallic mode and glossiness in specular mode.
          */
         protected _microSurfaceTexture: BaseTexture;

src/Materials/PBR/babylon.pbrBaseSimpleMaterial.ts

@@ -103,10 +103,16 @@
             this._markAllSubMeshesAsTexturesDirty();
         }
 
+        /**
+         * Stores the pre-calculated light information of a mesh in a texture.
+         */
         @serializeAsTexture()
         @expandToProperty("_markAllSubMeshesAsTexturesDirty", null)
         public lightmapTexture: BaseTexture;
 
+        /**
+         * If true, the light map contains occlusion information instead of lighting info.
+         */
         @serialize()
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useLightmapAsShadowmap = false;

src/Materials/PBR/babylon.pbrMaterial.ts

@@ -155,7 +155,7 @@
         public roughness: Nullable<number>;
 
         /**
-         * Used to enable roughness/glossiness fetch from a separate chanel depending on the current mode.
+         * Used to enable roughness/glossiness fetch from a separate channel depending on the current mode.
          * Gray Scale represents roughness in metallic mode and glossiness in specular mode.
          */
         @serializeAsTexture()
@@ -247,6 +247,9 @@
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public linkRefractionWithTransparency = false;
 
+        /**
+         * If true, the light map contains occlusion information instead of lighting info.
+         */
         @serialize()
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useLightmapAsShadowmap = false;
@@ -273,7 +276,7 @@
         public alphaCutOff = 0.4;
 
         /**
-         * Specifies that the material will keeps the specular highlights over a transparent surface (only the most limunous ones).
+         * Specifies that the material will keep the specular highlights over a transparent surface (only the most limunous ones).
          * A car glass is a good exemple of that. When sun reflects on it you can not see what is behind.
          */
         @serialize()

src/Materials/Textures/Procedurals/babylon.customProceduralTexture.ts

@@ -1,20 +1,37 @@
 module BABYLON {
+    /**
+     * Procedural texturing is a way to programmatically create a texture. There are 2 types of procedural textures: code-only, and code that references some classic 2D images, sometimes called 'refMaps' or 'sampler' images.
+     * Custom Procedural textures are the easiest way to create your own procedural in your application.
+     * @see http://doc.babylonjs.com/how_to/how_to_use_procedural_textures#creating-custom-procedural-textures
+     */
     export class CustomProceduralTexture extends ProceduralTexture {
         private _animate: boolean = true;
         private _time: number = 0;
         private _config: any;
-        private _texturePath: any;
-
-        constructor(name: string, texturePath: any, size: number, scene: Scene, fallbackTexture?: Texture, generateMipMaps?: boolean) {
+        private _texturePath: string;
+
+        /**
+         * Instantiates a new Custom Procedural Texture.
+         * Procedural texturing is a way to programmatically create a texture. There are 2 types of procedural textures: code-only, and code that references some classic 2D images, sometimes called 'refMaps' or 'sampler' images.
+         * Custom Procedural textures are the easiest way to create your own procedural in your application.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_procedural_textures#creating-custom-procedural-textures
+         * @param name Define the name of the texture
+         * @param texturePath Define the folder path containing all the cutom texture related files (config, shaders...)
+         * @param size Define the size of the texture to create
+         * @param scene Define the scene the texture belongs to
+         * @param fallbackTexture Define a fallback texture in case there were issues to create the custom texture
+         * @param generateMipMaps Define if the texture should creates mip maps or not
+         */
+        constructor(name: string, texturePath: string, size: number, scene: Scene, fallbackTexture?: Texture, generateMipMaps?: boolean) {
             super(name, size, null, scene, fallbackTexture, generateMipMaps);
             this._texturePath = texturePath;
 
             //Try to load json
-            this.loadJson(texturePath);
+            this._loadJson(texturePath);
             this.refreshRate = 1;
         }
 
-        private loadJson(jsonUrl: string): void {
+        private _loadJson(jsonUrl: string): void {
             let noConfigFile = () => {
                 Tools.Log("No config file found in " + jsonUrl + " trying to use ShadersStore or DOM element");
                 try {
@@ -62,6 +79,10 @@
             }
         }
 
+        /**
+         * Is the texture ready to be used ? (rendered at least once)
+         * @returns true if ready, otherwise, false.
+         */
         public isReady(): boolean {
             if (!super.isReady()) {
                 return false;
@@ -78,6 +99,10 @@
             return true;
         }
 
+        /**
+         * Render the texture to its associated render target.
+         * @param useCameraPostProcess Define if camera post process should be applied to the texture
+         */
         public render(useCameraPostProcess?: boolean): void {
             let scene = this.getScene();
             if (this._animate && scene) {
@@ -88,12 +113,18 @@
             super.render(useCameraPostProcess);
         }
 
+        /**
+         * Update the list of dependant textures samplers in the shader.
+         */
         public updateTextures(): void {
             for (var i = 0; i < this._config.sampler2Ds.length; i++) {
                 this.setTexture(this._config.sampler2Ds[i].sample2Dname, new Texture(this._texturePath + "/" + this._config.sampler2Ds[i].textureRelativeUrl, this.getScene()));
             }
         }
 
+        /**
+         * Update the uniform values of the procedural texture in the shader.
+         */
         public updateShaderUniforms(): void {
             if (this._config) {
                 for (var j = 0; j < this._config.uniforms.length; j++) {
@@ -122,6 +153,9 @@
             this.setFloat("time", this._time);
         }
 
+        /**
+         * Define if the texture animates or not.
+         */
         public get animate(): boolean {
             return this._animate;
         }

src/Materials/Textures/Procedurals/babylon.proceduralTexture.ts

@@ -1,16 +1,15 @@
 module BABYLON {
+    /**
+     * Procedural texturing is a way to programmatically create a texture. There are 2 types of procedural textures: code-only, and code that references some classic 2D images, sometimes called 'refMaps' or 'sampler' images.
+     * This is the base class of any Procedural texture and contains most of the shareable code.
+     * @see http://doc.babylonjs.com/how_to/how_to_use_procedural_textures
+     */
     export class ProceduralTexture extends Texture {
-        @serialize()
-        private _size: number;
-
-        /** @hidden */
-        @serialize()
-        public _generateMipMaps: boolean;
-
+        /**
+         * Define if the texture is enabled or not (disabled texture will not render)
+         */
         @serialize()
         public isEnabled = true;
-        private _currentRefreshId = -1;
-        private _refreshRate = 1;
 
         /**
          * Callback called when the texture is generated
@@ -22,17 +21,26 @@
          */
         public onGeneratedObservable = new Observable<ProceduralTexture>();
 
-        private _vertexBuffers: { [key: string]: Nullable<VertexBuffer> } = {};
-        private _indexBuffer: Nullable<WebGLBuffer>;
-        /** get the internal effect */
+        /** @hidden */
+        @serialize()
+        public _generateMipMaps: boolean;
+
+        /** @hidden **/
         public _effect: Effect;
 
+        /** @hidden */
+        public _textures: { [key: string]: Texture } = {};
+
+        @serialize()
+        private _size: number;
+        private _currentRefreshId = -1;
+        private _refreshRate = 1;
+        private _vertexBuffers: { [key: string]: Nullable<VertexBuffer> } = {};
+        private _indexBuffer: Nullable<WebGLBuffer>;
         private _uniforms = new Array<string>();
         private _samplers = new Array<string>();
         private _fragment: any;
 
-        /** @hidden */
-        public _textures: { [key: string]: Texture } = {};
         private _floats: { [key: string]: number } = {};
         private _ints: { [key: string]: number } = {};
         private _floatsArrays: { [key: string]: number[] } = {};
@@ -52,6 +60,19 @@
         private _contentUpdateId = -1;
         private _contentData: Nullable<ArrayBufferView>;
 
+        /**
+         * Instantiates a new procedural texture.
+         * Procedural texturing is a way to programmatically create a texture. There are 2 types of procedural textures: code-only, and code that references some classic 2D images, sometimes called 'refMaps' or 'sampler' images.
+         * This is the base class of any Procedural texture and contains most of the shareable code.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_procedural_textures
+         * @param name  Define the name of the texture
+         * @param size Define the size of the texture to create
+         * @param fragment Define the fragment shader to use to generate the texture or null if it is defined later
+         * @param scene Define the scene the texture belongs to
+         * @param fallbackTexture Define a fallback texture in case there were issues to create the custom texture
+         * @param generateMipMaps Define if the texture should creates mip maps or not
+         * @param isCube Define if the texture is a cube texture or not (this will render each faces of the cube)
+         */
         constructor(name: string, size: any, fragment: any, scene: Nullable<Scene>, fallbackTexture: Nullable<Texture> = null, generateMipMaps = true, public isCube = false) {
             super(null, scene, !generateMipMaps);
 
@@ -140,6 +161,10 @@
             }
         }
 
+        /**
+         * Resets the texture in order to recreate its associated resources.
+         * This can be called in case of context loss
+         */
         public reset(): void {
             if (this._effect === undefined) {
                 return;
@@ -153,7 +178,10 @@
             return "";
         }
 
-
+        /**
+         * Is the texture ready to be used ? (rendered at least once)
+         * @returns true if ready, otherwise, false.
+         */
         public isReady(): boolean {
             var engine = this._engine;
             var shaders;
@@ -201,20 +229,31 @@
             return this._effect.isReady();
         }
 
+        /**
+         * Resets the refresh counter of the texture and start bak from scratch.
+         * Could be usefull to regenerate the texture if it is setup to render only once.
+         */
         public resetRefreshCounter(): void {
             this._currentRefreshId = -1;
         }
 
+        /**
+         * Set the fragment shader to use in order to render the texture.
+         * @param fragment This can be set to a path (into the shader store) or to a json object containing a fragmentElement property.
+         */
         public setFragment(fragment: any) {
             this._fragment = fragment;
         }
 
+        /**
+         * Define the refresh rate of the texture or the rendering frequency.
+         * Use 0 to render just once, 1 to render on every frame, 2 to render every two frames and so on...
+         */
         @serialize()
         public get refreshRate(): number {
             return this._refreshRate;
         }
 
-        // Use 0 to render just once, 1 to render on every frame, 2 to render every two frames and so on...
         public set refreshRate(value: number) {
             this._refreshRate = value;
             this.resetRefreshCounter();
@@ -247,10 +286,19 @@
             return false;
         }
 
+        /**
+         * Get the size the texture is rendering at.
+         * @returns the size (texture is always squared)
+         */
         public getRenderSize(): number {
             return this._size;
         }
 
+        /**
+         * Resize the texture to new value.
+         * @param size Define the new size the texture should have
+         * @param generateMipMaps Define whether the new texture should create mip maps
+         */
         public resize(size: number, generateMipMaps: boolean): void {
             if (this._fallbackTextureUsed) {
                 return;
@@ -270,6 +318,12 @@
             }
         }
 
+        /**
+         * Set a texture in the shader program used to render.
+         * @param name Define the name of the uniform samplers as defined in the shader
+         * @param texture Define the texture to bind to this sampler
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setTexture(name: string, texture: Texture): ProceduralTexture {
             if (this._samplers.indexOf(name) === -1) {
                 this._samplers.push(name);
@@ -279,6 +333,12 @@
             return this;
         }
 
+        /**
+         * Set a float in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setFloat(name: string, value: number): ProceduralTexture {
             this._checkUniform(name);
             this._floats[name] = value;
@@ -287,10 +347,10 @@
         }
 
         /**
-         * Set the value of an uniform to an integer value
-         * @param name defines the name of the uniform
-         * @param value defines the value to set
-         * @returns the current procedural texture
+         * Set a int in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
          */
         public setInt(name: string, value: number): ProceduralTexture {
             this._checkUniform(name);
@@ -299,6 +359,12 @@
             return this;
         }
 
+        /**
+         * Set an array of floats in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setFloats(name: string, value: number[]): ProceduralTexture {
             this._checkUniform(name);
             this._floatsArrays[name] = value;
@@ -306,6 +372,12 @@
             return this;
         }
 
+        /**
+         * Set a vec3 in the shader from a Color3.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setColor3(name: string, value: Color3): ProceduralTexture {
             this._checkUniform(name);
             this._colors3[name] = value;
@@ -313,6 +385,12 @@
             return this;
         }
 
+        /**
+         * Set a vec4 in the shader from a Color4.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setColor4(name: string, value: Color4): ProceduralTexture {
             this._checkUniform(name);
             this._colors4[name] = value;
@@ -320,6 +398,12 @@
             return this;
         }
 
+        /**
+         * Set a vec2 in the shader from a Vector2.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setVector2(name: string, value: Vector2): ProceduralTexture {
             this._checkUniform(name);
             this._vectors2[name] = value;
@@ -327,6 +411,12 @@
             return this;
         }
 
+        /**
+         * Set a vec3 in the shader from a Vector3.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setVector3(name: string, value: Vector3): ProceduralTexture {
             this._checkUniform(name);
             this._vectors3[name] = value;
@@ -334,6 +424,12 @@
             return this;
         }
 
+        /**
+         * Set a mat4 in the shader from a MAtrix.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the texture itself allowing "fluent" like uniform updates
+         */
         public setMatrix(name: string, value: Matrix): ProceduralTexture {
             this._checkUniform(name);
             this._matrices[name] = value;
@@ -341,6 +437,10 @@
             return this;
         }
 
+        /**
+         * Render the texture to its associated render target.
+         * @param useCameraPostProcess Define if camera post process should be applied to the texture
+         */
         public render(useCameraPostProcess?: boolean): void {
             var scene = this.getScene();
 
@@ -447,6 +547,10 @@
             this.onGeneratedObservable.notifyObservers(this);
         }
 
+        /**
+         * Clone the texture.
+         * @returns the cloned texture
+         */
         public clone(): ProceduralTexture {
             var textureSize = this.getSize();
             var newTexture = new ProceduralTexture(this.name, textureSize.width, this._fragment, <Scene>this.getScene(), this._fallbackTexture, this._generateMipMaps);
@@ -461,6 +565,9 @@
             return newTexture;
         }
 
+        /**
+         * Dispose the texture and release its asoociated resources.
+         */
         public dispose(): void {
             let scene = this.getScene();
 

src/Materials/Textures/babylon.baseTexture.ts

@@ -1,12 +1,27 @@
 module BABYLON {
+    /**
+     * Base class of all the textures in babylon.
+     * It groups all the common properties the materials, post process, lights... might need 
+     * in order to make a correct use of the texture.
+     */
     export class BaseTexture {
+        /**
+         * Default anisotropic filtering level for the application.
+         * It is set to 4 as a good tradeoff between perf and quality.
+         */
         public static DEFAULT_ANISOTROPIC_FILTERING_LEVEL = 4;
 
+        /**
+         * Define the name of the texture.
+         */
         @serialize()
         public name: string;
 
         @serialize("hasAlpha")
         private _hasAlpha = false;
+        /**
+         * Define if the texture is having a usable alpha value (can be use for transparency or glossiness for instance).
+         */
         public set hasAlpha(value: boolean) {
             if (this._hasAlpha === value) {
                 return;
@@ -20,12 +35,24 @@
             return this._hasAlpha;
         }
 
+        /**
+         * Defines if the alpha value should be determined via the rgb values.
+         * If true the luminance of the pixel might be used to find the corresponding alpha value.
+         */
         @serialize()
         public getAlphaFromRGB = false;
 
+        /**
+         * Intensity or strength of the texture.
+         * It is commonly used by materials to fine tune the intensity of the texture
+         */
         @serialize()
         public level = 1;
 
+        /**
+         * Define the UV chanel to use starting from 0 and defaulting to 0.
+         * This is part of the texture as textures usually maps to one uv set.
+         */
         @serialize()
         public coordinatesIndex = 0;
 
@@ -91,15 +118,31 @@
         @serialize()
         public wrapR = Texture.WRAP_ADDRESSMODE;
 
+        /**
+         * With compliant hardware and browser (supporting anisotropic filtering)
+         * this defines the level of anisotropic filtering in the texture.
+         * The higher the better but the slower. This defaults to 4 as it seems to be the best tradeoff.
+         */
         @serialize()
         public anisotropicFilteringLevel = BaseTexture.DEFAULT_ANISOTROPIC_FILTERING_LEVEL;
 
+        /**
+         * Define if the texture is a cube texture or if false a 2d texture.
+         */
         @serialize()
         public isCube = false;
 
+        /**
+         * Define if the texture is a 3d texture (webgl 2) or if false a 2d texture.
+         */
         @serialize()
         public is3D = false;
 
+        /**
+         * Define if the texture contains data in gamma space (most of the png/jpg aside bump).
+         * HDR texture are usually stored in linear space.
+         * This only impacts the PBR and Background materials
+         */
         @serialize()
         public gammaSpace = true;
 
@@ -110,12 +153,21 @@
             return this._texture != null && this._texture._isRGBD;
         }
 
+        /**
+         * Is Z inverted in the texture (useful in a cube texture).
+         */
         @serialize()
         public invertZ = false;
 
+        /**
+         * @hidden
+         */
         @serialize()
         public lodLevelInAlpha = false;
 
+        /**
+         * With prefiltered texture, defined the offset used during the prefiltering steps.
+         */
         @serialize()
         public get lodGenerationOffset(): number {
             if (this._texture) return this._texture._lodGenerationOffset;
@@ -126,6 +178,9 @@
             if (this._texture) this._texture._lodGenerationOffset = value;
         }
 
+        /**
+         * With prefiltered texture, defined the scale used during the prefiltering steps.
+         */
         @serialize()
         public get lodGenerationScale(): number {
             if (this._texture) return this._texture._lodGenerationScale;
@@ -136,9 +191,15 @@
             if (this._texture) this._texture._lodGenerationScale = value;
         }
 
+        /**
+         * Define if the texture is a render target.
+         */
         @serialize()
         public isRenderTarget = false;
 
+        /**
+         * Define the unique id of the texture in the scene.
+         */
         public get uid(): string {
             if (!this._uid) {
                 this._uid = Tools.RandomId();
@@ -146,14 +207,25 @@
             return this._uid;
         }
 
+        /**
+         * Return a string representation of the texture.
+         * @returns the texture as a string
+         */
         public toString(): string {
             return this.name;
         }
 
+        /**
+         * Get the class name of the texture.
+         * @returns "BaseTexture"
+         */
         public getClassName(): string {
             return "BaseTexture";
         }
 
+        /**
+         * Define the list of animation attached to the texture.
+         */
         public animations = new Array<Animation>();
 
         /**
@@ -162,6 +234,10 @@
         public onDisposeObservable = new Observable<BaseTexture>();
 
         private _onDisposeObserver: Nullable<Observer<BaseTexture>>;
+        /**
+         * Callback triggered when the texture has been disposed.
+         * Kept for back compatibility, you can use the onDisposeObservable instead.
+         */
         public set onDispose(callback: () => void) {
             if (this._onDisposeObserver) {
                 this.onDisposeObservable.remove(this._onDisposeObserver);
@@ -169,6 +245,9 @@
             this._onDisposeObserver = this.onDisposeObservable.add(callback);
         }
 
+        /**
+         * Define the current state of the loading sequence when in delayed load mode.
+         */
         public delayLoadState = Engine.DELAYLOADSTATE_NONE;
 
         private _scene: Nullable<Scene>;
@@ -177,10 +256,21 @@
         public _texture: Nullable<InternalTexture>;
         private _uid: Nullable<string>;
 
+        /**
+         * Define if the texture is preventinga material to render or not.
+         * If not and the texture is not ready, the engine will use a default black texture instead.
+         */
         public get isBlocking(): boolean {
             return true;
         }
 
+        /**
+         * Instantiates a new BaseTexture.
+         * Base class of all the textures in babylon.
+         * It groups all the common properties the materials, post process, lights... might need 
+         * in order to make a correct use of the texture.
+         * @param scene Define the scene the texture blongs to
+         */
         constructor(scene: Nullable<Scene>) {
             this._scene = scene || Engine.LastCreatedScene;
             if (this._scene) {
@@ -190,26 +280,50 @@
             this._uid = null;
         }
 
+        /**
+         * Get the scene the texture belongs to.
+         * @returns the scene or null if undefined
+         */
         public getScene(): Nullable<Scene> {
             return this._scene;
         }
 
+        /**
+         * Get the texture transform matrix used to offset tile the texture for istance.
+         * @returns the transformation matrix
+         */
         public getTextureMatrix(): Matrix {
             return Matrix.IdentityReadOnly;
         }
 
+        /**
+         * Get the texture reflection matrix used to rotate/transform the reflection.
+         * @returns the reflection matrix
+         */
         public getReflectionTextureMatrix(): Matrix {
             return Matrix.IdentityReadOnly;
         }
 
+        /**
+         * Get the underlying lower level texture from Babylon.
+         * @returns the insternal texture
+         */
         public getInternalTexture(): Nullable<InternalTexture> {
             return this._texture;
         }
 
+        /**
+         * Get if the texture is ready to be consumed (either it is ready or it is not blocking)
+         * @returns true if ready or not blocking
+         */
         public isReadyOrNotBlocking(): boolean {
             return !this.isBlocking || this.isReady();
         }
 
+        /**
+         * Get if the texture is ready to be used (downloaded, converted, mip mapped...).
+         * @returns true if fully ready
+         */
         public isReady(): boolean {
             if (this.delayLoadState === Engine.DELAYLOADSTATE_NOTLOADED) {
                 this.delayLoad();
@@ -224,6 +338,10 @@
         }
 
         private _cachedSize: ISize = Size.Zero();
+        /**
+         * Get the size of the texture.
+         * @returns the texture size.
+         */
         public getSize(): ISize {
             if (this._texture) {
                 if (this._texture.width) {
@@ -242,6 +360,11 @@
             return this._cachedSize;
         }
 
+        /**
+         * Get the base size of the texture.
+         * It can be different from the size if the texture has been resized for POT for instance
+         * @returns the base size
+         */
         public getBaseSize(): ISize {
             if (!this.isReady() || !this._texture)
                 return Size.Zero();
@@ -253,9 +376,16 @@
             return new Size(this._texture.baseWidth, this._texture.baseHeight);
         }
 
+        /**
+         * Scales the texture if is `canRescale()`
+         * @param ratio the resize factor we want to use to rescale
+         */
         public scale(ratio: number): void {
         }
 
+        /**
+         * Get if the texture can rescale.
+         */
         public get canRescale(): boolean {
             return false;
         }
@@ -286,13 +416,23 @@
 
         }
 
+        /**
+         * Triggers the load sequence in delayed load mode.
+         */
         public delayLoad(): void {
         }
 
+        /**
+         * Clones the texture.
+         * @returns the cloned texture
+         */
         public clone(): Nullable<BaseTexture> {
             return null;
         }
 
+        /**
+         * Get the texture underlying type (INT, FLOAT...)
+         */
         public get textureType(): number {
             if (!this._texture) {
                 return Engine.TEXTURETYPE_UNSIGNED_INT;
@@ -301,6 +441,9 @@
             return (this._texture.type !== undefined) ? this._texture.type : Engine.TEXTURETYPE_UNSIGNED_INT;
         }
 
+        /**
+         * Get the texture underlying format (RGB, RGBA...)
+         */
         public get textureFormat(): number {
             if (!this._texture) {
                 return Engine.TEXTUREFORMAT_RGBA;
@@ -349,6 +492,9 @@
             return engine._readTexturePixels(this._texture, width, height, -1, level, buffer);
         }
 
+        /**
+         * Release and destroy the underlying lower level texture aka internalTexture.
+         */
         public releaseInternalTexture(): void {
             if (this._texture) {
                 this._texture.dispose();
@@ -356,6 +502,11 @@
             }
         }
 
+        /**
+         * Get the polynomial representation of the texture data.
+         * This is mainly use as a fast way to recover IBL Diffuse irradiance data.
+         * @see https://learnopengl.com/PBR/IBL/Diffuse-irradiance
+         */
         public get sphericalPolynomial(): Nullable<SphericalPolynomial> {
             if (!this._texture || !CubeMapToSphericalPolynomialTools || !this.isReady()) {
                 return null;
@@ -375,6 +526,7 @@
             }
         }
 
+        /** @hidden */
         public get _lodTextureHigh(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureHigh;
@@ -382,6 +534,7 @@
             return null;
         }
 
+        /** @hidden */
         public get _lodTextureMid(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureMid;
@@ -389,6 +542,7 @@
             return null;
         }
 
+        /** @hidden */
         public get _lodTextureLow(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureLow;
@@ -396,6 +550,9 @@
             return null;
         }
 
+        /**
+         * Dispose the texture and release its associated resources.
+         */
         public dispose(): void {
             if (!this._scene) {
                 return;
@@ -425,6 +582,10 @@
             this.onDisposeObservable.clear();
         }
 
+        /**
+         * Serialize the texture into a JSON representation that can be parsed later on.
+         * @returns the JSON representation of the texture
+         */
         public serialize(): any {
             if (!this.name) {
                 return null;
@@ -438,6 +599,11 @@
             return serializationObject;
         }
 
+        /**
+         * Helper function to be called back once a list of texture contains only ready textures.
+         * @param textures Define the list of textures to wait for
+         * @param callback Define the callback triggered once the entire list will be ready
+         */
         public static WhenAllReady(textures: BaseTexture[], callback: () => void): void {
             let numRemaining = textures.length;
             if (numRemaining === 0) {

src/Materials/Textures/babylon.colorGradingTexture.ts

@@ -4,9 +4,9 @@ module BABYLON {
      * This represents a color grading texture. This acts as a lookup table LUT, useful during post process
      * It can help converting any input color in a desired output one. This can then be used to create effects
      * from sepia, black and white to sixties or futuristic rendering...
-     * 
+     *
      * The only supported format is currently 3dl.
-     * More information on LUT: https://en.wikipedia.org/wiki/3D_lookup_table/
+     * More information on LUT: https://en.wikipedia.org/wiki/3D_lookup_table
      */
     export class ColorGradingTexture extends BaseTexture {
         /**
@@ -28,7 +28,7 @@ module BABYLON {
 
         /**
          * Instantiates a ColorGradingTexture from the following parameters.
-         * 
+         *
          * @param url The location of the color gradind data (currently only supporting 3dl)
          * @param scene The scene the texture will be used in
          */
@@ -250,4 +250,4 @@ module BABYLON {
             return serializationObject;
         }
     }
-}
+}

src/Materials/Textures/babylon.hdrCubeTexture.ts

@@ -257,14 +257,29 @@ module BABYLON {
             }
         }
 
+        /**
+         * Get the texture reflection matrix used to rotate/transform the reflection.
+         * @returns the reflection matrix
+         */
         public getReflectionTextureMatrix(): Matrix {
             return this._textureMatrix;
         }
 
+        /**
+         * Set the texture reflection matrix used to rotate/transform the reflection.
+         * @param value Define the reflection matrix to set
+         */
         public setReflectionTextureMatrix(value: Matrix): void {
             this._textureMatrix = value;
         }
 
+        /**
+         * Parses a JSON representation of an HDR Texture in order to create the texture
+         * @param parsedTexture Define the JSON representation
+         * @param scene Define the scene the texture should be created in
+         * @param rootUrl Define the root url in case we need to load relative dependencies
+         * @returns the newly created texture after parsing
+         */
         public static Parse(parsedTexture: any, scene: Scene, rootUrl: string): Nullable<HDRCubeTexture> {
             var texture = null;
             if (parsedTexture.name && !parsedTexture.isRenderTarget) {

src/Materials/Textures/babylon.internalTexture.ts

@@ -87,11 +87,11 @@ module BABYLON {
          */
         public samples: number;
         /**
-         * Gets the type of the texture
+         * Gets the type of the texture (int, float...)
          */
         public type: number;
         /**
-         * Gets the format of the texture 
+         * Gets the format of the texture (RGB, RGBA...)
          */
         public format: number;
         /**

src/Materials/Textures/babylon.mirrorTexture.ts

@@ -1,18 +1,22 @@
 module BABYLON {
+    /**
+     * Mirror texture can be used to simulate the view from a mirror in a scene.
+     * It will dynamically be rendered every frame to adapt to the camera point of view.
+     * You can then easily use it as a reflectionTexture on a flat surface.
+     * In case the surface is not a plane, please consider relying on reflection probes.
+     * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+     */
     export class MirrorTexture extends RenderTargetTexture {
+        /**
+         * Define the reflection plane we want to use. The mirrorPlane is usually set to the constructed reflector. 
+         * It is possible to directly set the mirrorPlane by directly using a BABYLON.Plane(a, b, c, d) where a, b and c give the plane normal vector (a, b, c) and d is a scalar displacement from the mirrorPlane to the origin. However in all but the very simplest of situations it is more straight forward to set it to the reflector as stated in the doc.
+         * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+         */
         public mirrorPlane = new Plane(0, 1, 0, 1);
 
-        private _transformMatrix = Matrix.Zero();
-        private _mirrorMatrix = Matrix.Zero();
-        private _savedViewMatrix: Matrix;
-
-        private _blurX: Nullable<BlurPostProcess>;
-        private _blurY: Nullable<BlurPostProcess>;
-        private _adaptiveBlurKernel = 0;
-        private _blurKernelX = 0;
-        private _blurKernelY = 0;
-        private _blurRatio = 1.0;
-
+        /**
+         * Define the blur ratio used to blur the reflection if needed.
+         */
         public set blurRatio(value: number) {
             if (this._blurRatio === value) {
                 return;
@@ -26,16 +30,28 @@
             return this._blurRatio;
         }
 
+        /**
+         * Define the adaptive blur kernel used to blur the reflection if needed.
+         * This will autocompute the closest best match for the `blurKernel`
+         */
         public set adaptiveBlurKernel(value: number) {
             this._adaptiveBlurKernel = value;
             this._autoComputeBlurKernel();
         }
 
+        /**
+         * Define the blur kernel used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernel(value: number) {
             this.blurKernelX = value;
             this.blurKernelY = value;
         }
 
+        /**
+         * Define the blur kernel on the X Axis used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernelX(value: number) {
             if (this._blurKernelX === value) {
                 return;
@@ -49,6 +65,10 @@
             return this._blurKernelX;
         }
 
+        /**
+         * Define the blur kernel on the Y Axis used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernelY(value: number) {
             if (this._blurKernelY === value) {
                 return;
@@ -83,11 +103,39 @@
                 this._autoComputeBlurKernel();
             }
         }
+
         private _updateGammaSpace(){
             this.gammaSpace = !this.scene.imageProcessingConfiguration.isEnabled || !this.scene.imageProcessingConfiguration.applyByPostProcess;
         }
 
         private _imageProcessingConfigChangeObserver:Nullable<Observer<ImageProcessingConfiguration>>;
+
+        private _transformMatrix = Matrix.Zero();
+        private _mirrorMatrix = Matrix.Zero();
+        private _savedViewMatrix: Matrix;
+
+        private _blurX: Nullable<BlurPostProcess>;
+        private _blurY: Nullable<BlurPostProcess>;
+        private _adaptiveBlurKernel = 0;
+        private _blurKernelX = 0;
+        private _blurKernelY = 0;
+        private _blurRatio = 1.0;
+
+        /**
+         * Instantiates a Mirror Texture.
+         * Mirror texture can be used to simulate the view from a mirror in a scene.
+         * It will dynamically be rendered every frame to adapt to the camera point of view.
+         * You can then easily use it as a reflectionTexture on a flat surface.
+         * In case the surface is not a plane, please consider relying on reflection probes.
+         * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+         * @param name 
+         * @param size 
+         * @param scene 
+         * @param generateMipMaps 
+         * @param type 
+         * @param samplingMode 
+         * @param generateDepthBuffer 
+         */
         constructor(name: string, size: number | { width: number, height: number } | { ratio: number }, private scene: Scene, generateMipMaps?: boolean, type: number = Engine.TEXTURETYPE_UNSIGNED_INT, samplingMode = Texture.BILINEAR_SAMPLINGMODE, generateDepthBuffer = true) {
             super(name, size, scene, generateMipMaps, true, type, false, samplingMode, generateDepthBuffer);
 
@@ -160,6 +208,10 @@
             }
         }
 
+        /**
+         * Clone the mirror texture.
+         * @returns the cloned texture
+         */
         public clone(): MirrorTexture {
             let scene = this.getScene();
 
@@ -191,6 +243,10 @@
             return newTexture;
         }
 
+        /**
+         * Serialize the texture to a JSON representation you could use in Parse later on
+         * @returns the serialized JSON representation
+         */
         public serialize(): any {
             if (!this.name) {
                 return null;
@@ -203,6 +259,9 @@
             return serializationObject;
         }
 
+        /**
+         * Dispose the texture and release its associated resources.
+         */
         public dispose(){
             super.dispose();
             this.scene.imageProcessingConfiguration.onUpdateParameters.remove(this._imageProcessingConfigChangeObserver);

src/Materials/Textures/babylon.multiRenderTarget.ts

@@ -1,34 +1,83 @@
 module BABYLON {
+    /**
+     * Creation options of the multi render target texture.
+     */
     export interface IMultiRenderTargetOptions {
+        /**
+         * Define if the texture needs to create mip maps after render.
+         */
         generateMipMaps?: boolean,
+        /**
+         * Define the types of all the draw buffers we want to create
+         */
         types?: number[],
+        /**
+         * Define the sampling modes of all the draw buffers we want to create
+         */
         samplingModes?: number[],
+        /**
+         * Define if a depth buffer is required
+         */
         generateDepthBuffer?: boolean,
+        /**
+         * Define if a stencil buffer is required
+         */
         generateStencilBuffer?: boolean,
+        /**
+         * Define if a depth texture is required instead of a depth buffer
+         */
         generateDepthTexture?: boolean,
+        /**
+         * Define the number of desired draw buffers
+         */
         textureCount?: number,
+        /**
+         * Define if aspect ratio should be adapted to the texture or stay the scene one
+         */
         doNotChangeAspectRatio?: boolean,
+        /**
+         * Define the default type of the buffers we are creating
+         */
         defaultType?: number
     };
+
+    /**
+     * A multi render target, like a render target provides the ability to render to a texture.
+     * Unlike the render target, it can render to several draw buffers in one draw.
+     * This is specially interesting in deferred rendering or for any effects requiring more than
+     * just one color from a single pass.
+     */
     export class MultiRenderTarget extends RenderTargetTexture {
 
         private _internalTextures: InternalTexture[];
         private _textures: Texture[];
+        private _multiRenderTargetOptions: IMultiRenderTargetOptions;
 
+        /**
+         * Get if draw buffers are currently supported by the used hardware and browser.
+         */
         public get isSupported(): boolean {
             return this._engine.webGLVersion > 1 || this._engine.getCaps().drawBuffersExtension;
         }
 
-        private _multiRenderTargetOptions: IMultiRenderTargetOptions;
-
+        /**
+         * Get the list of textures generated by the multi render target.
+         */
         public get textures(): Texture[] {
             return this._textures;
         }
 
+        /**
+         * Get the depth texture generated by the multi render target if options.generateDepthTexture has been set
+         */
         public get depthTexture(): Texture {
             return this._textures[this._textures.length - 1];
         }
 
+        /**
+         * Set the wrapping mode on U of all the textures we are rendering to.
+         * Can be any of the Texture. (CLAMP_ADDRESSMODE, MIRROR_ADDRESSMODE or WRAP_ADDRESSMODE)
+         */
         public set wrapU(wrap: number) {
             if (this._textures) {
                 for (var i = 0; i < this._textures.length; i++) {
@@ -37,6 +86,10 @@ module BABYLON {
             }
         }
 
+        /**
+         * Set the wrapping mode on V of all the textures we are rendering to.
+         * Can be any of the Texture. (CLAMP_ADDRESSMODE, MIRROR_ADDRESSMODE or WRAP_ADDRESSMODE)
+         */
         public set wrapV(wrap: number) {
             if (this._textures) {
                 for (var i = 0; i < this._textures.length; i++) {
@@ -45,6 +98,18 @@ module BABYLON {
             }
         }
 
+        /**
+         * Instantiate a new multi render target texture.
+         * A multi render target, like a render target provides the ability to render to a texture.
+         * Unlike the render target, it can render to several draw buffers in one draw.
+         * This is specially interesting in deferred rendering or for any effects requiring more than
+         * just one color from a single pass.
+         * @param name Define the name of the texture
+         * @param size Define the size of the buffers to render to
+         * @param count Define the number of target we are rendering into
+         * @param scene Define the scene the texture belongs to
+         * @param options Define the options used to create the multi render target
+         */
         constructor(name: string, size: any, count: number, scene: Scene, options?: IMultiRenderTargetOptions) {
             var generateMipMaps = options && options.generateMipMaps ? options.generateMipMaps : false;
             var generateDepthTexture = options && options.generateDepthTexture ? options.generateDepthTexture : false;
@@ -124,6 +189,9 @@ module BABYLON {
             this._texture = this._internalTextures[0];
         }
 
+        /**
+         * Define the number of samples used if MSAA is enabled.
+         */
         public get samples(): number {
             return this._samples;
         }
@@ -136,6 +204,11 @@ module BABYLON {
             this._samples = this._engine.updateMultipleRenderTargetTextureSampleCount(this._internalTextures, value);
         }
 
+        /**
+         * Resize all the textures in the multi render target.
+         * Be carrefull as it will recreate all the data in the new texture.
+         * @param size Define the new size
+         */
         public resize(size: any) {
             this.releaseInternalTextures();
             this._internalTextures = this._engine.createMultipleRenderTarget(size, this._multiRenderTargetOptions);
@@ -148,12 +221,18 @@ module BABYLON {
             });
         }
 
+        /**
+         * Dispose the render targets and their associated resources
+         */
         public dispose(): void {
             this.releaseInternalTextures();
 
             super.dispose();
         }
 
+        /**
+         * Release all the underlying texture used as draw buffers.
+         */
         public releaseInternalTextures(): void {
             if (!this._internalTextures) {
                 return;

src/Materials/Textures/babylon.rawTexture.ts

@@ -1,6 +1,27 @@
 module BABYLON {
+    /**
+     * Raw texture can help creating a texture directly from an array of data.
+     * This can be super useful if you either get the data from an uncompressed source or
+     * if you wish to create your texture pixel by pixel.
+     */
     export class RawTexture extends Texture {
         private _engine: Engine;
+
+        /**
+         * Instantiates a new RawTexture.
+         * Raw texture can help creating a texture directly from an array of data.
+         * This can be super useful if you either get the data from an uncompressed source or
+         * if you wish to create your texture pixel by pixel.
+         * @param data define the array of data to use to create the texture
+         * @param width define the width of the texture
+         * @param height define the height of the texture
+         * @param format define the format of the data (RGB, RGBA... Engine.TEXTUREFORMAT_xxx)
+         * @param scene  define the scene the texture belongs to
+         * @param generateMipMaps define whether mip maps should be generated or not
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @param type define the format of the data (int, float... Engine.TEXTURETYPE_xxx)
+         */
         constructor(data: ArrayBufferView, width: number, height: number, public format: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
             super(null, scene, !generateMipMaps, invertY);
             this._engine = scene.getEngine();
@@ -10,33 +31,102 @@
             this.wrapV = Texture.CLAMP_ADDRESSMODE;
         }
 
+        /**
+         * Updates the texture underlying data.
+         * @param data Define the new data of the texture
+         */
         public update(data: ArrayBufferView): void {
             this._engine.updateRawTexture(this._texture, data, this._texture!.format, this._texture!.invertY, undefined, this._texture!.type);
         }
 
-        // Statics
+        /**
+         * Creates a luminance texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the luminance texture
+         */
         public static CreateLuminanceTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_LUMINANCE, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates a luminance alpha texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the luminance alpha texture
+         */
         public static CreateLuminanceAlphaTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_LUMINANCE_ALPHA, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates an alpha texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the alpha texture
+         */
         public static CreateAlphaTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_ALPHA, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates a RGB texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the RGB alpha texture
+         */
         public static CreateRGBTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_RGB, scene, generateMipMaps, invertY, samplingMode, type);
         }
 
+        /**
+         * Creates a RGBA texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the RGBA texture
+         */
         public static CreateRGBATexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_RGBA, scene, generateMipMaps, invertY, samplingMode, type);
         }
 
+        /**
+         * Creates a R texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the R texture
+         */
         public static CreateRTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_FLOAT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_R, scene, generateMipMaps, invertY, samplingMode, type);
-        }        
+        }
     }
 }

src/Materials/Textures/babylon.refractionTexture.ts

@@ -1,14 +1,31 @@
 module BABYLON {
     /**
-    * Creates a refraction texture used by refraction channel of the standard material.
-    * @param name the texture name
-    * @param size size of the underlying texture
-    * @param scene root scene
-    */
+     * Creates a refraction texture used by refraction channel of the standard material.
+     * It is like a mirror but to see through a material.
+     * @see https://doc.babylonjs.com/how_to/reflect#refraction
+     */
     export class RefractionTexture extends RenderTargetTexture {
+        /**
+         * Define the reflection plane we want to use. The refractionPlane is usually set to the constructed refractor. 
+         * It is possible to directly set the refractionPlane by directly using a BABYLON.Plane(a, b, c, d) where a, b and c give the plane normal vector (a, b, c) and d is a scalar displacement from the refractionPlane to the origin. However in all but the very simplest of situations it is more straight forward to set it to the refractor as stated in the doc.
+         * @see https://doc.babylonjs.com/how_to/reflect#refraction
+         */
         public refractionPlane = new Plane(0, 1, 0, 1);
+
+        /**
+         * Define how deep under the surface we should see.
+         */
         public depth = 2.0;
 
+        /**
+         * Creates a refraction texture used by refraction channel of the standard material.
+         * It is like a mirror but to see through a material.
+         * @see https://doc.babylonjs.com/how_to/reflect#refraction
+         * @param name Define the texture name
+         * @param size Define the size of the underlying texture
+         * @param scene Define the scene the refraction belongs to
+         * @param generateMipMaps Define if we need to generate mips level for the refraction
+         */
         constructor(name: string, size: number, scene: Scene, generateMipMaps?: boolean) {
             super(name, size, scene, generateMipMaps, true);
 
@@ -21,6 +38,10 @@
             });
         }
 
+        /**
+         * Clone the refraction texture.
+         * @returns the cloned texture
+         */
         public clone(): RefractionTexture {
             let scene = this.getScene();
 
@@ -45,6 +66,10 @@
             return newTexture;
         }
 
+        /**
+         * Serialize the texture to a JSON representation you could use in Parse later on
+         * @returns the serialized JSON representation
+         */
         public serialize(): any {
             if (!this.name) {
                 return null;

src/Materials/Textures/babylon.renderTargetTexture.ts

@@ -41,11 +41,15 @@
         private _hookArray(array: AbstractMesh[]): void {
             var oldPush = array.push;
             array.push = (...items: AbstractMesh[]) => {
+                let wasEmpty = array.length === 0;
+
                 var result = oldPush.apply(array, items);
 
-                this.getScene()!.meshes.forEach(mesh => {
-                    mesh._markSubMeshesAsLightDirty();
-                })
+                if (wasEmpty) {
+                    this.getScene()!.meshes.forEach(mesh => {
+                        mesh._markSubMeshesAsLightDirty();
+                    });
+                }
 
                 return result;
             }
@@ -54,9 +58,11 @@
             array.splice = (index: number, deleteCount?: number) => {
                 var deleted = oldSplice.apply(array, [index, deleteCount]);
 
-                this.getScene()!.meshes.forEach(mesh => {
-                    mesh._markSubMeshesAsLightDirty();
-                })
+                if (array.length === 0) {
+                    this.getScene()!.meshes.forEach(mesh => {
+                        mesh._markSubMeshesAsLightDirty();
+                    });
+                }
 
                 return deleted;
             }
@@ -318,15 +324,21 @@
             this._samples = scene.getEngine().updateRenderTargetTextureSampleCount(this._texture, value);
         }
 
+        /**
+         * Resets the refresh counter of the texture and start bak from scratch.
+         * Could be usefull to regenerate the texture if it is setup to render only once.
+         */
         public resetRefreshCounter(): void {
             this._currentRefreshId = -1;
         }
 
+        /**
+         * Define the refresh rate of the texture or the rendering frequency.
+         * Use 0 to render just once, 1 to render on every frame, 2 to render every two frames and so on...
+         */
         public get refreshRate(): number {
             return this._refreshRate;
         }
-
-        // Use 0 to render just once, 1 to render on every frame, 2 to render every two frames and so on...
         public set refreshRate(value: number) {
             this._refreshRate = value;
             this.resetRefreshCounter();

src/Materials/Textures/babylon.videoTexture.ts

@@ -24,6 +24,11 @@
         poster?: string;
     }
 
+    /**
+     * If you want to display a video in your scene, this is the special texture for that. 
+     * This special texture works similar to other textures, with the exception of a few parameters.
+     * @see https://doc.babylonjs.com/how_to/video_texture
+     */
     export class VideoTexture extends Texture {
         /**
          * Tells whether textures will be updated automatically or user is required to call `updateTexture` manually
@@ -37,6 +42,10 @@
 
         private _onUserActionRequestedObservable: Nullable<Observable<Texture>> = null;
 
+        /**
+         * Event triggerd when a dom action is required by the user to play the video.
+         * This happens due to recent changes in browser policies preventing video to auto start.
+         */
         public get onUserActionRequestedObservable(): Observable<Texture> {
             if (!this._onUserActionRequestedObservable) {
                 this._onUserActionRequestedObservable = new Observable<Texture>();
@@ -51,7 +60,9 @@
 
         /**
          * Creates a video texture.
-         * Sample : https://doc.babylonjs.com/how_to/video_texture
+         * If you want to display a video in your scene, this is the special texture for that. 
+         * This special texture works similar to other textures, with the exception of a few parameters.
+         * @see https://doc.babylonjs.com/how_to/video_texture
          * @param {string | null} name optional name, will detect from video source, if not defined
          * @param {(string | string[] | HTMLVideoElement)} src can be used to provide an url, array of urls or an already setup HTML video element.
          * @param {BABYLON.Scene} scene is obviously the current scene.
@@ -279,6 +290,9 @@
             this.video.src = url;
         }
 
+        /**
+         * Dispose the texture and release its associated resources.
+         */
         public dispose(): void {
             super.dispose();
 
@@ -294,6 +308,12 @@
             this.video.pause();
         }
 
+        /**
+         * Creates a video texture straight from your WebCam video feed.
+         * @param scene Define the scene the texture should be created in
+         * @param onReady Define a callback to triggered once the texture will be ready
+         * @param constraints Define the constraints to use to create the web cam feed from WebRTC
+         */
         public static CreateFromWebCam(
             scene: Scene,
             onReady: (videoTexture: VideoTexture) => void,

src/Materials/babylon.fresnelParameters.ts

@@ -1,6 +1,13 @@
 module BABYLON {
+    /**
+     * This represents all the required information to add a fresnel effect on a material:
+     * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+     */
     export class FresnelParameters {
         private _isEnabled = true;
+        /**
+         * Define if the fresnel effect is enable or not.
+         */
         public get isEnabled(): boolean {
             return this._isEnabled;
         }
@@ -13,11 +20,30 @@
             Engine.MarkAllMaterialsAsDirty(Material.FresnelDirtyFlag | Material.MiscDirtyFlag);
         }   
 
+        /**
+         * Define the color used on edges (grazing angle)
+         */
         public leftColor = Color3.White();
+
+        /**
+         * Define the color used on center
+         */
         public rightColor = Color3.Black();
+
+        /**
+         * Define bias applied to computed fresnel term
+         */
         public bias = 0;
+
+        /**
+         * Defined the power exponent applied to fresnel term
+         */
         public power = 1;
 
+        /**
+         * Clones the current fresnel and its valuues
+         * @returns a clone fresnel configuration
+         */
         public clone(): FresnelParameters {
             var newFresnelParameters = new FresnelParameters();
 
@@ -26,6 +52,10 @@
             return newFresnelParameters;
         }
 
+        /**
+         * Serializes the current fresnel parameters to a JSON representation.
+         * @return the JSON serialization
+         */
         public serialize(): any {
             var serializationObject: any = {};
 
@@ -38,6 +68,11 @@
             return serializationObject;
         }
 
+        /**
+         * Parse a JSON object and deserialize it to a new Fresnel parameter object.
+         * @param parsedFresnelParameters Define the JSON representation
+         * @returns the parsed parameters
+         */
         public static Parse(parsedFresnelParameters: any): FresnelParameters {
             var fresnelParameters = new FresnelParameters();
 

src/Materials/babylon.imageProcessingConfiguration.ts

@@ -366,13 +366,17 @@ module BABYLON {
             this.onUpdateParameters.notifyObservers(this);
         }
 
+        /**
+         * Gets the current class name.
+         * @return "ImageProcessingConfiguration"
+         */
         public getClassName(): string {
             return "ImageProcessingConfiguration";
         }
 
         /**
          * Prepare the list of uniforms associated with the Image Processing effects.
-         * @param uniformsList The list of uniforms used in the effect
+         * @param uniforms The list of uniforms used in the effect
          * @param defines the list of defines currently in use
          */
         public static PrepareUniforms(uniforms: string[], defines: IImageProcessingConfigurationDefines): void {
@@ -397,7 +401,7 @@ module BABYLON {
 
         /**
          * Prepare the list of samplers associated with the Image Processing effects.
-         * @param uniformsList The list of uniforms used in the effect
+         * @param samplersList The list of uniforms used in the effect
          * @param defines the list of defines currently in use
          */
         public static PrepareSamplers(samplersList: string[], defines: IImageProcessingConfigurationDefines): void {
@@ -409,6 +413,7 @@ module BABYLON {
         /**
          * Prepare the list of defines associated to the shader.
          * @param defines the list of defines to complete
+         * @param forPostProcess Define if we are currently in post process mode or not
          */
         public prepareDefines(defines: IImageProcessingConfigurationDefines, forPostProcess: boolean = false): void {
             if (forPostProcess !== this.applyByPostProcess || !this._isEnabled) {
@@ -453,6 +458,7 @@ module BABYLON {
 
         /**
          * Returns true if all the image processing information are ready.
+         * @returns True if ready, otherwise, false
          */
         public isReady() {
             // Color Grading texure can not be none blocking.
@@ -462,6 +468,7 @@ module BABYLON {
         /**
          * Binds the image processing to the shader.
          * @param effect The effect to bind to
+         * @param aspectRatio Define the current aspect ratio of the effect
          */
         public bind(effect: Effect, aspectRatio = 1): void {
             // Color Curves

src/Materials/babylon.materialHelper.ts

@@ -24,10 +24,10 @@ module BABYLON {
 
         /**
          * 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.
+         * UVs are shared as much as we can accross channels 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
+         * @param key The channel key "diffuse", "specular"... used in the shader
          */
         public static PrepareDefinesForMergedUV(texture: BaseTexture, defines: any, key: string): void {
             defines._needUVs = true;
@@ -48,7 +48,7 @@ module BABYLON {
          * 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
+         * @param key The channel key "diffuse", "specular"... used in the shader
          */
         public static BindTextureMatrix(texture: BaseTexture, uniformBuffer: UniformBuffer, key: string): void {
             var matrix = texture.getTextureMatrix();

src/Materials/babylon.multiMaterial.ts

@@ -1,6 +1,16 @@
 module BABYLON {
+    /**
+     * A multi-material is used to apply different materials to different parts of the same object without the need of 
+     * separate meshes. This can be use to improve performances.
+     * @see http://doc.babylonjs.com/how_to/multi_materials
+     */
     export class MultiMaterial extends Material {
         private _subMaterials: Nullable<Material>[];
+
+        /**
+         * Gets or Sets the list of Materials used within the multi material.
+         * They need to be ordered according to the submeshes order in the associated mesh
+         */
         public get subMaterials(): Nullable<Material>[] {
             return this._subMaterials;
         }
@@ -10,6 +20,14 @@
             this._hookArray(value);
         }
 
+        /**
+         * Instantiates a new Multi Material
+         * A multi-material is used to apply different materials to different parts of the same object without the need of 
+         * separate meshes. This can be use to improve performances.
+         * @see http://doc.babylonjs.com/how_to/multi_materials
+         * @param name Define the name in the scene
+         * @param scene Define the scene the material belongs to
+         */
         constructor(name: string, scene: Scene) {
             super(name, scene, true);
 
@@ -40,7 +58,11 @@
             }
         }
 
-        // Properties
+        /**
+         * Get one of the submaterial by its index in the submaterials array
+         * @param index The index to look the sub material at
+         * @returns The Material if the index has been defined
+         */
         public getSubMaterial(index: number): Nullable<Material> {
             if (index < 0 || index >= this.subMaterials.length) {
                 return this.getScene().defaultMaterial;
@@ -49,6 +71,10 @@
             return this.subMaterials[index];
         }
 
+        /**
+         * Get the list of active textures for the whole sub materials list.
+         * @returns All the textures that will be used during the rendering
+         */
         public getActiveTextures(): BaseTexture[] {
             return super.getActiveTextures().concat(...this.subMaterials.map(subMaterial => {
                 if (subMaterial) {
@@ -59,11 +85,22 @@
             }));
         }
 
-        // Methods
+        /**
+         * Gets the current class name of the material e.g. "MultiMaterial"
+         * Mainly use in serialization.
+         * @returns the class name
+         */
         public getClassName(): string {
             return "MultiMaterial";
         }
 
+        /**
+         * Checks if the material is ready to render the requested sub mesh
+         * @param mesh Define the mesh the submesh belongs to 
+         * @param subMesh Define the sub mesh to look readyness for
+         * @param useInstances Define whether or not the material is used with instances
+         * @returns true if ready, otherwise false
+         */
         public isReadyForSubMesh(mesh: AbstractMesh, subMesh: BaseSubMesh, useInstances?: boolean): boolean {
             for (var index = 0; index < this.subMaterials.length; index++) {
                 var subMaterial = this.subMaterials[index];
@@ -84,6 +121,12 @@
             return true;
         }
 
+        /**
+         * Clones the current material and its related sub materials
+         * @param name Define the name of the newly cloned material
+         * @param cloneChildren Define if submaterial will be cloned or shared with the parent instance
+         * @returns the cloned material
+         */
         public clone(name: string, cloneChildren?: boolean): MultiMaterial {
             var newMultiMaterial = new MultiMaterial(name, this.getScene());
 
@@ -101,6 +144,10 @@
             return newMultiMaterial;
         }
 
+        /**
+         * Serializes the materials into a JSON representation.
+         * @returns the JSON representation
+         */
         public serialize(): any {
             var serializationObject: any = {};
 
@@ -124,6 +171,11 @@
             return serializationObject;
         }
 
+        /**
+         * Dispose the material and release its associated resources
+         * @param forceDisposeEffect Define if we want to force disposing the associated effect (if false the shader is not released and could be reuse later on)
+         * @param forceDisposeTextures Define if we want to force disposing the associated textures (if false, they will not be disposed and can still be use elsewhere in the app)
+         */
         public dispose(forceDisposeEffect?: boolean, forceDisposeTextures?: boolean): void {
             var scene = this.getScene();
             if (!scene) {

src/Materials/babylon.pushMaterial.ts

@@ -1,4 +1,8 @@
 module BABYLON {
+    /**
+     * Base class of materials working in push mode in babylon JS
+     * @hidden
+     */
     export class PushMaterial extends Material {
 
         protected _activeEffect: Effect;

src/Materials/babylon.shaderMaterial.ts

@@ -1,7 +1,54 @@
 module BABYLON {
+    /**
+     * Defines the options associated with the creation of a shader material.
+     */
+    export interface IShaderMaterialOptions {
+        /**
+         * Does the material work in alpha blend mode
+         */
+        needAlphaBlending: boolean;
+
+        /**
+         * Does the material work in alpha test mode
+         */
+        needAlphaTesting: boolean;
+        
+        /**
+         * The list of attribute names used in the shader
+         */
+        attributes: string[];
+
+        /**
+         * The list of unifrom names used in the shader
+         */
+        uniforms: string[];
+
+        /**
+         * The list of UBO names used in the shader
+         */
+        uniformBuffers: string[];
+
+        /**
+         * The list of sampler names used in the shader
+         */
+        samplers: string[];
+
+        /**
+         * The list of defines used in the shader
+         */
+        defines: string[];
+    }
+
+    /**
+     * The ShaderMaterial object has the necessary methods to pass data from your scene to the Vertex and Fragment Shaders and returns a material that can be applied to any mesh.
+     *
+     * This returned material effects how the mesh will look based on the code in the shaders.
+     *
+     * @see http://doc.babylonjs.com/how_to/shader_material
+     */
     export class ShaderMaterial extends Material {
         private _shaderPath: any;
-        private _options: any;
+        private _options: IShaderMaterialOptions;
         private _textures: { [name: string]: Texture } = {};
         private _textureArrays: { [name: string]: Texture[] } = {};
         private _floats: { [name: string]: number } = {};
@@ -21,29 +68,56 @@
         private _cachedWorldViewMatrix = new Matrix();
         private _renderId: number;
 
-        constructor(name: string, scene: Scene, shaderPath: any, options: any) {
+        /**
+         * Instantiate a new shader material.
+         * The ShaderMaterial object has the necessary methods to pass data from your scene to the Vertex and Fragment Shaders and returns a material that can be applied to any mesh.
+         * This returned material effects how the mesh will look based on the code in the shaders.
+         * @see http://doc.babylonjs.com/how_to/shader_material
+         * @param name Define the name of the material in the scene
+         * @param scene Define the scene the material belongs to
+         * @param shaderPath Defines  the route to the shader code in one of three ways:
+         *     - object - { vertex: "custom", fragment: "custom" }, used with BABYLON.Effect.ShadersStore["customVertexShader"] and BABYLON.Effect.ShadersStore["customFragmentShader"]
+         *     - object - { vertexElement: "vertexShaderCode", fragmentElement: "fragmentShaderCode" }, used with shader code in <script> tags
+         *     - string - "./COMMON_NAME", used with external files COMMON_NAME.vertex.fx and COMMON_NAME.fragment.fx in index.html folder.
+         * @param options Define the options used to create the shader
+         */
+        constructor(name: string, scene: Scene, shaderPath: any, options: Partial<IShaderMaterialOptions> = {}) {
             super(name, scene);
             this._shaderPath = shaderPath;
 
-            options.needAlphaBlending = options.needAlphaBlending || false;
-            options.needAlphaTesting = options.needAlphaTesting || false;
-            options.attributes = options.attributes || ["position", "normal", "uv"];
-            options.uniforms = options.uniforms || ["worldViewProjection"];
-            options.uniformBuffers = options.uniformBuffers || [];
-            options.samplers = options.samplers || [];
-            options.defines = options.defines || [];
-
-            this._options = options;
+            this._options = {
+                needAlphaBlending: false,
+                needAlphaTesting: false,
+                attributes: ["position", "normal", "uv"],
+                uniforms: ["worldViewProjection"],
+                uniformBuffers: [],
+                samplers: [],
+                defines: [],
+                ...options
+            };
         }
 
+        /**
+         * Gets the current class name of the material e.g. "ShaderMaterial"
+         * Mainly use in serialization.
+         * @returns the class name
+         */
         public getClassName(): string {
             return "ShaderMaterial";
         }
 
+        /**
+         * Specifies if the material will require alpha blending
+         * @returns a boolean specifying if alpha blending is needed
+         */
         public needAlphaBlending(): boolean {
-            return this._options.needAlphaBlending;
+            return (this.alpha < 1.0);
         }
 
+        /**
+         * Specifies if this material should be rendered in alpha test mode
+         * @returns a boolean specifying if an alpha test is needed.
+         */
         public needAlphaTesting(): boolean {
             return this._options.needAlphaTesting;
         }
@@ -54,6 +128,12 @@
             }
         }
 
+        /**
+         * Set a texture in the shader.
+         * @param name Define the name of the uniform samplers as defined in the shader
+         * @param texture Define the texture to bind to this sampler
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setTexture(name: string, texture: Texture): ShaderMaterial {
             if (this._options.samplers.indexOf(name) === -1) {
                 this._options.samplers.push(name);
@@ -63,6 +143,12 @@
             return this;
         }
 
+        /**
+         * Set a texture array in the shader.
+         * @param name Define the name of the uniform sampler array as defined in the shader
+         * @param textures Define the list of textures to bind to this sampler
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setTextureArray(name: string, textures: Texture[]): ShaderMaterial {
             if (this._options.samplers.indexOf(name) === -1) {
                 this._options.samplers.push(name);
@@ -75,6 +161,12 @@
             return this;
         }
 
+        /**
+         * Set a float in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setFloat(name: string, value: number): ShaderMaterial {
             this._checkUniform(name);
             this._floats[name] = value;
@@ -82,6 +174,12 @@
             return this;
         }
 
+        /**
+         * Set a int in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setInt(name: string, value: number): ShaderMaterial {
             this._checkUniform(name);
             this._ints[name] = value;
@@ -89,6 +187,12 @@
             return this;
         }
 
+        /**
+         * Set an array of floats in the shader.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setFloats(name: string, value: number[]): ShaderMaterial {
             this._checkUniform(name);
             this._floatsArrays[name] = value;
@@ -96,12 +200,25 @@
             return this;
         }
 
+        /**
+         * Set a vec3 in the shader from a Color3.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setColor3(name: string, value: Color3): ShaderMaterial {
             this._checkUniform(name);
             this._colors3[name] = value;
 
             return this;
         }
+
+        /**
+         * Set a vec3 array in the shader from a Color3 array.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setColor3Array(name: string, value: Color3[]): ShaderMaterial {
             this._checkUniform(name);
             this._colors3Arrays[name] = value.reduce((arr, color) => {
@@ -111,6 +228,12 @@
             return this;
         }
 
+        /**
+         * Set a vec4 in the shader from a Color4.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setColor4(name: string, value: Color4): ShaderMaterial {
             this._checkUniform(name);
             this._colors4[name] = value;
@@ -118,6 +241,12 @@
             return this;
         }
 
+        /**
+         * Set a vec2 in the shader from a Vector2.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setVector2(name: string, value: Vector2): ShaderMaterial {
             this._checkUniform(name);
             this._vectors2[name] = value;
@@ -125,6 +254,12 @@
             return this;
         }
 
+        /**
+         * Set a vec3 in the shader from a Vector3.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setVector3(name: string, value: Vector3): ShaderMaterial {
             this._checkUniform(name);
             this._vectors3[name] = value;
@@ -132,6 +267,12 @@
             return this;
         }
 
+        /**
+         * Set a vec4 in the shader from a Vector4.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setVector4(name: string, value: Vector4): ShaderMaterial {
             this._checkUniform(name);
             this._vectors4[name] = value;
@@ -139,6 +280,12 @@
             return this;
         }
 
+        /**
+         * Set a mat4 in the shader from a Matrix.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setMatrix(name: string, value: Matrix): ShaderMaterial {
             this._checkUniform(name);
             this._matrices[name] = value;
@@ -146,6 +293,12 @@
             return this;
         }
 
+        /**
+         * Set a mat3 in the shader from a Float32Array.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setMatrix3x3(name: string, value: Float32Array): ShaderMaterial {
             this._checkUniform(name);
             this._matrices3x3[name] = value;
@@ -153,6 +306,12 @@
             return this;
         }
 
+        /**
+         * Set a mat2 in the shader from a Float32Array.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setMatrix2x2(name: string, value: Float32Array): ShaderMaterial {
             this._checkUniform(name);
             this._matrices2x2[name] = value;
@@ -160,6 +319,12 @@
             return this;
         }
 
+        /**
+         * Set a vec2 array in the shader from a number array.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setArray2(name: string, value: number[]): ShaderMaterial {
             this._checkUniform(name);
             this._vectors2Arrays[name] = value;
@@ -167,6 +332,12 @@
             return this;
         }
 
+        /**
+         * Set a vec3 array in the shader from a number array.
+         * @param name Define the name of the uniform as defined in the shader
+         * @param value Define the value to give to the uniform
+         * @return the material itself allowing "fluent" like uniform updates
+         */
         public setArray3(name: string, value: number[]): ShaderMaterial {
             this._checkUniform(name);
             this._vectors3Arrays[name] = value;
@@ -186,6 +357,12 @@
             return false;
         }
 
+        /**
+         * Checks if the material is ready to render the requested mesh
+         * @param mesh Define the mesh to render
+         * @param useInstances Define whether or not the material is used with instances
+         * @returns true if ready, otherwise false
+         */
         public isReady(mesh?: AbstractMesh, useInstances?: boolean): boolean {
             var scene = this.getScene();
             var engine = scene.getEngine();
@@ -280,6 +457,10 @@
             return true;
         }
 
+        /**
+         * Binds the world matrix to the material
+         * @param world defines the world transformation matrix
+         */
         public bindOnlyWorldMatrix(world: Matrix): void {
             var scene = this.getScene();
 
@@ -301,6 +482,11 @@
             }
         }
 
+        /**
+         * Binds the material to the mesh
+         * @param world defines the world transformation matrix
+         * @param mesh defines the mesh to bind the material to
+         */
         public bind(world: Matrix, mesh?: Mesh): void {
             // Std values
             this.bindOnlyWorldMatrix(world);
@@ -406,6 +592,10 @@
             this._afterBind(mesh);
         }
 
+        /**
+         * Gets the active textures from the material
+         * @returns an array of textures
+         */
         public getActiveTextures(): BaseTexture[] {
             var activeTextures = super.getActiveTextures();
 
@@ -423,6 +613,11 @@
             return activeTextures;
         }
 
+        /**
+         * Specifies if the material uses a texture
+         * @param texture defines the texture to check against the material
+         * @returns a boolean specifying if the material uses the texture
+         */
         public hasTexture(texture: BaseTexture): boolean {
             if (super.hasTexture(texture)) {
                 return true;
@@ -446,12 +641,22 @@
             return false;
         }
 
+        /**
+         * Makes a duplicate of the material, and gives it a new name
+         * @param name defines the new name for the duplicated material
+         * @returns the cloned material
+         */
         public clone(name: string): ShaderMaterial {
             var newShaderMaterial = new ShaderMaterial(name, this.getScene(), this._shaderPath, this._options);
 
             return newShaderMaterial;
         }
 
+        /**
+         * Disposes the material
+         * @param forceDisposeEffect specifies if effects should be forcefully disposed
+         * @param forceDisposeTextures specifies if textures should be forcefully disposed
+         */
         public dispose(forceDisposeEffect?: boolean, forceDisposeTextures?: boolean): void {
 
             if (forceDisposeTextures) {
@@ -473,6 +678,10 @@
             super.dispose(forceDisposeEffect, forceDisposeTextures);
         }
 
+        /**
+         * Serializes this material in a JSON representation
+         * @returns the serialized material object
+         */
         public serialize(): any {
             var serializationObject = SerializationHelper.Serialize(this);
             serializationObject.customType = "BABYLON.ShaderMaterial";
@@ -579,6 +788,13 @@
             return serializationObject;
         }
 
+        /**
+         * Creates a shader material from parsed shader material data
+         * @param source defines the JSON represnetation of the material
+         * @param scene defines the hosting scene
+         * @param rootUrl defines the root URL to use to load textures and relative dependencies
+         * @returns a new material
+         */
         public static Parse(source: any, scene: Scene, rootUrl: string): ShaderMaterial {
             var material = SerializationHelper.Parse(() => new ShaderMaterial(source.name, scene, source.shaderPath, source.options), source, scene, rootUrl);
 

src/Materials/babylon.standardMaterial.ts

@@ -123,94 +123,176 @@ module BABYLON {
         }
     }
 
+    /**
+     * This is the default material used in Babylon. It is the best trade off between quality
+     * and performances.
+     * @see http://doc.babylonjs.com/babylon101/materials
+     */
     export class StandardMaterial extends PushMaterial {
         @serializeAsTexture("diffuseTexture")
         private _diffuseTexture: Nullable<BaseTexture>;
+        /**
+         * The basic texture of the material as viewed under a light.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesAndMiscDirty")
         public diffuseTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("ambientTexture")
         private _ambientTexture: Nullable<BaseTexture>;
+        /**
+         * AKA Occlusion Texture in other nomenclature, it helps adding baked shadows into your material.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public ambientTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("opacityTexture")
         private _opacityTexture: Nullable<BaseTexture>;
+        /**
+         * Define the transparency of the material from a texture.
+         * The final alpha value can be read either from the red channel (if texture.getAlphaFromRGB is false)
+         * or from the luminance or the current texel (if texture.getAlphaFromRGB is true)
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesAndMiscDirty")
         public opacityTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("reflectionTexture")
         private _reflectionTexture: Nullable<BaseTexture>;
+        /**
+         * Define the texture used to display the reflection.
+         * @see http://doc.babylonjs.com/how_to/reflect#how-to-obtain-reflections-and-refractions
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("emissiveTexture")
         private _emissiveTexture: Nullable<BaseTexture>;
+        /**
+         * Define texture of the material as if self lit.
+         * This will be mixed in the final result even in the absence of light.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public emissiveTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("specularTexture")
         private _specularTexture: Nullable<BaseTexture>;
+        /**
+         * Define how the color and intensity of the highlight given by the light in the material.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public specularTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("bumpTexture")
         private _bumpTexture: Nullable<BaseTexture>;
+        /**
+         * Bump mapping is a technique to simulate bump and dents on a rendered surface. 
+         * These are made by creating a normal map from an image. The means to do this can be found on the web, a search for 'normal map generator' will bring up free and paid for methods of doing this.
+         * @see http://doc.babylonjs.com/how_to/more_materials#bump-map
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public bumpTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("lightmapTexture")
         private _lightmapTexture: Nullable<BaseTexture>;
+        /**
+         * Complex lighting can be computationally expensive to compute at runtime. 
+         * To save on computation, lightmaps may be used to store calculated lighting in a texture which will be applied to a given mesh.
+         * @see http://doc.babylonjs.com/babylon101/lights#lightmaps
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public lightmapTexture: Nullable<BaseTexture>;
 
         @serializeAsTexture("refractionTexture")
         private _refractionTexture: Nullable<BaseTexture>;
+        /**
+         * Define the texture used to display the refraction.
+         * @see http://doc.babylonjs.com/how_to/reflect#how-to-obtain-reflections-and-refractions
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public refractionTexture: Nullable<BaseTexture>;
 
+        /**
+         * The color of the material lit by the environmental background lighting.
+         * @see http://doc.babylonjs.com/babylon101/materials#ambient-color-example
+         */
         @serializeAsColor3("ambient")
         public ambientColor = new Color3(0, 0, 0);
 
+        /**
+         * The basic color of the material as viewed under a light.
+         */
         @serializeAsColor3("diffuse")
         public diffuseColor = new Color3(1, 1, 1);
 
+        /**
+         * Define how the color and intensity of the highlight given by the light in the material.
+         */
         @serializeAsColor3("specular")
         public specularColor = new Color3(1, 1, 1);
 
+        /**
+         * Define the color of the material as if self lit.
+         * This will be mixed in the final result even in the absence of light.
+         */
         @serializeAsColor3("emissive")
         public emissiveColor = new Color3(0, 0, 0);
 
+        /**
+         * Defines how sharp are the highlights in the material.
+         * The bigger the value the sharper giving a more glossy feeling to the result.
+         * Reversely, the smaller the value the blurrier giving a more rough feeling to the result.
+         */
         @serialize()
         public specularPower = 64;
 
         @serialize("useAlphaFromDiffuseTexture")
         private _useAlphaFromDiffuseTexture = false;
+        /**
+         * Does the transparency come from the diffuse texture alpha channel.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useAlphaFromDiffuseTexture: boolean;
 
         @serialize("useEmissiveAsIllumination")
         private _useEmissiveAsIllumination = false;
+        /**
+         * If true, the emissive value is added into the end result, otherwise it is multiplied in.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useEmissiveAsIllumination: boolean;
 
         @serialize("linkEmissiveWithDiffuse")
         private _linkEmissiveWithDiffuse = false;
+        /**
+         * If true, some kind of energy conservation will prevent the end result to be more than 1 by reducing
+         * the emissive level when the final color is close to one.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public linkEmissiveWithDiffuse: boolean;
 
         @serialize("useSpecularOverAlpha")
         private _useSpecularOverAlpha = false;
+        /**
+         * Specifies that the material will keep the specular highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When sun reflects on it you can not see what is behind.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useSpecularOverAlpha: boolean;
 
         @serialize("useReflectionOverAlpha")
         private _useReflectionOverAlpha = false;
+        /**
+         * Specifies that the material will keeps the reflection highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When the street lights reflects on it you can not see what is behind.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useReflectionOverAlpha: boolean;
 
         @serialize("disableLighting")
         private _disableLighting = false;
+        /**
+         * Does lights from the scene impacts this material.
+         * It can be a nice trick for performance to disable lighting on a fully emissive material.
+         */
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public disableLighting: boolean;
 
@@ -224,102 +306,158 @@ module BABYLON {
 
         @serialize("useParallax")
         private _useParallax = false;
+        /**
+         * Is parallax enabled or not.
+         * @see http://doc.babylonjs.com/how_to/using_parallax_mapping
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useParallax: boolean;
 
         @serialize("useParallaxOcclusion")
         private _useParallaxOcclusion = false;
+        /**
+         * Is parallax occlusion enabled or not.
+         * If true, the outcome is way more realistic than traditional Parallax but you can expect a performance hit that worthes consideration.
+         * @see http://doc.babylonjs.com/how_to/using_parallax_mapping
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useParallaxOcclusion: boolean;
 
+        /**
+         * Apply a scaling factor that determine which "depth" the height map should reprensent. A value between 0.05 and 0.1 is reasonnable in Parallax, you can reach 0.2 using Parallax Occlusion.
+         */
         @serialize()
         public parallaxScaleBias = 0.05;
 
         @serialize("roughness")
         private _roughness = 0;
+        /**
+         * Helps to define how blurry the reflections should appears in the material.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public roughness: number;
 
+        /**
+         * In case of refraction, define the value of the indice of refraction.
+         * @see http://doc.babylonjs.com/how_to/reflect#how-to-obtain-reflections-and-refractions
+         */
         @serialize()
         public indexOfRefraction = 0.98;
 
+        /**
+         * Invert the refraction texture alongside the y axis.
+         * It can be usefull with procedural textures or probe for instance.
+         * @see http://doc.babylonjs.com/how_to/reflect#how-to-obtain-reflections-and-refractions
+         */
         @serialize()
         public invertRefractionY = true;
 
         /**
-         * Defines the alpha limits in alpha test mode
+         * Defines the alpha limits in alpha test mode.
          */
         @serialize()
-        public alphaCutOff = 0.4;        
+        public alphaCutOff = 0.4;
 
         @serialize("useLightmapAsShadowmap")
         private _useLightmapAsShadowmap = false;
+        /**
+         * In case of light mapping, define whether the map contains light or shadow informations.
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useLightmapAsShadowmap: boolean;
 
         // Fresnel
         @serializeAsFresnelParameters("diffuseFresnelParameters")
         private _diffuseFresnelParameters: FresnelParameters;
+        /**
+         * Define the diffuse fresnel parameters of the material.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelDirty")
         public diffuseFresnelParameters: FresnelParameters;
 
         @serializeAsFresnelParameters("opacityFresnelParameters")
         private _opacityFresnelParameters: FresnelParameters;
+        /**
+         * Define the opacity fresnel parameters of the material.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelAndMiscDirty")
         public opacityFresnelParameters: FresnelParameters;
 
-
         @serializeAsFresnelParameters("reflectionFresnelParameters")
         private _reflectionFresnelParameters: FresnelParameters;
+        /**
+         * Define the reflection fresnel parameters of the material.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelDirty")
         public reflectionFresnelParameters: FresnelParameters;
 
         @serializeAsFresnelParameters("refractionFresnelParameters")
         private _refractionFresnelParameters: FresnelParameters;
+        /**
+         * Define the refraction fresnel parameters of the material.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelDirty")
         public refractionFresnelParameters: FresnelParameters;
 
         @serializeAsFresnelParameters("emissiveFresnelParameters")
         private _emissiveFresnelParameters: FresnelParameters;
+        /**
+         * Define the emissive fresnel parameters of the material.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelDirty")
         public emissiveFresnelParameters: FresnelParameters;
 
         @serialize("useReflectionFresnelFromSpecular")
         private _useReflectionFresnelFromSpecular = false;
+        /**
+         * If true automatically deducts the fresnels values from the material specularity.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_fresnelparameters
+         */
         @expandToProperty("_markAllSubMeshesAsFresnelDirty")
         public useReflectionFresnelFromSpecular: boolean;
 
         @serialize("useGlossinessFromSpecularMapAlpha")
         private _useGlossinessFromSpecularMapAlpha = false;
+        /**
+         * Defines if the glossiness/roughness of the material should be read from the specular map alpha channel
+         */
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useGlossinessFromSpecularMapAlpha: boolean;
 
         @serialize("maxSimultaneousLights")
         private _maxSimultaneousLights = 4;
+        /**
+         * Defines the maximum number of lights that can be used in the material
+         */
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public maxSimultaneousLights: number;
 
+        @serialize("invertNormalMapX")
+        private _invertNormalMapX = false;
         /**
          * If sets to true, x component of normal map value will invert (x = 1.0 - x).
          */
-        @serialize("invertNormalMapX")
-        private _invertNormalMapX = false;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public invertNormalMapX: boolean;
 
+        @serialize("invertNormalMapY")
+        private _invertNormalMapY = false;
         /**
          * If sets to true, y component of normal map value will invert (y = 1.0 - y).
          */
-        @serialize("invertNormalMapY")
-        private _invertNormalMapY = false;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public invertNormalMapY: boolean;
 
+        @serialize("twoSidedLighting")
+        private _twoSidedLighting = false;
         /**
          * If sets to true and backfaceCulling is false, normals will be flipped on the backside.
          */
-        @serialize("twoSidedLighting")
-        private _twoSidedLighting = false;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public twoSidedLighting: boolean;
 
@@ -484,14 +622,24 @@ module BABYLON {
             this._imageProcessingConfiguration.colorCurves = value;
         }
 
+        /**
+         * Custom callback helping to override the default shader used in the material.
+         */
         public customShaderNameResolve: (shaderName: string, uniforms: string[], uniformBuffers: string[], samplers: string[], defines: StandardMaterialDefines) => string;
 
         protected _renderTargets = new SmartArray<RenderTargetTexture>(16);
         protected _worldViewProjectionMatrix = Matrix.Zero();
         protected _globalAmbientColor = new Color3(0, 0, 0);
-
         protected _useLogarithmicDepth: boolean;
 
+        /**
+         * Instantiates a new standard material.
+         * This is the default material used in Babylon. It is the best trade off between quality
+         * and performances.
+         * @see http://doc.babylonjs.com/babylon101/materials
+         * @param name Define the name of the material in the scene
+         * @param scene Define the scene the material belong to
+         */
         constructor(name: string, scene: Scene) {
             super(name, scene);
 
@@ -515,7 +663,7 @@ module BABYLON {
 
         /**
          * Gets a boolean indicating that current material needs to register RTT
-         */               
+         */
         public get hasRenderTargetTextures(): boolean {
             if (StandardMaterial.ReflectionTextureEnabled && this._reflectionTexture && this._reflectionTexture.isRenderTarget) {
                 return true;
@@ -528,10 +676,20 @@ module BABYLON {
             return false;
         }
 
+        /**
+         * Gets the current class name of the material e.g. "StandardMaterial"
+         * Mainly use in serialization.
+         * @returns the class name
+         */
         public getClassName(): string {
             return "StandardMaterial";
         }
 
+        /**
+         * In case the depth buffer does not allow enough depth precision for your scene (might be the case in large scenes)
+         * You can try switching to logarithmic depth.
+         * @see http://doc.babylonjs.com/how_to/using_logarithmic_depth_buffer
+         */
         @serialize()
         public get useLogarithmicDepth(): boolean {
             return this._useLogarithmicDepth;
@@ -543,10 +701,18 @@ module BABYLON {
             this._markAllSubMeshesAsMiscDirty();
         }
 
+        /**
+         * Specifies if the material will require alpha blending
+         * @returns a boolean specifying if alpha blending is needed
+         */
         public needAlphaBlending(): boolean {
             return (this.alpha < 1.0) || (this._opacityTexture != null) || this._shouldUseAlphaFromDiffuseTexture() || this._opacityFresnelParameters && this._opacityFresnelParameters.isEnabled;
         }
 
+        /**
+         * Specifies if this material should be rendered in alpha test mode
+         * @returns a boolean specifying if an alpha test is needed.
+         */
         public needAlphaTesting(): boolean {
             return this._diffuseTexture != null && this._diffuseTexture.hasAlpha;
         }
@@ -555,12 +721,21 @@ module BABYLON {
             return this._diffuseTexture != null && this._diffuseTexture.hasAlpha && this._useAlphaFromDiffuseTexture;
         }
 
+        /**
+         * Get the texture used for alpha test purpose.
+         * @returns the diffuse texture in case of the standard material.
+         */
         public getAlphaTestTexture(): Nullable<BaseTexture> {
             return this._diffuseTexture;
         }
 
         /**
+         * Get if the submesh is ready to be used and all its information available.
          * Child classes can use it to update shaders
+         * @param mesh defines the mesh to check
+         * @param subMesh defines which submesh to check
+         * @param useInstances specifies that instances should be used
+         * @returns a boolean indicating that the submesh is ready or not
          */
         public isReadyForSubMesh(mesh: AbstractMesh, subMesh: SubMesh, useInstances: boolean = false): boolean {
             if (subMesh.effect && this.isFrozen) {
@@ -956,6 +1131,10 @@ module BABYLON {
             return true;
         }
 
+        /**
+         * Builds the material UBO layouts.
+         * Used internally during the effect preparation.
+         */
         public buildUniformLayout(): void {
             // Order is important !
             this._uniformBuffer.addUniform("diffuseLeftColor", 4);
@@ -998,6 +1177,9 @@ module BABYLON {
             this._uniformBuffer.create();
         }
 
+        /**
+         * Unbinds the material from the mesh
+         */
         public unbind(): void {
             if (this._activeEffect) {
                 let needFlag = false;
@@ -1019,6 +1201,12 @@ module BABYLON {
             super.unbind();
         }
 
+        /**
+         * Binds the submesh to this material by preparing the effect and shader to draw
+         * @param world defines the world transformation matrix
+         * @param mesh defines the mesh containing the submesh
+         * @param subMesh defines the submesh to bind the material to
+         */
         public bindForSubMesh(world: Matrix, mesh: Mesh, subMesh: SubMesh): void {
             var scene = this.getScene();
 
@@ -1257,6 +1445,10 @@ module BABYLON {
             this._afterBind(mesh, this._activeEffect);
         }
 
+        /**
+         * Get the list of animatables in the material.
+         * @returns the list of animatables object used in the material
+         */
         public getAnimatables(): IAnimatable[] {
             var results = [];
 
@@ -1299,6 +1491,10 @@ module BABYLON {
             return results;
         }
 
+        /**
+         * Gets the active textures from the material
+         * @returns an array of textures
+         */
         public getActiveTextures(): BaseTexture[] {
             var activeTextures = super.getActiveTextures();
 
@@ -1341,6 +1537,11 @@ module BABYLON {
             return activeTextures;
         }
 
+        /**
+         * Specifies if the material uses a texture
+         * @param texture defines the texture to check against the material
+         * @returns a boolean specifying if the material uses the texture
+         */
         public hasTexture(texture: BaseTexture): boolean {
             if (super.hasTexture(texture)) {
                 return true;
@@ -1385,6 +1586,11 @@ module BABYLON {
             return false;
         }
 
+        /**
+         * Disposes the material
+         * @param forceDisposeEffect specifies if effects should be forcefully disposed
+         * @param forceDisposeTextures specifies if textures should be forcefully disposed
+         */
         public dispose(forceDisposeEffect?: boolean, forceDisposeTextures?: boolean): void {
             if (forceDisposeTextures) {
                 if (this._diffuseTexture) {
@@ -1431,6 +1637,11 @@ module BABYLON {
             super.dispose(forceDisposeEffect, forceDisposeTextures);
         }
 
+        /**
+         * Makes a duplicate of the material, and gives it a new name
+         * @param name defines the new name for the duplicated material
+         * @returns the cloned material
+         */
         public clone(name: string): StandardMaterial {
             var result = SerializationHelper.Clone(() => new StandardMaterial(name, this.getScene()), this);
 
@@ -1440,17 +1651,30 @@ module BABYLON {
             return result;
         }
 
+        /**
+         * Serializes this material in a JSON representation
+         * @returns the serialized material object
+         */
         public serialize(): any {
             return SerializationHelper.Serialize(this);
         }
 
-        // Statics
+        /**
+         * Creates a standard material from parsed material data
+         * @param source defines the JSON represnetation of the material
+         * @param scene defines the hosting scene
+         * @param rootUrl defines the root URL to use to load textures and relative dependencies
+         * @returns a new material
+         */
         public static Parse(source: any, scene: Scene, rootUrl: string): StandardMaterial {
             return SerializationHelper.Parse(() => new StandardMaterial(source.name, scene), source, scene, rootUrl);
         }
 
         // Flags used to enable or disable a type of texture for all Standard Materials
-        static _DiffuseTextureEnabled = true;
+        private static _DiffuseTextureEnabled = true;
+        /**
+         * Are diffuse textures enabled in the application.
+         */
         public static get DiffuseTextureEnabled(): boolean {
             return StandardMaterial._DiffuseTextureEnabled;
         }
@@ -1463,8 +1687,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-
-        static _AmbientTextureEnabled = true;
+        private static _AmbientTextureEnabled = true;
+        /**
+         * Are ambient textures enabled in the application.
+         */
         public static get AmbientTextureEnabled(): boolean {
             return StandardMaterial._AmbientTextureEnabled;
         }
@@ -1477,7 +1703,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _OpacityTextureEnabled = true;
+        private static _OpacityTextureEnabled = true;
+        /**
+         * Are opacity textures enabled in the application.
+         */
         public static get OpacityTextureEnabled(): boolean {
             return StandardMaterial._OpacityTextureEnabled;
         }
@@ -1490,7 +1719,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _ReflectionTextureEnabled = true;
+        private static _ReflectionTextureEnabled = true;
+        /**
+         * Are reflection textures enabled in the application.
+         */
         public static get ReflectionTextureEnabled(): boolean {
             return StandardMaterial._ReflectionTextureEnabled;
         }
@@ -1503,7 +1735,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _EmissiveTextureEnabled = true;
+        private static _EmissiveTextureEnabled = true;
+        /**
+         * Are emissive textures enabled in the application.
+         */
         public static get EmissiveTextureEnabled(): boolean {
             return StandardMaterial._EmissiveTextureEnabled;
         }
@@ -1516,7 +1751,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _SpecularTextureEnabled = true;
+        private static _SpecularTextureEnabled = true;
+        /**
+         * Are specular textures enabled in the application.
+         */
         public static get SpecularTextureEnabled(): boolean {
             return StandardMaterial._SpecularTextureEnabled;
         }
@@ -1529,7 +1767,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _BumpTextureEnabled = true;
+        private static _BumpTextureEnabled = true;
+        /**
+         * Are bump textures enabled in the application.
+         */
         public static get BumpTextureEnabled(): boolean {
             return StandardMaterial._BumpTextureEnabled;
         }
@@ -1542,7 +1783,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _LightmapTextureEnabled = true;
+        private static _LightmapTextureEnabled = true;
+        /**
+         * Are lightmap textures enabled in the application.
+         */
         public static get LightmapTextureEnabled(): boolean {
             return StandardMaterial._LightmapTextureEnabled;
         }
@@ -1555,7 +1799,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _RefractionTextureEnabled = true;
+        private static _RefractionTextureEnabled = true;
+        /**
+         * Are refraction textures enabled in the application.
+         */
         public static get RefractionTextureEnabled(): boolean {
             return StandardMaterial._RefractionTextureEnabled;
         }
@@ -1568,7 +1815,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _ColorGradingTextureEnabled = true;
+        private static _ColorGradingTextureEnabled = true;
+        /**
+         * Are color grading textures enabled in the application.
+         */
         public static get ColorGradingTextureEnabled(): boolean {
             return StandardMaterial._ColorGradingTextureEnabled;
         }
@@ -1581,7 +1831,10 @@ module BABYLON {
             Engine.MarkAllMaterialsAsDirty(Material.TextureDirtyFlag);
         }
 
-        static _FresnelEnabled = true;
+        private static _FresnelEnabled = true;
+        /**
+         * Are fresnels enabled in the application.
+         */
         public static get FresnelEnabled(): boolean {
             return StandardMaterial._FresnelEnabled;
         }

src/Materials/babylon.uniformBuffer.ts

@@ -1,5 +1,15 @@
 module BABYLON {
 
+    /**
+     * Uniform buffer objects.
+     * 
+     * Handles blocks of uniform on the GPU.
+     *
+     * If WebGL 2 is not available, this class falls back on traditionnal setUniformXXX calls.
+     *
+     * For more information, please refer to : 
+     * https://www.khronos.org/opengl/wiki/Uniform_Buffer_Object
+     */
     export class UniformBuffer {
         private _engine: Engine;
         private _buffer: Nullable<WebGLBuffer>;
@@ -18,104 +28,94 @@ module BABYLON {
         private static _tempBuffer = new Float32Array(UniformBuffer._MAX_UNIFORM_SIZE);
 
         /**
-         * Wrapper for updateUniform.
-         * @method updateMatrix3x3 
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Float32Array} matrix
+         * Lambda to Update a 3x3 Matrix in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateMatrix3x3: (name: string, matrix: Float32Array) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Float32Array} matrix
+         * Lambda to Update a 2x2 Matrix in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateMatrix2x2: (name: string, matrix: Float32Array) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
+         * Lambda to Update a single float in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateFloat: (name: string, x: number) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
-         * @param {number} y
-         * @param {string} [suffix] Suffix to add to the uniform name.
+         * Lambda to Update a vec2 of float in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateFloat2: (name: string, x: number, y: number, suffix?: string) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
-         * @param {number} y
-         * @param {number} z
-         * @param {string} [suffix] Suffix to add to the uniform name.
+         * Lambda to Update a vec3 of float in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateFloat3: (name: string, x: number, y: number, z: number, suffix?: string) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
-         * @param {number} y
-         * @param {number} z
-         * @param {number} w
-         * @param {string} [suffix] Suffix to add to the uniform name.
+         * Lambda to Update a vec4 of float in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateFloat4: (name: string, x: number, y: number, z: number, w: number, suffix?: string) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Matrix} A 4x4 matrix.
+         * Lambda to Update a 4x4 Matrix in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateMatrix: (name: string, mat: Matrix) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Vector3} vector
+         * Lambda to Update vec3 of float from a Vector in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateVector3: (name: string, vector: Vector3) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Vector4} vector
+         * Lambda to Update vec4 of float from a Vector in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateVector4: (name: string, vector: Vector4) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Color3} color
-         * @param {string} [suffix] Suffix to add to the uniform name.
+         * Lambda to Update vec3 of float from a Color in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateColor3: (name: string, color: Color3, suffix?: string) => void;
 
         /**
-         * Wrapper for updateUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Color3} color
-         * @param {number} alpha
-         * @param {string} [suffix] Suffix to add to the uniform name.
+         * Lambda to Update vec4 of float from a Color in a uniform buffer.
+         * This is dynamic to allow compat with webgl 1 and 2.
+         * You will need to pass the name of the uniform as well as the value.
          */
         public updateColor4: (name: string, color: Color3, alpha: number, suffix?: string) => void;
 
         /**
-         * Uniform buffer objects.
+         * Instantiates a new Uniform buffer objects.
          * 
          * Handles blocks of uniform on the GPU.
          *
          * If WebGL 2 is not available, this class falls back on traditionnal setUniformXXX calls.
          *
          * For more information, please refer to : 
-         * https://www.khronos.org/opengl/wiki/Uniform_Buffer_Object
+         * @see https://www.khronos.org/opengl/wiki/Uniform_Buffer_Object
+         * @param engine Define the engine the buffer is associated with
+         * @param data Define the data contained in the buffer
+         * @param dynamic Define if the buffer is updatable 
          */
         constructor(engine: Engine, data?: number[], dynamic?: boolean) {
             this._engine = engine;
@@ -159,7 +159,6 @@ module BABYLON {
 
         }
 
-        // Properties
         /**
          * Indicates if the buffer is using the WebGL2 UBO implementation,
          * or just falling back on setUniformXXX calls.
@@ -180,6 +179,7 @@ module BABYLON {
          * Indicates if the WebGL underlying uniform buffer is dynamic.
          * Also, a dynamic UniformBuffer will disable cache verification and always 
          * update the underlying WebGL uniform buffer to the GPU.
+         * @returns if Dynamic, otherwise false
          */
         public isDynamic(): boolean {
             return this._dynamic !== undefined;
@@ -187,6 +187,7 @@ module BABYLON {
 
         /**
          * The data cache on JS side.
+         * @returns the underlying data as a float array
          */
         public getData(): Float32Array {
             return this._bufferData;
@@ -194,6 +195,7 @@ module BABYLON {
 
         /**
          * The underlying WebGL Uniform buffer.
+         * @returns the webgl buffer
          */
         public getBuffer(): Nullable<WebGLBuffer> {
             return this._buffer;
@@ -231,8 +233,8 @@ module BABYLON {
          * Adds an uniform in the buffer.
          * Warning : the subsequents calls of this function must be in the same order as declared in the shader
          * for the layout to be correct !
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number|number[]} size Data size, or data directly.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param size Data size, or data directly.
          */
         public addUniform(name: string, size: number | number[]) {
             if (this._noUBO) {
@@ -274,19 +276,19 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Matrix} mat A 4x4 matrix.
+         * Adds a Matrix 4x4 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param mat A 4x4 matrix.
          */
         public addMatrix(name: string, mat: Matrix) {
             this.addUniform(name, Array.prototype.slice.call(mat.toArray()));
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
-         * @param {number} y
+         * Adds a vec2 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param x Define the x component value of the vec2
+         * @param y Define the y component value of the vec2
          */
         public addFloat2(name: string, x: number, y: number) {
             var temp = [x, y];
@@ -294,11 +296,11 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {number} x
-         * @param {number} y
-         * @param {number} z
+         * Adds a vec3 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param x Define the x component value of the vec3
+         * @param y Define the y component value of the vec3
+         * @param z Define the z component value of the vec3
          */
         public addFloat3(name: string, x: number, y: number, z: number) {
             var temp = [x, y, z];
@@ -306,9 +308,9 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Color3} color
+         * Adds a vec3 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param color Define the vec3 from a Color
          */
         public addColor3(name: string, color: Color3) {
             var temp = new Array<number>();
@@ -317,10 +319,10 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Color3} color
-         * @param {number} alpha
+         * Adds a vec4 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param color Define the rgb components from a Color
+         * @param alpha Define the a component of the vec4
          */
         public addColor4(name: string, color: Color3, alpha: number) {
             var temp = new Array<number>();
@@ -330,9 +332,9 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
-         * @param {Vector3} vector
+         * Adds a vec3 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
+         * @param vector Define the vec3 components from a Vector
          */
         public addVector3(name: string, vector: Vector3) {
             var temp = new Array<number>();
@@ -341,16 +343,16 @@ module BABYLON {
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
+         * Adds a Matrix 3x3 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
          */
         public addMatrix3x3(name: string) {
             this.addUniform(name, 12);
         }
 
         /**
-         * Wrapper for addUniform.
-         * @param {string} name Name of the uniform, as used in the uniform block in the shader.
+         * Adds a Matrix 2x2 to the uniform buffer.
+         * @param name Name of the uniform, as used in the uniform block in the shader.
          */
         public addMatrix2x2(name: string) {
             this.addUniform(name, 8);
@@ -411,9 +413,9 @@ module BABYLON {
 
         /**
          * Updates the value of an uniform. The `update` method must be called afterwards to make it effective in the GPU.
-         * @param {string} uniformName Name of the uniform, as used in the uniform block in the shader.
-         * @param {number[]|Float32Array} data Flattened data
-         * @param {number} size Size of the data.
+         * @param uniformName Define the name of the uniform, as used in the uniform block in the shader.
+         * @param data Define the flattened data
+         * @param size Define the size of the data.
          */
         public updateUniform(uniformName: string, data: FloatArray, size: number) {
 
@@ -575,8 +577,8 @@ module BABYLON {
 
         /**
          * Sets a sampler uniform on the effect.
-         * @param {string} name Name of the sampler.
-         * @param {Texture} texture
+         * @param name Define the name of the sampler.
+         * @param texture Define the texture to set in the sampler
          */
         public setTexture(name: string, texture: Nullable<BaseTexture>) {
             this._currentEffect.setTexture(name, texture);
@@ -584,8 +586,8 @@ module BABYLON {
 
         /**
          * Directly updates the value of the uniform in the cache AND on the GPU.
-         * @param {string} uniformName Name of the uniform, as used in the uniform block in the shader.
-         * @param {number[]|Float32Array} data Flattened data
+         * @param uniformName Define the name of the uniform, as used in the uniform block in the shader.
+         * @param data Define the flattened data
          */
         public updateUniformDirectly(uniformName: string, data: FloatArray) {
             this.updateUniform(uniformName, data, data.length);
@@ -595,8 +597,8 @@ module BABYLON {
 
         /**
          * Binds this uniform buffer to an effect.
-         * @param {Effect} effect
-         * @param {string} name Name of the uniform block in the shader.
+         * @param effect Define the effect to bind the buffer to
+         * @param name Name of the uniform block in the shader.
          */
         public bindToEffect(effect: Effect, name: string): void {
             this._currentEffect = effect;

src/Mesh/babylon.buffer.ts

@@ -1,4 +1,7 @@
 module BABYLON {
+    /**
+     * Class used to store data that will be store in GPU memory
+     */
     export class Buffer {
         private _engine: Engine;
         private _buffer: Nullable<WebGLBuffer>;
@@ -61,14 +64,27 @@
         }
 
         // Properties
+
+        /**
+         * Gets a boolean indicating if the Buffer is updatable?
+         * @returns true if the buffer is updatable
+         */
         public isUpdatable(): boolean {
             return this._updatable;
         }
 
+        /**
+         * Gets current buffer's data
+         * @returns a DataArray or null
+         */
         public getData(): Nullable<DataArray> {
             return this._data;
         }
 
+        /**
+         * Gets underlying native buffer
+         * @returns underlying native buffer
+         */
         public getBuffer(): Nullable<WebGLBuffer> {
             return this._buffer;
         }
@@ -84,6 +100,11 @@
         }
 
         // Methods
+
+        /**
+         * Store data into the buffer. If the buffer was already used it will be either recreated or updated depending on isUpdatable property
+         * @param data defines the data to store
+         */
         public create(data: Nullable<DataArray> = null): void {
             if (!data && this._buffer) {
                 return; // nothing to do
@@ -114,6 +135,10 @@
             this.create(this._data);
         }
 
+        /**
+         * Update current buffer data
+         * @param data defines the data to store
+         */
         public update(data: DataArray): void {
             this.create(data);
         }
@@ -136,6 +161,9 @@
             }
         }
 
+        /**
+         * Release all resources
+         */
         public dispose(): void {
             if (!this._buffer) {
                 return;

src/Mesh/babylon.linesMesh.ts

@@ -44,7 +44,7 @@
 
             this._intersectionThreshold = 0.1;
 
-            var defines: String[] = [];
+            var defines: string[] = [];
             var options = {
                 attributes: [VertexBuffer.PositionKind, "world0", "world1", "world2", "world3"],
                 uniforms: ["world", "viewProjection"],

src/Mesh/babylon.mesh.ts

@@ -1,4 +1,34 @@
 module BABYLON {
+
+    /**
+     * @hidden
+     **/
+    export class _CreationDataStorage {
+        public closePath?: boolean;
+        public idx: number[];
+        public dashSize: number;
+        public gapSize: number;
+        public path3D: Path3D;
+        public pathArray: Vector3[][];
+        public arc: number;
+        public radius: number;   
+        public cap: number;
+        public tessellation: number
+    }
+
+    /**
+     * @hidden
+     **/
+    class _InstanceDataStorage {
+        public visibleInstances: any = {};
+        public renderIdForInstances = new Array<number>();
+        public batchCache = new _InstancesBatch();
+        public instancesBufferSize = 32 * 16 * 4; // let's start with a maximum of 32 instances
+        public instancesBuffer: Nullable<Buffer>;
+        public instancesData: Float32Array;
+        public overridenInstanceCount: number;
+    }
+
     /**
      * @hidden
      **/
@@ -148,6 +178,9 @@
 
         // Private
         /** @hidden */
+        public _creationDataStorage: Nullable<_CreationDataStorage>;
+
+        /** @hidden */
         public _geometry: Nullable<Geometry>;
         /** @hidden */
         public _delayInfo: Array<string>;
@@ -155,13 +188,7 @@
         public _delayLoadingFunction: (any: any, mesh: Mesh) => void;
 
         /** @hidden */
-        public _visibleInstances: any = {};
-        private _renderIdForInstances = new Array<number>();
-        private _batchCache = new _InstancesBatch();
-        private _instancesBufferSize = 32 * 16 * 4; // let's start with a maximum of 32 instances
-        private _instancesBuffer: Nullable<Buffer>;
-        private _instancesData: Float32Array;
-        private _overridenInstanceCount: number;
+        public _instanceDataStorage = new _InstanceDataStorage();
 
         private _effectiveMaterial: Material;
 
@@ -242,16 +269,7 @@
                 // Construction Params
                 // Clone parameters allowing mesh to be updated in case of parametric shapes.
                 this._originalBuilderSideOrientation = source._originalBuilderSideOrientation;
-                const myAnyThis = this as any;
-                const myAnySource = source as any;
-                myAnyThis._closePath = myAnySource._closePath;
-                myAnyThis._idx = myAnySource._idx;
-                myAnyThis.dashSize = myAnySource.dashSize;
-                myAnyThis.gapSize = myAnySource.gapSize;
-                myAnyThis.path3D = myAnySource.path3D;
-                myAnyThis.pathArray = myAnySource.pathArray;
-                myAnyThis.arc = myAnySource.arc;
-                myAnyThis.radius = myAnySource.radius;
+                this._creationDataStorage = source._creationDataStorage;
 
                 // Animation ranges
                 if (this._source._ranges) {
@@ -816,7 +834,7 @@
          * Sets a value overriding the instance count. Only applicable when custom instanced InterleavedVertexBuffer are used rather than InstancedMeshs
          */
         public set overridenInstanceCount(count: number) {
-            this._overridenInstanceCount = count;
+            this._instanceDataStorage.overridenInstanceCount = count;
         }
 
         // Methods
@@ -828,31 +846,31 @@
             }
 
             this._preActivateId = sceneRenderId;
-            this._visibleInstances = null;
+            this._instanceDataStorage.visibleInstances = null;
             return this;
         }
 
         /** @hidden */
         public _preActivateForIntermediateRendering(renderId: number): Mesh {
-            if (this._visibleInstances) {
-                this._visibleInstances.intermediateDefaultRenderId = renderId;
+            if (this._instanceDataStorage.visibleInstances) {
+                this._instanceDataStorage.visibleInstances.intermediateDefaultRenderId = renderId;
             }
             return this;
         }
 
         /** @hidden */
         public _registerInstanceForRenderId(instance: InstancedMesh, renderId: number): Mesh {
-            if (!this._visibleInstances) {
-                this._visibleInstances = {};
-                this._visibleInstances.defaultRenderId = renderId;
-                this._visibleInstances.selfDefaultRenderId = this._renderId;
+            if (!this._instanceDataStorage.visibleInstances) {
+                this._instanceDataStorage.visibleInstances = {};
+                this._instanceDataStorage.visibleInstances.defaultRenderId = renderId;
+                this._instanceDataStorage.visibleInstances.selfDefaultRenderId = this._renderId;
             }
 
-            if (!this._visibleInstances[renderId]) {
-                this._visibleInstances[renderId] = new Array<InstancedMesh>();
+            if (!this._instanceDataStorage.visibleInstances[renderId]) {
+                this._instanceDataStorage.visibleInstances[renderId] = new Array<InstancedMesh>();
             }
 
-            this._visibleInstances[renderId].push(instance);
+            this._instanceDataStorage.visibleInstances[renderId].push(instance);
             return this;
         }
 
@@ -1338,38 +1356,40 @@
         /** @hidden */
         public _getInstancesRenderList(subMeshId: number): _InstancesBatch {
             var scene = this.getScene();
-            this._batchCache.mustReturn = false;
-            this._batchCache.renderSelf[subMeshId] = this.isEnabled() && this.isVisible;
-            this._batchCache.visibleInstances[subMeshId] = null;
+            let batchCache = this._instanceDataStorage.batchCache;
+            batchCache.mustReturn = false;
+            batchCache.renderSelf[subMeshId] = this.isEnabled() && this.isVisible;
+            batchCache.visibleInstances[subMeshId] = null;
 
-            if (this._visibleInstances) {
+            if (this._instanceDataStorage.visibleInstances) {
+                let visibleInstances = this._instanceDataStorage.visibleInstances;
                 var currentRenderId = scene.getRenderId();
-                var defaultRenderId = (scene._isInIntermediateRendering() ? this._visibleInstances.intermediateDefaultRenderId : this._visibleInstances.defaultRenderId);
-                this._batchCache.visibleInstances[subMeshId] = this._visibleInstances[currentRenderId];
+                var defaultRenderId = (scene._isInIntermediateRendering() ? visibleInstances.intermediateDefaultRenderId : visibleInstances.defaultRenderId);
+                batchCache.visibleInstances[subMeshId] = visibleInstances[currentRenderId];
                 var selfRenderId = this._renderId;
 
-                if (!this._batchCache.visibleInstances[subMeshId] && defaultRenderId) {
-                    this._batchCache.visibleInstances[subMeshId] = this._visibleInstances[defaultRenderId];
+                if (!batchCache.visibleInstances[subMeshId] && defaultRenderId) {
+                    batchCache.visibleInstances[subMeshId] = visibleInstances[defaultRenderId];
                     currentRenderId = Math.max(defaultRenderId, currentRenderId);
-                    selfRenderId = Math.max(this._visibleInstances.selfDefaultRenderId, currentRenderId);
+                    selfRenderId = Math.max(visibleInstances.selfDefaultRenderId, currentRenderId);
                 }
 
-                let visibleInstancesForSubMesh = this._batchCache.visibleInstances[subMeshId];
+                let visibleInstancesForSubMesh = batchCache.visibleInstances[subMeshId];
                 if (visibleInstancesForSubMesh && visibleInstancesForSubMesh.length) {
-                    if (this._renderIdForInstances[subMeshId] === currentRenderId) {
-                        this._batchCache.mustReturn = true;
-                        return this._batchCache;
+                    if (this._instanceDataStorage.renderIdForInstances[subMeshId] === currentRenderId) {
+                        batchCache.mustReturn = true;
+                        return batchCache;
                     }
 
                     if (currentRenderId !== selfRenderId) {
-                        this._batchCache.renderSelf[subMeshId] = false;
+                        batchCache.renderSelf[subMeshId] = false;
                     }
 
                 }
-                this._renderIdForInstances[subMeshId] = currentRenderId;
+                this._instanceDataStorage.renderIdForInstances[subMeshId] = currentRenderId;
             }
 
-            return this._batchCache;
+            return batchCache;
         }
 
         /** @hidden */
@@ -1382,15 +1402,16 @@
             var matricesCount = visibleInstances.length + 1;
             var bufferSize = matricesCount * 16 * 4;
 
-            var currentInstancesBufferSize = this._instancesBufferSize;
-            var instancesBuffer = this._instancesBuffer;
+            let instanceStorage = this._instanceDataStorage;
+            var currentInstancesBufferSize = instanceStorage.instancesBufferSize;
+            var instancesBuffer = instanceStorage.instancesBuffer;
 
-            while (this._instancesBufferSize < bufferSize) {
-                this._instancesBufferSize *= 2;
+            while (instanceStorage.instancesBufferSize < bufferSize) {
+                instanceStorage.instancesBufferSize *= 2;
             }
 
-            if (!this._instancesData || currentInstancesBufferSize != this._instancesBufferSize) {
-                this._instancesData = new Float32Array(this._instancesBufferSize / 4);
+            if (!instanceStorage.instancesData || currentInstancesBufferSize != instanceStorage.instancesBufferSize) {
+                instanceStorage.instancesData = new Float32Array(instanceStorage.instancesBufferSize / 4);
             }
 
             var offset = 0;
@@ -1398,7 +1419,7 @@
 
             var world = this.getWorldMatrix();
             if (batch.renderSelf[subMesh._id]) {
-                world.copyToArray(this._instancesData, offset);
+                world.copyToArray(instanceStorage.instancesData, offset);
                 offset += 16;
                 instancesCount++;
             }
@@ -1406,26 +1427,26 @@
             if (visibleInstances) {
                 for (var instanceIndex = 0; instanceIndex < visibleInstances.length; instanceIndex++) {
                     var instance = visibleInstances[instanceIndex];
-                    instance.getWorldMatrix().copyToArray(this._instancesData, offset);
+                    instance.getWorldMatrix().copyToArray(instanceStorage.instancesData, offset);
                     offset += 16;
                     instancesCount++;
                 }
             }
 
-            if (!instancesBuffer || currentInstancesBufferSize != this._instancesBufferSize) {
+            if (!instancesBuffer || currentInstancesBufferSize != instanceStorage.instancesBufferSize) {
                 if (instancesBuffer) {
                     instancesBuffer.dispose();
                 }
 
-                instancesBuffer = new Buffer(engine, this._instancesData, true, 16, false, true);
-                this._instancesBuffer = instancesBuffer;
+                instancesBuffer = new Buffer(engine, instanceStorage.instancesData, true, 16, false, true);
+                instanceStorage.instancesBuffer = instancesBuffer;
 
                 this.setVerticesBuffer(instancesBuffer.createVertexBuffer("world0", 0, 4));
                 this.setVerticesBuffer(instancesBuffer.createVertexBuffer("world1", 4, 4));
                 this.setVerticesBuffer(instancesBuffer.createVertexBuffer("world2", 8, 4));
                 this.setVerticesBuffer(instancesBuffer.createVertexBuffer("world3", 12, 4));
             } else {
-                instancesBuffer.updateDirectly(this._instancesData, 0, instancesCount);
+                instancesBuffer.updateDirectly(instanceStorage.instancesData, 0, instancesCount);
             }
 
             this._bind(subMesh, effect, fillMode);
@@ -1450,7 +1471,7 @@
                         onBeforeDraw(false, this.getWorldMatrix(), effectiveMaterial);
                     }
 
-                    this._draw(subMesh, fillMode, this._overridenInstanceCount);
+                    this._draw(subMesh, fillMode, this._instanceDataStorage.overridenInstanceCount);
                 }
 
                 let visibleInstancesForSubMesh = batch.visibleInstances[subMesh._id];
@@ -1740,6 +1761,94 @@
             this.setVerticesData(VertexBuffer.MatricesWeightsKind, matricesWeightsExtra);
         }
 
+        /**
+         * ValidateSkinning returns a validation report along with skin metrics, if missing weights, or not normalized it is returned as invalid mesh
+         *    the string can be used for console logs, or on screen messages to let the user know there was an issue with importing the mesh
+         */
+        public validateSkinning() : {skinned:boolean, valid:boolean, report:string} {
+            let matricesWeightsExtra = (<FloatArray>this.getVerticesData(VertexBuffer.MatricesWeightsExtraKind));
+            let matricesWeights = (<FloatArray>this.getVerticesData(VertexBuffer.MatricesWeightsKind));
+            if (matricesWeights===null || this.skeleton==null)
+            {
+                return {skinned:false, valid: true, report:"not skinned"}
+            }
+
+            let numWeights = matricesWeights.length;
+            let numberNotSorted :number = 0;
+            let missingWeights :number  = 0;
+            let maxUsedWeights :number  = 0;
+            let numberNotNormalized :number  = 0;
+            let numInfluences :number  = matricesWeightsExtra===null ? 4 : 8;
+            var usedWeightCounts = new Array<number>();
+            for (var a=0; a<=numInfluences;a++){ 
+                usedWeightCounts[a]=0;
+            }
+            const toleranceEpsilon :number = 0.001;
+
+            for (var a=0; a<numWeights; a+=4){
+
+                let lastWeight :number = matricesWeights[a];
+                var t = lastWeight;
+                let usedWeights:number = t===0? 0: 1;
+
+                for (var b=1; b<numInfluences; b++){
+                    var d = b<4? matricesWeights[a+b]:matricesWeightsExtra[a+b-4];
+                    if (d>lastWeight) numberNotSorted++;
+                    if (d!==0) usedWeights++;
+                    t+=d;
+                    lastWeight = d;
+                }
+                // count the buffer weights usage
+                usedWeightCounts[usedWeights]++;
+
+                // max influences
+                if (usedWeights>maxUsedWeights) maxUsedWeights = usedWeights;
+
+                // check for invalid weight and just set it to 1.
+                if (t===0)
+                {
+                    missingWeights++;
+                } 
+                else{
+                    // renormalize so everything adds to 1 use reciprical 
+                    let recip = 1 / t;
+                    let tolerance = 0;
+                    for (b=0; b<numInfluences; b++)
+                    {
+                        if (b<4)
+                            tolerance += Math.abs(matricesWeights[a+b] - (matricesWeights[a+b]*recip));
+                        else
+                            tolerance += Math.abs(matricesWeightsExtra[a+b-4] - (matricesWeightsExtra[a+b-4]*recip));
+                    }
+                    // arbitary epsilon value for dicdating not normalized
+                    if (tolerance > toleranceEpsilon) numberNotNormalized++;
+                }   
+            }
+
+            // validate bone indices are in range of the skeleton
+            let numBones:number = this.skeleton.bones.length;
+            let matricesIndices = (<FloatArray>this.getVerticesData(VertexBuffer.MatricesIndicesKind));
+            let matricesIndicesExtra = (<FloatArray>this.getVerticesData(VertexBuffer.MatricesIndicesExtraKind));
+            let numBadBoneIndices : number = 0;
+            for (var a=0; a<numWeights; a++)
+            {
+                for (var b=0;b< numInfluences; b++)
+                {
+                    let index = b<4? matricesIndices[b] : matricesIndicesExtra[b-4];
+                    if (index>=numBones||index<0) numBadBoneIndices++;
+                }
+            }
+
+            
+            // log mesh stats
+            var output = "Number of Weights = " + numWeights/4 + "\nMaximum influences = " + maxUsedWeights + 
+                         "\nMissing Weights = " + missingWeights + "\nNot Sorted = " + numberNotSorted +
+                         "\nNot Normalized = " + numberNotNormalized + "\nWeightCounts = [" +usedWeightCounts+"]" +
+                         "\nNumber of bones = " + numBones + "\nBad Bone Indices = " + numBadBoneIndices ;
+            
+            return {skinned:true, valid: missingWeights===0 && numberNotNormalized===0 && numBadBoneIndices===0, report: output};
+        }
+
         /** @hidden */
         public _checkDelayState(): Mesh {
             var scene = this.getScene();
@@ -1987,9 +2096,9 @@
             this._source = null;
 
             // Instances
-            if (this._instancesBuffer) {
-                this._instancesBuffer.dispose();
-                this._instancesBuffer = null;
+            if (this._instanceDataStorage.instancesBuffer) {
+                this._instanceDataStorage.instancesBuffer.dispose();
+                this._instanceDataStorage.instancesBuffer = null;
             }
 
             while (this.instances.length) {

src/Mesh/babylon.meshBuilder.ts

@@ -1,4 +1,5 @@
 module BABYLON {
+
     /**
      * Class containing static functions to help procedurally build meshes
      */
@@ -165,8 +166,9 @@
                 Vector3.FromFloatsToRef(-Number.MAX_VALUE, -Number.MAX_VALUE, -Number.MAX_VALUE, Tmp.Vector3[1]);
                 var positionFunction = (positions: FloatArray) => {
                     var minlg = pathArray[0].length;
+                    var mesh = (<Mesh>instance);
                     var i = 0;
-                    var ns = ((<Mesh>instance)._originalBuilderSideOrientation === Mesh.DOUBLESIDE) ? 2 : 1;
+                    var ns = (mesh._originalBuilderSideOrientation === Mesh.DOUBLESIDE) ? 2 : 1;
                     for (var si = 1; si <= ns; si++) {
                         for (var p = 0; p < pathArray.length; p++) {
                             var path = pathArray[p];
@@ -198,7 +200,7 @@
                                 j++;
                                 i += 3;
                             }
-                            if ((<any>instance)._closePath) {
+                            if (mesh._creationDataStorage && mesh._creationDataStorage.closePath) {
                                 positions[i] = path[0].x;
                                 positions[i + 1] = path[0].y;
                                 positions[i + 2] = path[0].z;
@@ -236,13 +238,13 @@
                     var params = instance.isFacetDataEnabled ? instance.getFacetDataParameters() : null;
                     VertexData.ComputeNormals(positions, indices, normals, params);
 
-                    if ((<any>instance)._closePath) {
+                    if (instance._creationDataStorage && instance._creationDataStorage.closePath) {
                         var indexFirst: number = 0;
                         var indexLast: number = 0;
                         for (var p = 0; p < pathArray.length; p++) {
-                            indexFirst = (<any>instance)._idx[p] * 3;
+                            indexFirst = instance._creationDataStorage!.idx[p] * 3;
                             if (p + 1 < pathArray.length) {
-                                indexLast = ((<any>instance)._idx[p + 1] - 1) * 3;
+                                indexLast = (instance._creationDataStorage!.idx[p + 1] - 1) * 3;
                             }
                             else {
                                 indexLast = normals.length - 3;
@@ -266,12 +268,13 @@
 
                 var ribbon = new Mesh(name, scene);
                 ribbon._originalBuilderSideOrientation = sideOrientation;
+                ribbon._creationDataStorage = new _CreationDataStorage();
 
                 var vertexData = VertexData.CreateRibbon(options);
                 if (closePath) {
-                    (<any>ribbon)._idx = (<any>vertexData)._idx;
+                    ribbon._creationDataStorage.idx = (<any>vertexData)._idx;
                 }
-                (<any>ribbon)._closePath = closePath;
+                ribbon._creationDataStorage.closePath = closePath;
                 (<any>ribbon)._closeArray = closeArray;
 
                 vertexData.applyToMesh(ribbon, updatable);
@@ -500,7 +503,9 @@
                         lg += curvect.length();
                     }
                     shft = lg / nbSeg;
-                    dashshft = (<any>instance).dashSize * shft / ((<any>instance).dashSize + (<any>instance).gapSize);
+                    let dashSize = instance!._creationDataStorage!.dashSize;
+                    let gapSize = instance!._creationDataStorage!.gapSize;
+                    dashshft = dashSize * shft / (dashSize + gapSize);
                     for (i = 0; i < points.length - 1; i++) {
                         points[i + 1].subtractToRef(points[i], curvect);
                         nb = Math.floor(curvect.length() / shft);
@@ -532,8 +537,10 @@
             var dashedLines = new LinesMesh(name, scene);
             var vertexData = VertexData.CreateDashedLines(options);
             vertexData.applyToMesh(dashedLines, options.updatable);
-            (<any>dashedLines).dashSize = dashSize;
-            (<any>dashedLines).gapSize = gapSize;
+
+            dashedLines._creationDataStorage = new _CreationDataStorage();
+            dashedLines._creationDataStorage.dashSize = dashSize;
+            dashedLines._creationDataStorage.gapSize = gapSize;
             return dashedLines;
         }
 
@@ -940,12 +947,13 @@
             var path = options.path;
             var instance = options.instance;
             var radius = 1.0;
-            if (instance) {
-                radius = (<any>instance).radius;
-            }
+            
             if (options.radius !== undefined) {
                 radius = options.radius;
-            };
+            } else if (instance) {
+                radius = instance._creationDataStorage!.radius;
+            }
+
             var tessellation = options.tessellation || 64 | 0;
             var radiusFunction = options.radiusFunction || null;
             var cap = options.cap || Mesh.NO_CAP;
@@ -1020,13 +1028,15 @@
             var pathArray;
             if (instance) { // tube update
                 var arc = options.arc || (<any>instance).arc;
-                path3D = ((<any>instance).path3D).update(path);
-                pathArray = tubePathArray(path, path3D, (<any>instance).pathArray, radius, (<any>instance).tessellation, radiusFunction, (<any>instance).cap, arc);
+                let storage = instance._creationDataStorage!;
+                path3D =  storage.path3D.update(path);
+                pathArray = tubePathArray(path, path3D, storage.pathArray, radius, storage.tessellation, radiusFunction, storage.cap, arc);
                 instance = MeshBuilder.CreateRibbon("", { pathArray: pathArray, instance: instance });
-                (<any>instance).path3D = path3D;
-                (<any>instance).pathArray = pathArray;
-                (<any>instance).arc = arc;
-                (<any>instance).radius = radius;
+                instance._creationDataStorage = new _CreationDataStorage();
+                instance._creationDataStorage.path3D = path3D;
+                instance._creationDataStorage.pathArray = pathArray;
+                instance._creationDataStorage.arc = arc;
+                instance._creationDataStorage.radius = radius;
 
                 return instance;
             }
@@ -1037,12 +1047,13 @@
             cap = (cap < 0 || cap > 3) ? 0 : cap;
             pathArray = tubePathArray(path, path3D, newPathArray, radius, tessellation, radiusFunction, cap, options.arc);
             var tube = MeshBuilder.CreateRibbon(name, { pathArray: pathArray, closePath: true, closeArray: false, updatable: updatable, sideOrientation: sideOrientation, invertUV: invertUV, frontUVs: options.frontUVs, backUVs: options.backUVs }, scene);
-            (<any>tube).pathArray = pathArray;
-            (<any>tube).path3D = path3D;
-            (<any>tube).tessellation = tessellation;
-            (<any>tube).cap = cap;
-            (<any>tube).arc = options.arc;
-            (<any>tube).radius = radius;
+            tube._creationDataStorage = new _CreationDataStorage();
+            tube._creationDataStorage.pathArray = pathArray;
+            tube._creationDataStorage.path3D = path3D;
+            tube._creationDataStorage.tessellation = tessellation;
+            tube._creationDataStorage.cap = cap;
+            tube._creationDataStorage.arc = options.arc;
+            tube._creationDataStorage.radius = radius;
 
             return tube;
         }
@@ -1383,8 +1394,9 @@
             var path3D;
             var pathArray;
             if (instance) { // instance update
-                path3D = ((<any>instance).path3D).update(curve);
-                pathArray = extrusionPathArray(shape, curve, (<any>instance).path3D, (<any>instance).pathArray, scale, rotation, scaleFunction, rotateFunction, (<any>instance).cap, custom);
+                let storage = instance._creationDataStorage!;
+                path3D =  storage.path3D.update(curve);
+                pathArray = extrusionPathArray(shape, curve, storage.path3D, storage.pathArray, scale, rotation, scaleFunction, rotateFunction, storage.cap, custom);
                 instance = Mesh.CreateRibbon("", pathArray, false, false, 0, scene || undefined, false, 0, instance);
 
                 return instance;
@@ -1395,9 +1407,10 @@
             cap = (cap < 0 || cap > 3) ? 0 : cap;
             pathArray = extrusionPathArray(shape, curve, path3D, newShapePaths, scale, rotation, scaleFunction, rotateFunction, cap, custom);
             var extrudedGeneric = MeshBuilder.CreateRibbon(name, { pathArray: pathArray, closeArray: rbCA, closePath: rbCP, updatable: updtbl, sideOrientation: side, invertUV: invertUV, frontUVs: frontUVs || undefined, backUVs: backUVs || undefined }, scene);
-            (<any>extrudedGeneric).pathArray = pathArray;
-            (<any>extrudedGeneric).path3D = path3D;
-            (<any>extrudedGeneric).cap = cap;
+            extrudedGeneric._creationDataStorage = new _CreationDataStorage();
+            extrudedGeneric._creationDataStorage.pathArray = pathArray;
+            extrudedGeneric._creationDataStorage.path3D = path3D;
+            extrudedGeneric._creationDataStorage.cap = cap;
 
             return extrudedGeneric;
         }

src/Mesh/babylon.vertexBuffer.ts

@@ -1,4 +1,7 @@
 module BABYLON {
+    /**
+     * Specialized buffer used to store vertex data
+     */
     export class VertexBuffer {
         /** @hidden */
         public _buffer: Buffer;
@@ -148,37 +151,44 @@
         }
 
         /**
-         * Returns the kind of the VertexBuffer (string).  
+         * Returns the kind of the VertexBuffer (string)
+         * @returns a string
          */
         public getKind(): string {
             return this._kind;
         }
 
         // Properties
+
         /**
-         * Boolean : is the VertexBuffer updatable ?
+         * Gets a boolean indicating if the VertexBuffer is updatable?
+         * @returns true if the buffer is updatable
          */
         public isUpdatable(): boolean {
             return this._buffer.isUpdatable();
         }
 
         /**
-         * Returns an array of numbers or a typed array containing the VertexBuffer data.  
+         * Gets current buffer's data
+         * @returns a DataArray or null
          */
         public getData(): Nullable<DataArray> {
             return this._buffer.getData();
         }
 
         /**
-         * Returns the WebGLBuffer associated to the VertexBuffer.  
+         * Gets underlying native buffer
+         * @returns underlying native buffer
          */
         public getBuffer(): Nullable<WebGLBuffer> {
             return this._buffer.getBuffer();
         }
 
         /**
-         * Returns the stride as a multiple of the type byte length.
+         * Gets the stride in float32 units (i.e. byte stride / 4).
+         * May not be an integer if the byte stride is not divisible by 4.
          * DEPRECATED. Use byteStride instead.
+         * @returns the stride in float32 units
          */
         public getStrideSize(): number {
             return this.byteStride / VertexBuffer.GetTypeByteLength(this.type);
@@ -187,20 +197,23 @@
         /**
          * Returns the offset as a multiple of the type byte length.
          * DEPRECATED. Use byteOffset instead.
+         * @returns the offset in bytes
          */
         public getOffset(): number {
             return this.byteOffset / VertexBuffer.GetTypeByteLength(this.type);
         }
 
         /**
-         * Returns the number of components per vertex attribute (integer).  
+         * Returns the number of components per vertex attribute (integer)
+         * @returns the size in float 
          */
         public getSize(): number {
             return this._size;
         }
 
         /**
-         * Boolean : is the WebGLBuffer of the VertexBuffer instanced now ?
+         * Gets a boolean indicating is the internal buffer of the VertexBuffer is instanced
+         * @returns true if this buffer is instanced
          */
         public getIsInstanced(): boolean {
             return this._instanced;
@@ -208,6 +221,7 @@
 
         /**
          * Returns the instancing divisor, zero for non-instanced (integer).  
+         * @returns a number
          */
         public getInstanceDivisor(): number {
             return this._instanceDivisor;
@@ -216,20 +230,20 @@
         // Methods
 
         /**
-         * Creates the underlying WebGLBuffer from the passed numeric array or Float32Array.  
-         * Returns the created WebGLBuffer.   
+         * Store data into the buffer. If the buffer was already used it will be either recreated or updated depending on isUpdatable property
+         * @param data defines the data to store
          */
         public create(data?: DataArray): void {
-            return this._buffer.create(data);
+            this._buffer.create(data);
         }
 
         /**
-         * Updates the underlying WebGLBuffer according to the passed numeric array or Float32Array.  
+         * Updates the underlying buffer according to the passed numeric array or Float32Array.  
          * This function will create a new buffer if the current one is not updatable
-         * Returns the updated WebGLBuffer.  
+         * @param data defines the data to store 
          */
         public update(data: DataArray): void {
-            return this._buffer.update(data);
+            this._buffer.update(data);
         }
 
         /**
@@ -262,76 +276,62 @@
         }
 
         // Enums
-        private static _PositionKind = "position";
-        private static _NormalKind = "normal";
-        private static _TangentKind = "tangent";
-        private static _UVKind = "uv";
-        private static _UV2Kind = "uv2";
-        private static _UV3Kind = "uv3";
-        private static _UV4Kind = "uv4";
-        private static _UV5Kind = "uv5";
-        private static _UV6Kind = "uv6";
-        private static _ColorKind = "color";
-        private static _MatricesIndicesKind = "matricesIndices";
-        private static _MatricesWeightsKind = "matricesWeights";
-        private static _MatricesIndicesExtraKind = "matricesIndicesExtra";
-        private static _MatricesWeightsExtraKind = "matricesWeightsExtra";
-
-        public static get PositionKind(): string {
-            return VertexBuffer._PositionKind;
-        }
-
-        public static get NormalKind(): string {
-            return VertexBuffer._NormalKind;
-        }
-
-        public static get TangentKind(): string {
-            return VertexBuffer._TangentKind;
-        }
-
-        public static get UVKind(): string {
-            return VertexBuffer._UVKind;
-        }
-
-        public static get UV2Kind(): string {
-            return VertexBuffer._UV2Kind;
-        }
-
-        public static get UV3Kind(): string {
-            return VertexBuffer._UV3Kind;
-        }
-
-        public static get UV4Kind(): string {
-            return VertexBuffer._UV4Kind;
-        }
-
-        public static get UV5Kind(): string {
-            return VertexBuffer._UV5Kind;
-        }
-
-        public static get UV6Kind(): string {
-            return VertexBuffer._UV6Kind;
-        }
-
-        public static get ColorKind(): string {
-            return VertexBuffer._ColorKind;
-        }
-
-        public static get MatricesIndicesKind(): string {
-            return VertexBuffer._MatricesIndicesKind;
-        }
-
-        public static get MatricesWeightsKind(): string {
-            return VertexBuffer._MatricesWeightsKind;
-        }
-
-        public static get MatricesIndicesExtraKind(): string {
-            return VertexBuffer._MatricesIndicesExtraKind;
-        }
-
-        public static get MatricesWeightsExtraKind(): string {
-            return VertexBuffer._MatricesWeightsExtraKind;
-        }
+        /**
+         * Positions
+         */
+        public static readonly PositionKind = "position";
+        /**
+         * Normals
+         */
+        public static readonly NormalKind = "normal";
+        /**
+         * Tangents
+         */
+        public static readonly TangentKind = "tangent";
+        /**
+         * Texture coordinates
+         */
+        public static readonly UVKind = "uv";
+        /**
+         * Texture coordinates 2
+         */
+        public static readonly UV2Kind = "uv2";
+        /**
+         * Texture coordinates 3
+         */
+        public static readonly UV3Kind = "uv3";
+        /**
+         * Texture coordinates 4
+         */
+        public static readonly UV4Kind = "uv4";
+        /**
+         * Texture coordinates 5
+         */
+        public static readonly UV5Kind = "uv5";
+        /**
+         * Texture coordinates 6
+         */
+        public static readonly UV6Kind = "uv6";
+        /**
+         * Colors
+         */
+        public static readonly ColorKind = "color";
+        /**
+         * Matrix indices (for bones)
+         */
+        public static readonly MatricesIndicesKind = "matricesIndices";
+        /**
+         * Matrix weights (for bones)
+         */
+        public static readonly MatricesWeightsKind = "matricesWeights";
+        /**
+         * Additional matrix indices (for bones)
+         */
+        public static readonly MatricesIndicesExtraKind = "matricesIndicesExtra";
+        /**
+         * Additional matrix weights (for bones)
+         */
+        public static readonly MatricesWeightsExtraKind = "matricesWeightsExtra";
 
         /**
          * Deduces the stride given a kind.

src/Shaders/gpuUpdateParticles.vertex.fx

@@ -313,7 +313,7 @@ void main() {
     float power = emitPower.x + (emitPower.y - emitPower.x) * randoms.a;
 
     outPosition = (emitterWM * vec4(position, 1.)).xyz;
-    vec3 initial = (emitterWM * vec4(normalize(direction), 0.)).xyz;
+    vec3 initial = (emitterWM * vec4(direction, 0.)).xyz;
     outDirection = initial * power;
 #ifndef BILLBOARD        
     outInitialDirection = initial;

src/babylon.node.ts

@@ -6,7 +6,7 @@
     export type NodeConstructor = (name: string, scene: Scene, options?: any) => () => Node;
 
     /**
-     * Node is the basic class for all scene objects (Mesh, Light Camera).
+     * Node is the basic class for all scene objects (Mesh, Light, Camera.)
      */
     export class Node implements IBehaviorAware<Node> {
         private static _NodeConstructors: {[key: string]: any} = {};