Merge remote-tracking branch 'BabylonJS/master'

dist/preview release/what's new.md

@@ -12,6 +12,8 @@
  - Multi-platform Compressed Textures for Desktops & Mobile Devices with fall back.  Batch (dos) scripts to convert entire directories of .jpg's & .png's ([jcpalmer](https://github.com/Palmer-JC))
 
 ### Updates
+- Added `HDRCubeTextureAssetTask` to AssetManager ([deltakosh](https://github.com/deltakosh))
+- Engine now uses range based fog ([deltakosh](https://github.com/deltakosh))
 - `VertexBuffer.updatable` is now serialized ([deltakosh](https://github.com/deltakosh))
 - Added intersectsMeshes to Ray ([abow](https://github.com/abow))
 - New RayHelper class for easily viewing and attaching a ray to a mesh.  [Demo](http://www.babylonjs-playground.com/#ZHDBJ#34) - ([abow](https://github.com/abow))
@@ -20,6 +22,7 @@
 - `Effect.getVertexShaderSource()` and `Effect.getFragmentShaderSource()` now returns the effective shader code (including evaluation of #define) ([deltakosh](https://github.com/deltakosh))
 - GroundMesh : `getHeightAtCoordinates()`, `getNormalAtCoordinates()` and `getNormalAtCoordinatesToRef()` can now work with rotated grounds ([jerome](https://github.com/jbousquie))  
 - `GroundMesh`, `facetData` and `SolidParticleSystem` improvement in normal computations ([jerome](https://github.com/jbousquie))   
+- Added `AbstractMesh.addRotation()` ([jerome](https://github.com/jbousquie))  
  
 ### Canvas2D
 

src/Bones/babylon.bone.ts

@@ -5,7 +5,7 @@
         public length: number;
 
         private _skeleton: Skeleton;
-        public _matrix: Matrix;
+        private _localMatrix: Matrix;
         private _restPose: Matrix;
         private _baseMatrix: Matrix;
         private _worldTransform = new Matrix();
@@ -17,11 +17,23 @@
         private _scaleVector = new Vector3(1, 1, 1);
         private _negateScaleChildren = new Vector3(1, 1, 1);
         private _scalingDeterminant = 1;
+
+        get _matrix():Matrix{
+            return this._localMatrix;
+        }
+
+        set _matrix(val:Matrix){
+            if(this._localMatrix){
+                this._localMatrix.copyFrom(val);
+            }else{
+                this._localMatrix = val;
+            }
+        }
         
         constructor(public name: string, skeleton: Skeleton, parentBone: Bone, matrix: Matrix, restPose?: Matrix) {
             super(name, skeleton.getScene());
             this._skeleton = skeleton;
-            this._matrix = matrix;
+            this._localMatrix = matrix;
             this._baseMatrix = matrix;
             this._restPose = restPose ? restPose : matrix.clone();
 
@@ -47,7 +59,7 @@
         }
 
         public getLocalMatrix(): Matrix {
-            return this._matrix;
+            return this._localMatrix;
         }
 
         public getBaseMatrix(): Matrix {
@@ -77,7 +89,7 @@
         // Methods
         public updateMatrix(matrix: Matrix, updateDifferenceMatrix = true): void {
             this._baseMatrix = matrix.clone();
-            this._matrix = matrix.clone();
+            this._localMatrix = matrix.clone();
 
             this._skeleton._markAsDirty();
 
@@ -171,6 +183,12 @@
             return true;
         }
 
+        /**
+         * Translate the bone in local or world space.
+         * @param vec The amount to translate the bone.
+         * @param space The space that the translation is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public translate (vec: Vector3, space = Space.LOCAL, mesh?: AbstractMesh): void {
 
             var lm = this.getLocalMatrix();
@@ -211,6 +229,12 @@
 	        
         }
 
+        /**
+         * Set the postion of the bone in local or world space.
+         * @param position The position to set the bone.
+         * @param space The space that the position is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setPosition (position: Vector3, space = Space.LOCAL, mesh?: AbstractMesh): void {
 
             var lm = this.getLocalMatrix();
@@ -248,12 +272,24 @@
 	        
         }
 
+        /**
+         * Set the absolute postion of the bone (world space).
+         * @param position The position to set the bone.
+         * @param mesh The mesh that this bone is attached to.
+         */
         public setAbsolutePosition(position:Vector3, mesh?: AbstractMesh){
 
             this.setPosition(position, Space.WORLD, mesh);
 
         }
 
+        /**
+         * Set the scale of the bone on the x, y and z axes.
+         * @param x The scale of the bone on the x axis.
+         * @param x The scale of the bone on the y axis.
+         * @param z The scale of the bone on the z axis.
+         * @param scaleChildren Set this to true if children of the bone should be scaled.
+         */
         public setScale (x: number, y: number, z: number, scaleChildren = false): void {
 
             if (this.animations[0] && !this.animations[0].isStopped()) {
@@ -269,6 +305,13 @@
 
         }
 
+        /**
+         * Scale the bone on the x, y and z axes. 
+         * @param x The amount to scale the bone on the x axis.
+         * @param x The amount to scale the bone on the y axis.
+         * @param z The amount to scale the bone on the z axis.
+         * @param scaleChildren Set this to true if children of the bone should be scaled.
+         */
         public scale (x: number, y: number, z: number, scaleChildren = false): void {
 	
             var locMat = this.getLocalMatrix();
@@ -324,6 +367,14 @@
 
         }
 
+        /**
+         * Set the yaw, pitch, and roll of the bone in local or world space.
+         * @param yaw The rotation of the bone on the y axis.
+         * @param pitch The rotation of the bone on the x axis.
+         * @param roll The rotation of the bone on the z axis.
+         * @param space The space that the axes of rotation are in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setYawPitchRoll (yaw: number, pitch: number, roll: number, space = Space.LOCAL, mesh?: AbstractMesh): void {
 	
             var rotMat = Tmp.Matrix[0];
@@ -339,6 +390,13 @@
             
         }
 
+        /**
+         * Rotate the bone on an axis in local or world space.
+         * @param axis The axis to rotate the bone on.
+         * @param amount The amount to rotate the bone.
+         * @param space The space that the axis is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public rotate (axis: Vector3, amount: number, space = Space.LOCAL, mesh?: AbstractMesh): void {
             
             var rmat = Tmp.Matrix[0];
@@ -352,6 +410,13 @@
             
         }
 
+        /**
+         * Set the rotation of the bone to a particular axis angle in local or world space.
+         * @param axis The axis to rotate the bone on.
+         * @param angle The angle that the bone should be rotated to.
+         * @param space The space that the axis is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setAxisAngle (axis: Vector3, angle: number, space = Space.LOCAL, mesh?: AbstractMesh): void {
 
             var rotMat = Tmp.Matrix[0];
@@ -365,12 +430,24 @@
 
         }
 
+        /**
+         * Set the euler rotation of the bone in local of world space.
+         * @param rotation The euler rotation that the bone should be set to.
+         * @param space The space that the rotation is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setRotation (rotation: Vector3, space = Space.LOCAL, mesh?: AbstractMesh): void {
             
             this.setYawPitchRoll(rotation.y, rotation.x, rotation.z, space, mesh);
 
         }
 
+        /**
+         * Set the quaternion rotation of the bone in local of world space.
+         * @param quat The quaternion rotation that the bone should be set to.
+         * @param space The space that the rotation is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setRotationQuaternion (quat: Quaternion, space = Space.LOCAL, mesh?: AbstractMesh): void {
 
             var rotMatInv = Tmp.Matrix[0];
@@ -386,6 +463,12 @@
 
         }
 
+        /**
+         * Set the rotation matrix of the bone in local of world space.
+         * @param rotMat The rotation matrix that the bone should be set to.
+         * @param space The space that the rotation is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         */
         public setRotationMatrix (rotMat: Matrix, space = Space.LOCAL, mesh?: AbstractMesh): void {
 
             var rotMatInv = Tmp.Matrix[0];
@@ -487,18 +570,32 @@
 
         }
 
+        /**
+         * Get the scale of the bone
+         * @returns the scale of the bone
+         */
         public getScale(): Vector3 {
             
             return this._scaleVector.clone();
             
         }
 
+        /**
+         * Copy the scale of the bone to a vector3.
+         * @param result The vector3 to copy the scale to
+         */
         public getScaleToRef(result: Vector3): void {
 	
             result.copyFrom(this._scaleVector);
             
         }
 
+        /**
+         * Get the position of the bone in local or world space.
+         * @param space The space that the returned position is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @returns The position of the bone
+         */
         public getPosition (space = Space.LOCAL, mesh?: AbstractMesh): Vector3 {
 
             var pos = Vector3.Zero();
@@ -509,6 +606,12 @@
 
         }
 
+        /**
+         * Copy the position of the bone to a vector3 in local or world space.
+         * @param space The space that the returned position is in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @param result The vector3 to copy the position to.
+         */
         public getPositionToRef (space = Space.LOCAL, mesh: AbstractMesh, result: Vector3): void {
 
             if(space == Space.LOCAL){
@@ -540,6 +643,11 @@
 
         }
 
+        /**
+         * Get the absolute position of the bone (world space).
+         * @param mesh The mesh that this bone is attached to.
+         * @returns The absolute position of the bone
+         */
         public getAbsolutePosition (mesh?: AbstractMesh): Vector3 {
 
             var pos = Vector3.Zero();
@@ -550,18 +658,26 @@
 
         }
 
+        /**
+         * Copy the absolute position of the bone (world space) to the result param.
+         * @param mesh The mesh that this bone is attached to.
+         * @param result The vector3 to copy the absolute position to.
+         */
         public getAbsolutePositionToRef (mesh: AbstractMesh, result: Vector3) {
 
             this.getPositionToRef(Space.WORLD, mesh, result);
 
         }
 
+        /**
+         * Compute the absolute transforms of this bone and its children.
+         */
         public computeAbsoluteTransforms (): void {
 
             if (this._parent) {
-                this._matrix.multiplyToRef(this._parent._absoluteTransform, this._absoluteTransform);
+                this._localMatrix.multiplyToRef(this._parent._absoluteTransform, this._absoluteTransform);
             } else {
-                this._absoluteTransform.copyFrom(this._matrix);
+                this._absoluteTransform.copyFrom(this._localMatrix);
 
                 var poseMatrix = this._skeleton.getPoseMatrix();
 
@@ -579,7 +695,7 @@
 
         }
 
-        private _syncScaleVector = function(): void{
+        private _syncScaleVector(): void{
             
             var lm = this.getLocalMatrix();
             
@@ -605,6 +721,12 @@
 
         }
 
+        /**
+         * Get the world direction from an axis that is in the local space of the bone.
+         * @param localAxis The local direction that is used to compute the world direction.
+         * @param mesh The mesh that this bone is attached to.
+         * @returns The world direction
+         */
         public getDirection (localAxis: Vector3, mesh?: AbstractMesh): Vector3{
 
             var result = Vector3.Zero();
@@ -615,6 +737,12 @@
 
         }
 
+        /**
+         * Copy the world direction to a vector3 from an axis that is in the local space of the bone.
+         * @param localAxis The local direction that is used to compute the world direction.
+         * @param mesh The mesh that this bone is attached to.
+         * @param result The vector3 that the world direction will be copied to.
+         */
         public getDirectionToRef (localAxis: Vector3, mesh: AbstractMesh, result: Vector3): void {
 
             this._skeleton.computeAbsoluteTransforms();
@@ -633,6 +761,12 @@
 
         }
 
+        /**
+         * Get the euler rotation of the bone in local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @returns The euler rotation
+         */
         public getRotation(space = Space.LOCAL, mesh?: AbstractMesh): Vector3 {
 
             var result = Vector3.Zero();
@@ -643,6 +777,12 @@
 
         }
 
+        /**
+         * Copy the euler rotation of the bone to a vector3.  The rotation can be in either local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @param result The vector3 that the rotation should be copied to.
+         */
         public getRotationToRef(space = Space.LOCAL, mesh: AbstractMesh, result: Vector3): void {
 
             var quat = Tmp.Quaternion[0];
@@ -653,6 +793,12 @@
 
         }
 
+        /**
+         * Get the quaternion rotation of the bone in either local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @returns The quaternion rotation
+         */
         public getRotationQuaternion(space = Space.LOCAL, mesh?: AbstractMesh): Quaternion {
 
             var result = Quaternion.Identity();
@@ -663,6 +809,12 @@
 
         }
 
+        /**
+         * Copy the quaternion rotation of the bone to a quaternion.  The rotation can be in either local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @param result The quaternion that the rotation should be copied to.
+         */
         public getRotationQuaternionToRef( space = Space.LOCAL, mesh: AbstractMesh, result: Quaternion): void{
 
             if(space == Space.LOCAL){
@@ -689,6 +841,12 @@
             }
         }
 
+        /**
+         * Get the rotation matrix of the bone in local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @returns The rotation matrix
+         */
         public getRotationMatrix(space = Space.LOCAL, mesh: AbstractMesh): Matrix {
 
             var result = Matrix.Identity();
@@ -699,6 +857,12 @@
 
         }
 
+        /**
+         * Copy the rotation matrix of the bone to a matrix.  The rotation can be in either local or world space.
+         * @param space The space that the rotation should be in.
+         * @param mesh The mesh that this bone is attached to.  This is only used in world space.
+         * @param result The quaternion that the rotation should be copied to.
+         */
         public getRotationMatrixToRef(space = Space.LOCAL, mesh: AbstractMesh, result: Matrix): void{
 
             if(space == Space.LOCAL){
@@ -726,6 +890,12 @@
 
         }
 
+        /**
+         * Get the world position of a point that is in the local space of the bone.
+         * @param position The local position
+         * @param mesh The mesh that this bone is attached to.
+         * @returns The world position
+         */
         public getAbsolutePositionFromLocal(position:Vector3, mesh?:AbstractMesh): Vector3{
 
             var result = Vector3.Zero();
@@ -736,6 +906,12 @@
 
         }
 
+        /**
+         * Get the world position of a point that is in the local space of the bone and copy it to the result param.
+         * @param position The local position
+         * @param mesh The mesh that this bone is attached to.
+         * @param result The vector3 that the world position should be copied to.
+         */
         public getAbsolutePositionFromLocalToRef(position:Vector3, mesh:AbstractMesh, result:Vector3): void{
 
             this._skeleton.computeAbsoluteTransforms();
@@ -753,6 +929,12 @@
 
         }
 
+        /**
+         * Get the local position of a point that is in world space.
+         * @param position The world position
+         * @param mesh The mesh that this bone is attached to.
+         * @returns The local position
+         */
         public getLocalPositionFromAbsolute(position:Vector3, mesh?:AbstractMesh): Vector3{
 
             var result = Vector3.Zero();
@@ -763,6 +945,12 @@
 
         }
 
+        /**
+         * Get the local position of a point that is in world space and copy it to the result param.
+         * @param position The world position
+         * @param mesh The mesh that this bone is attached to.
+         * @param result The vector3 that the local position should be copied to.
+         */
         public getLocalPositionFromAbsoluteToRef(position:Vector3, mesh:AbstractMesh, result:Vector3): void{
 
             this._skeleton.computeAbsoluteTransforms();

src/Cameras/babylon.freeCamera.ts

@@ -103,6 +103,17 @@
             this.cameraRotation = new Vector2(0, 0);
         }
 
+        // Collisions
+        private _collisionMask = -1;
+        
+        public get collisionMask(): number {
+            return this._collisionMask;
+        }
+        
+        public set collisionMask(mask: number) {
+            this._collisionMask = !isNaN(mask) ? mask : -1;
+        }
+	 
         public _collideWithWorld(velocity: Vector3): void {
             var globalPosition: Vector3;
 
@@ -114,7 +125,8 @@
 
             globalPosition.subtractFromFloatsToRef(0, this.ellipsoid.y, 0, this._oldPosition);
             this._collider.radius = this.ellipsoid;
-
+	        this._collider.collisionMask = this._collisionMask;
+		
             //no need for clone, as long as gravity is not on.
             var actualVelocity = velocity;
 			

src/Collisions/babylon.collider.ts

@@ -86,6 +86,16 @@
         private _slidePlaneNormal = Vector3.Zero();
         private _displacementVector = Vector3.Zero();
 
+        private _collisionMask = -1;
+        
+        public get collisionMask(): number {
+            return this._collisionMask;
+        }
+        
+        public set collisionMask(mask: number) {
+            this._collisionMask = !isNaN(mask) ? mask : -1;
+        }
+
         // Methods
         public _initialize(source: Vector3, dir: Vector3, e: number): void {
             this.velocity = dir;

src/Collisions/babylon.collisionCoordinator.ts

@@ -385,12 +385,15 @@ module BABYLON {
                 return;
             }
 
+            // Check if this is a mesh else camera or -1
+            var collisionMask = (excludedMesh ? excludedMesh.collisionMask : collider.collisionMask);
+
             collider._initialize(position, velocity, closeDistance);
 
             // Check all meshes
             for (var index = 0; index < this._scene.meshes.length; index++) {
                 var mesh = this._scene.meshes[index];
-                if (mesh.isEnabled() && mesh.checkCollisions && mesh.subMeshes && mesh !== excludedMesh) {
+                if (mesh.isEnabled() && mesh.checkCollisions && mesh.subMeshes && mesh !== excludedMesh &&  ((collisionMask & mesh.collisionMask) !== 0)) {
                     mesh._checkCollision(collider);
                 }
             }

src/Materials/Textures/babylon.hdrCubeTexture.ts

@@ -25,6 +25,8 @@ module BABYLON {
         private _size: number;
         private _usePMREMGenerator: boolean;
         private _isBABYLONPreprocessed = false;
+        private _onLoad: () => void = null;
+        private _onError: () => void = null;
 
         /**
          * The texture URL.
@@ -58,7 +60,7 @@ module BABYLON {
          * @param useInGammaSpace Specifies if the texture will be use in gamma or linear space (the PBR material requires those texture in linear space, but the standard material would require them in Gamma space)
          * @param usePMREMGenerator Specifies wether or not to generate the CubeMap through CubeMapGen to avoid seams issue at run time.
          */
-        constructor(url: string, scene: Scene, size?: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false) {
+        constructor(url: string, scene: Scene, size?: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false, onLoad: () => void = null, onError: () => void = null) {
             super(scene);
 
             if (!url) {
@@ -70,6 +72,8 @@ module BABYLON {
             this.hasAlpha = false;
             this.isCube = true;
             this._textureMatrix = Matrix.Identity();
+            this._onLoad = onLoad;
+            this._onError = onError;
 
             if (size) {
                 this._isBABYLONPreprocessed = false;
@@ -233,7 +237,7 @@ module BABYLON {
                 this.getScene().getEngine().getCaps().textureFloat ? BABYLON.Engine.TEXTURETYPE_FLOAT : BABYLON.Engine.TEXTURETYPE_UNSIGNED_INT,
                 this._noMipmap,
                 callback,
-                mipmapGenerator);
+                mipmapGenerator, this._onLoad, this._onError);
         }
 
         /**
@@ -332,7 +336,7 @@ module BABYLON {
                 this.getScene().getEngine().getCaps().textureFloat ? BABYLON.Engine.TEXTURETYPE_FLOAT : BABYLON.Engine.TEXTURETYPE_UNSIGNED_INT,
                 this._noMipmap,
                 callback,
-                mipmapGenerator);
+                mipmapGenerator, this._onLoad, this._onError);                
         }
 
         /**

src/Mesh/babylon.abstractMesh.ts

@@ -50,7 +50,7 @@
             return this._facetNb;
         }
         /**
-         * The number of subdivisions per axis in the partioning space
+         * The number (integer) of subdivisions per axis in the partioning space
          */
         public get partitioningSubdivisions(): number {
             return this._partitioningSubdivisions;
@@ -59,7 +59,7 @@
             this._partitioningSubdivisions = nb;
         } 
         /**
-         * The ratio to apply to the bouding box size to set to the partioning space.  
+         * The ratio (float) to apply to the bouding box size to set to the partioning space.  
          * Ex : 1.01 (default) the partioning space is 1% bigger than the bounding box.
          */
         public get partitioningBBoxRatio(): number {
@@ -69,7 +69,7 @@
             this._partitioningBBoxRatio = ratio;
         }
         /**
-         * Read-only : is the feature facetData enabled ?
+         * Read-only boolean : is the feature facetData enabled ?
          */
         public get isFacetDataEnabled(): boolean {
             return this._facetDataEnabled;
@@ -166,12 +166,22 @@
 
         // Collisions
         private _checkCollisions = false;
+        private _collisionMask = -1;
         public ellipsoid = new Vector3(0.5, 1, 0.5);
         public ellipsoidOffset = new Vector3(0, 0, 0);
         private _collider = new Collider();
         private _oldPositionForCollisions = new Vector3(0, 0, 0);
         private _diffPositionForCollisions = new Vector3(0, 0, 0);
         private _newPositionForCollisions = new Vector3(0, 0, 0);
+        
+        
+        public get collisionMask(): number {
+            return this._collisionMask;
+        }
+        
+        public set collisionMask(mask: number) {
+            this._collisionMask = !isNaN(mask) ? mask : -1;
+        }
 
         // Attach to bone
         private _meshToBoneReferal: AbstractMesh;
@@ -267,7 +277,7 @@
         }
 
         /**
-         * Ratation property : a Vector3 depicting the rotation value in radians around each local axis X, Y, Z. 
+         * Rotation property : a Vector3 depicting the rotation value in radians around each local axis X, Y, Z. 
          * If rotation quaternion is set, this Vector3 will (almost always) be the Zero vector!
          * Default : (0.0, 0.0, 0.0)
          */
@@ -312,32 +322,55 @@
         }
 
         // Methods
-        public updatePoseMatrix(matrix: Matrix) {
+        /**
+         * Copies the paramater passed Matrix into the mesh Pose matrix.  
+         * Returns the AbstractMesh.  
+         */
+        public updatePoseMatrix(matrix: Matrix): AbstractMesh {
             this._poseMatrix.copyFrom(matrix);
+            return this;
         }
 
+        /**
+         * Returns the mesh Pose matrix.  
+         * Returned object : Matrix
+         */
         public getPoseMatrix(): Matrix {
             return this._poseMatrix;
         }
 
-        public disableEdgesRendering(): void {
+        /**
+         * Disables the mesh edger rendering mode.  
+         * Returns the AbstractMesh.  
+         */
+        public disableEdgesRendering(): AbstractMesh {
             if (this._edgesRenderer !== undefined) {
                 this._edgesRenderer.dispose();
                 this._edgesRenderer = undefined;
             }
+            return this;
         }
-        public enableEdgesRendering(epsilon = 0.95, checkVerticesInsteadOfIndices = false) {
+        /**
+         * Enables the edge rendering mode on the mesh.  
+         * This mode makes the mesh edges visible.  
+         * Returns the AbstractMesh.  
+         */
+        public enableEdgesRendering(epsilon = 0.95, checkVerticesInsteadOfIndices = false): AbstractMesh {
             this.disableEdgesRendering();
-
             this._edgesRenderer = new EdgesRenderer(this, epsilon, checkVerticesInsteadOfIndices);
+            return this;
         }
 
+        /**
+         * Returns true if the mesh is blocked. Used by the class Mesh.
+         * Returns the boolean `false` by default.  
+         */
         public get isBlocked(): boolean {
             return false;
         }
 
         /**
-         * Returns this by default, used by the class Mesh.  
+         * Returns the mesh itself by default, used by the class Mesh.  
          * Returned type : AbstractMesh
          */
         public getLOD(camera: Camera): AbstractMesh {
@@ -392,10 +425,11 @@
 
         /**
          * Sets a mesh new object BoundingInfo.
-         * Returns nothing.  
+         * Returns the AbstractMesh.  
          */
-        public setBoundingInfo(boundingInfo: BoundingInfo): void {
+        public setBoundingInfo(boundingInfo: BoundingInfo): AbstractMesh {
             this._boundingInfo = boundingInfo;
+            return this;
         }
 
         public get useBones(): boolean {
@@ -420,7 +454,6 @@
             if (this._masterMesh) {
                 return this._masterMesh.getWorldMatrix();
             }
-
             if (this._currentRenderId !== this.getScene().getRenderId()) {
                 this.computeWorldMatrix();
             }
@@ -437,28 +470,30 @@
 
         /**
          * Returns the current mesh absolute position.
-         * Retuns a Vector3
+         * Retuns a Vector3.
          */
         public get absolutePosition(): Vector3 {
             return this._absolutePosition;
         }
         /**
          * Prevents the World matrix to be computed any longer.
-         * Returns nothing.  
+         * Returns the AbstractMesh.  
          */
-        public freezeWorldMatrix() {
+        public freezeWorldMatrix(): AbstractMesh {
             this._isWorldMatrixFrozen = false;  // no guarantee world is not already frozen, switch off temporarily
             this.computeWorldMatrix(true);
             this._isWorldMatrixFrozen = true;
+            return this;
         }
 
         /**
          * Allows back the World matrix computation. 
-         * Returns nothing.  
+         * Returns the AbstractMesh.  
          */
         public unfreezeWorldMatrix() {
             this._isWorldMatrixFrozen = false;
             this.computeWorldMatrix(true);
+            return this;
         }
 
         /**
@@ -472,11 +507,13 @@
         private static _rotationAxisCache = new Quaternion();
         /**
          * Rotates the mesh around the axis vector for the passed angle (amount) expressed in radians, in the given space.  
-         * space (default LOCAL) can be either BABYLON.Space.LOCAL, either BABYLON.Space.WORLD
+         * space (default LOCAL) can be either BABYLON.Space.LOCAL, either BABYLON.Space.WORLD.
+         * Note that the property `rotationQuaternion` is then automatically updated and the property `rotation` is set to (0,0,0) and no longer used.  
+         * The passed axis is also normalized.  
+         * Returns the AbstractMesh.
          */
-        public rotate(axis: Vector3, amount: number, space?: Space): void {
+        public rotate(axis: Vector3, amount: number, space?: Space): AbstractMesh {
             axis.normalize();
-
             if (!this.rotationQuaternion) {
                 this.rotationQuaternion = Quaternion.RotationYawPitchRoll(this.rotation.y, this.rotation.x, this.rotation.z);
                 this.rotation = Vector3.Zero();
@@ -490,21 +527,21 @@
                 if (this.parent) {
                     var invertParentWorldMatrix = this.parent.getWorldMatrix().clone();
                     invertParentWorldMatrix.invert();
-
                     axis = Vector3.TransformNormal(axis, invertParentWorldMatrix);
                 }
                 rotationQuaternion = Quaternion.RotationAxisToRef(axis, amount, AbstractMesh._rotationAxisCache);
                 rotationQuaternion.multiplyToRef(this.rotationQuaternion, this.rotationQuaternion);
             }
+            return this;
         }
 
         /**
          * Translates the mesh along the axis vector for the passed distance in the given space.  
-         * space (default LOCAL) can be either BABYLON.Space.LOCAL, either BABYLON.Space.WORLD
+         * space (default LOCAL) can be either BABYLON.Space.LOCAL, either BABYLON.Space.WORLD.
+         * Returns the AbstractMesh.
          */
-        public translate(axis: Vector3, distance: number, space?: Space): void {
+        public translate(axis: Vector3, distance: number, space?: Space): AbstractMesh {
             var displacementVector = axis.scale(distance);
-
             if (!space || (space as any) === Space.LOCAL) {
                 var tempV3 = this.getPositionExpressedInLocalSpace().add(displacementVector);
                 this.setPositionWithLocalVector(tempV3);
@@ -512,19 +549,22 @@
             else {
                 this.setAbsolutePosition(this.getAbsolutePosition().add(displacementVector));
             }
+            return this;
         }
 
         /**
          * Adds a rotation step to the mesh current rotation.  
          * x, y, z are Euler angles expressed in radians.  
          * This methods updates the current mesh rotation, either mesh.rotation, either mesh.rotationQuaternion if it's set.  
+         * This means this rotation is made in the mesh local space only.   
          * It's useful to set a custom rotation order different from the BJS standard one YXZ.  
          * Example : this rotates the mesh first around its local X axis, then around its local Z axis, finally around its local Y axis.  
          * ```javascript
          * mesh.addRotation(x1, 0, 0).addRotation(0, 0, z2).addRotation(0, 0, y3);
          * ```
          * Note that `addRotation()` accumulates the passed rotation values to the current ones and computes the .rotation or .rotationQuaternion updated values.  
-         * Under the hood, only quaternions are used. So it's a little faster is you use .rotationQuaternion because it doesn't need to translate them back to Euler angles.  
+         * Under the hood, only quaternions are used. So it's a little faster is you use .rotationQuaternion because it doesn't need to translate them back to Euler angles.   
+         * Returns the AbstractMesh.  
          */
         public addRotation(x: number, y: number, z: number): AbstractMesh {
             var rotationQuaternion;
@@ -544,20 +584,26 @@
             return this;
         }
 
+        /**
+         * Retuns the mesh absolute position in the World.  
+         * Returns a Vector3.
+         */
         public getAbsolutePosition(): Vector3 {
             this.computeWorldMatrix();
             return this._absolutePosition;
         }
 
-        public setAbsolutePosition(absolutePosition: Vector3): void {
+        /**
+         * Sets the mesh absolute position in the World from a Vector3 or an Array(3).
+         * Returns the AbstractMesh.  
+         */
+        public setAbsolutePosition(absolutePosition: Vector3): AbstractMesh {
             if (!absolutePosition) {
                 return;
             }
-
             var absolutePositionX;
             var absolutePositionY;
             var absolutePositionZ;
-
             if (absolutePosition.x === undefined) {
                 if (arguments.length < 3) {
                     return;
@@ -571,20 +617,19 @@
                 absolutePositionY = absolutePosition.y;
                 absolutePositionZ = absolutePosition.z;
             }
-
             if (this.parent) {
                 var invertParentWorldMatrix = this.parent.getWorldMatrix().clone();
                 invertParentWorldMatrix.invert();
-
                 var worldPosition = new Vector3(absolutePositionX, absolutePositionY, absolutePositionZ);
-
                 this.position = Vector3.TransformCoordinates(worldPosition, invertParentWorldMatrix);
             } else {
                 this.position.x = absolutePositionX;
                 this.position.y = absolutePositionY;
                 this.position.z = absolutePositionZ;
             }
+            return this;
         }
+
         // ================================== Point of View Movement =================================
         /**
          * Perform relative position change from the point of view of behind the front of the mesh.
@@ -593,9 +638,12 @@
          * @param {number} amountRight
          * @param {number} amountUp
          * @param {number} amountForward
+         * 
+         * Returns the AbstractMesh.
          */
-        public movePOV(amountRight: number, amountUp: number, amountForward: number): void {
+        public movePOV(amountRight: number, amountUp: number, amountForward: number): AbstractMesh {
             this.position.addInPlace(this.calcMovePOV(amountRight, amountUp, amountForward));
+            return this;
         }
 
         /**
@@ -604,7 +652,9 @@
          * Supports definition of mesh facing forward or backward.
          * @param {number} amountRight
          * @param {number} amountUp
-         * @param {number} amountForward
+         * @param {number} amountForward  
+         * 
+         * Returns a new Vector3.  
          */
         public calcMovePOV(amountRight: number, amountUp: number, amountForward: number): Vector3 {
             var rotMatrix = new Matrix();
@@ -623,9 +673,12 @@
          * @param {number} flipBack
          * @param {number} twirlClockwise
          * @param {number} tiltRight
+         * 
+         * Returns the AbstractMesh.  
          */
-        public rotatePOV(flipBack: number, twirlClockwise: number, tiltRight: number): void {
+        public rotatePOV(flipBack: number, twirlClockwise: number, tiltRight: number): AbstractMesh {
             this.rotation.addInPlace(this.calcRotatePOV(flipBack, twirlClockwise, tiltRight));
+            return this;
         }
 
         /**
@@ -634,6 +687,8 @@
          * @param {number} flipBack
          * @param {number} twirlClockwise
          * @param {number} tiltRight
+         * 
+         * Returns a new Vector3.
          */
         public calcRotatePOV(flipBack: number, twirlClockwise: number, tiltRight: number): Vector3 {
             var defForwardMult = this.definedFacingForward ? 1 : -1;
@@ -642,11 +697,12 @@
 
         /**
          * Sets a new pivot matrix to the mesh.  
-         * Returns nothing.
+         * Returns the AbstractMesh.
          */
-        public setPivotMatrix(matrix: Matrix): void {
+        public setPivotMatrix(matrix: Matrix): AbstractMesh {
             this._pivotMatrix = matrix;
             this._cache.pivotMatrixUpdated = true;
+            return this;
         }
 
         /**
@@ -702,34 +758,41 @@
             this._cache.billboardMode = -1;
         }
 
-        public markAsDirty(property: string): void {
+        public markAsDirty(property: string): AbstractMesh {
             if (property === "rotation") {
                 this.rotationQuaternion = null;
             }
             this._currentRenderId = Number.MAX_VALUE;
             this._isDirty = true;
+            return this;
         }
 
-        public _updateBoundingInfo(): void {
+        /**
+         * Updates the mesh BoundingInfo object and all its children BoundingInfo objects also.  
+         * Returns the AbstractMesh.  
+         */
+        public _updateBoundingInfo(): AbstractMesh {
             this._boundingInfo = this._boundingInfo || new BoundingInfo(this.absolutePosition, this.absolutePosition);
-
             this._boundingInfo.update(this.worldMatrixFromCache);
-
             this._updateSubMeshesBoundingInfo(this.worldMatrixFromCache);
+            return this;
         }
 
-        public _updateSubMeshesBoundingInfo(matrix: Matrix): void {
+        /**
+         * Update a mesh's children BoundingInfo objects only.  
+         * Returns the AbstractMesh.  
+         */
+        public _updateSubMeshesBoundingInfo(matrix: Matrix): AbstractMesh {
             if (!this.subMeshes) {
                 return;
             }
-
             for (var subIndex = 0; subIndex < this.subMeshes.length; subIndex++) {
                 var subMesh = this.subMeshes[subIndex];
-
                 if (!subMesh.IsGlobal) {
                     subMesh.updateBoundingInfo(matrix);
                 }
             }
+            return this;
         }
 
         /**
@@ -876,24 +939,33 @@
         }
 
         /**
-        * If you'd like to be called back after the mesh position, rotation or scaling has been updated
+        * If you'd like to be called back after the mesh position, rotation or scaling has been updated.  
         * @param func: callback function to add
+        *
+        * Returns the AbstractMesh. 
         */
-        public registerAfterWorldMatrixUpdate(func: (mesh: AbstractMesh) => void): void {
+        public registerAfterWorldMatrixUpdate(func: (mesh: AbstractMesh) => void): AbstractMesh {
             this.onAfterWorldMatrixUpdateObservable.add(func);
+            return this;
         }
 
         /**
-         * Removes a registered callback function
+         * Removes a registered callback function.  
+         * Returns the AbstractMesh.
          */
-        public unregisterAfterWorldMatrixUpdate(func: (mesh: AbstractMesh) => void): void {
+        public unregisterAfterWorldMatrixUpdate(func: (mesh: AbstractMesh) => void): AbstractMesh {
             this.onAfterWorldMatrixUpdateObservable.removeCallback(func);
+            return this;
         }
 
-        public setPositionWithLocalVector(vector3: Vector3): void {
+        /**
+         * Sets the mesh position in its local space.  
+         * Returns the AbstractMesh.  
+         */
+        public setPositionWithLocalVector(vector3: Vector3): AbstractMesh {
             this.computeWorldMatrix();
-
             this.position = Vector3.TransformNormal(vector3, this._localWorld);
+            return this;
         }
 
         /**
@@ -908,14 +980,18 @@
             return Vector3.TransformNormal(this.position, invLocalWorldMatrix);
         }
 
-        public locallyTranslate(vector3: Vector3): void {
+        /**
+         * Translates the mesh along the passed Vector3 in its local space.  
+         * Returns the AbstractMesh. 
+         */
+        public locallyTranslate(vector3: Vector3): AbstractMesh {
             this.computeWorldMatrix(true);
-
             this.position = Vector3.TransformCoordinates(vector3, this._localWorld);
+            return this;
         }
 
         private static _lookAtVectorCache = new Vector3(0, 0, 0);
-        public lookAt(targetPoint: Vector3, yawCor: number = 0, pitchCor: number = 0, rollCor: number = 0, space: Space = Space.LOCAL): void {
+        public lookAt(targetPoint: Vector3, yawCor: number = 0, pitchCor: number = 0, rollCor: number = 0, space: Space = Space.LOCAL): AbstractMesh {
             /// <summary>Orients a mesh towards a target point. Mesh must be drawn facing user.</summary>
             /// <param name="targetPoint" type="Vector3">The position (must be in same space as current mesh) to look at</param>
             /// <param name="yawCor" type="Number">optional yaw (y-axis) correction in radians</param>
@@ -931,30 +1007,42 @@
             var pitch = Math.atan2(dv.y, len);
             this.rotationQuaternion = this.rotationQuaternion || new Quaternion();
             Quaternion.RotationYawPitchRollToRef(yaw + yawCor, pitch + pitchCor, rollCor, this.rotationQuaternion);
+            return this;
         }
 
-        public attachToBone(bone: Bone, affectedMesh: AbstractMesh): void {
+        public attachToBone(bone: Bone, affectedMesh: AbstractMesh): AbstractMesh {
             this._meshToBoneReferal = affectedMesh;
             this.parent = bone;
 
             if (bone.getWorldMatrix().determinant() < 0) {
                 this.scalingDeterminant *= -1;
             }
+            return this;
         }
 
-        public detachFromBone(): void {
+        public detachFromBone(): AbstractMesh {
             if (this.parent.getWorldMatrix().determinant() < 0) {
                 this.scalingDeterminant *= -1;
             }
-
             this._meshToBoneReferal = null;
             this.parent = null;
+            return this;
         }
 
+        /**
+         * Returns `true` if the mesh is within the frustum defined by the passed array of planes.  
+         * A mesh is in the frustum if its bounding box intersects the frustum.  
+         * Boolean returned.  
+         */
         public isInFrustum(frustumPlanes: Plane[]): boolean {
             return this._boundingInfo.isInFrustum(frustumPlanes);
         }
 
+        /**
+         * Returns `true` if the mesh is completely in the frustum defined be the passed array of planes.  
+         * A mesh is completely in the frustum if its bounding box it completely inside the frustum.  
+         * Boolean returned.  
+         */
         public isCompletelyInFrustum(frustumPlanes: Plane[]): boolean {
             return this._boundingInfo.isCompletelyInFrustum(frustumPlanes);;
         }
@@ -1031,32 +1119,35 @@
             return Vector3.TransformCoordinates(this.absolutePosition, camera.getViewMatrix());
         }
 
+        /**
+         * Returns the distance from the mesh to the active camera.  
+         * Returns a float.  
+         */
         public getDistanceToCamera(camera?: Camera): number {
             if (!camera) {
                 camera = this.getScene().activeCamera;
             }
-
             return this.absolutePosition.subtract(camera.position).length();
         }
 
-        public applyImpulse(force: Vector3, contactPoint: Vector3): void {
+        public applyImpulse(force: Vector3, contactPoint: Vector3): AbstractMesh {
             if (!this.physicsImpostor) {
                 return;
             }
-
             this.physicsImpostor.applyImpulse(force, contactPoint);
+            return this;
         }
 
-        public setPhysicsLinkWith(otherMesh: Mesh, pivot1: Vector3, pivot2: Vector3, options?: any): void {
+        public setPhysicsLinkWith(otherMesh: Mesh, pivot1: Vector3, pivot2: Vector3, options?: any): AbstractMesh {
             if (!this.physicsImpostor || !otherMesh.physicsImpostor) {
                 return;
             }
-
             this.physicsImpostor.createJoint(otherMesh.physicsImpostor, PhysicsJoint.HingeJoint, {
                 mainPivot: pivot1,
                 connectedPivot: pivot2,
                 nativeParams: options
-            })
+            });
+            return this;
         }
 
         /**
@@ -1079,6 +1170,10 @@
 
         // Collisions
 
+        /**
+         * Property checkCollisions : Boolean, whether the camera should check the collisions against the mesh.  
+         * Default `false`.
+         */
         public get checkCollisions(): boolean {
             return this._checkCollisions;
         }
@@ -1090,7 +1185,7 @@
             }
         }
 
-        public moveWithCollisions(velocity: Vector3): void {
+        public moveWithCollisions(velocity: Vector3): AbstractMesh {
             var globalPosition = this.getAbsolutePosition();
 
             globalPosition.subtractFromFloatsToRef(0, this.ellipsoid.y, 0, this._oldPositionForCollisions);
@@ -1098,6 +1193,7 @@
             this._collider.radius = this.ellipsoid;
 
             this.getScene().collisionCoordinator.getNewPosition(this._oldPositionForCollisions, velocity, this._collider, 3, this, this._onCollisionPositionChange, this.uniqueId);
+            return this;
         }
 
         private _onCollisionPositionChange = (collisionId: number, newPosition: Vector3, collidedMesh: AbstractMesh = null) => {
@@ -1121,8 +1217,9 @@
         // Submeshes octree
 
         /**
-        * This function will create an octree to help select the right submeshes for rendering, picking and collisions
-        * Please note that you must have a decent number of submeshes to get performance improvements when using octree
+        * This function will create an octree to help to select the right submeshes for rendering, picking and collision computations.  
+        * Please note that you must have a decent number of submeshes to get performance improvements when using an octree.  
+        * Returns an Octree of submeshes.  
         */
         public createOrUpdateSubmeshesOctree(maxCapacity = 64, maxDepth = 2): Octree<SubMesh> {
             if (!this._submeshesOctree) {
@@ -1139,7 +1236,7 @@
         }
 
         // Collisions
-        public _collideForSubMesh(subMesh: SubMesh, transformMatrix: Matrix, collider: Collider): void {
+        public _collideForSubMesh(subMesh: SubMesh, transformMatrix: Matrix, collider: Collider): AbstractMesh {
             this._generatePointsArray();
             // Transformation
             if (!subMesh._lastColliderWorldVertices || !subMesh._lastColliderTransformMatrix.equals(transformMatrix)) {
@@ -1157,9 +1254,10 @@
             if (collider.collisionFound) {
                 collider.collidedMesh = this;
             }
+            return this;
         }
 
-        public _processCollisionsForSubMeshes(collider: Collider, transformMatrix: Matrix): void {
+        public _processCollisionsForSubMeshes(collider: Collider, transformMatrix: Matrix): AbstractMesh {
             var subMeshes: SubMesh[];
             var len: number;
 
@@ -1184,18 +1282,19 @@
 
                 this._collideForSubMesh(subMesh, transformMatrix, collider);
             }
+            return this;
         }
 
-        public _checkCollision(collider: Collider): void {
+        public _checkCollision(collider: Collider): AbstractMesh {
             // Bounding box test
             if (!this._boundingInfo._checkCollision(collider))
-                return;
+                return this;
 
             // Transformation matrix
             Matrix.ScalingToRef(1.0 / collider.radius.x, 1.0 / collider.radius.y, 1.0 / collider.radius.z, this._collisionsScalingMatrix);
             this.worldMatrixFromCache.multiplyToRef(this._collisionsScalingMatrix, this._collisionsTransformMatrix);
-
             this._processCollisionsForSubMeshes(collider, this._collisionsTransformMatrix);
+            return this;
         }
 
         // Picking
@@ -1203,6 +1302,10 @@
             return false;
         }
 
+        /**
+         * Checks if the passed Ray intersects with the mesh.  
+         * Returns an object PickingInfo.
+         */
         public intersects(ray: Ray, fastCheck?: boolean): PickingInfo {
             var pickingInfo = new PickingInfo();
 
@@ -1277,11 +1380,19 @@
             return pickingInfo;
         }
 
+        /**
+         * Clones the mesh, used by the class Mesh.  
+         * Just returns `null` for an AbstractMesh.  
+         */
         public clone(name: string, newParent: Node, doNotCloneChildren?: boolean): AbstractMesh {
             return null;
         }
 
-        public releaseSubMeshes(): void {
+        /**
+         * Disposes all the mesh submeshes.  
+         * Returns the AbstractMesh.  
+         */
+        public releaseSubMeshes(): AbstractMesh {
             if (this.subMeshes) {
                 while (this.subMeshes.length) {
                     this.subMeshes[0].dispose();
@@ -1289,6 +1400,7 @@
             } else {
                 this.subMeshes = new Array<SubMesh>();
             }
+            return this;
         }
 
         /**
@@ -1408,6 +1520,10 @@
             super.dispose();
         }
 
+        /**
+         * Returns a new Vector3 what is the localAxis, expressed in the mesh local space, rotated like the mesh.  
+         * This Vector3 is expressed in the World space.  
+         */
         public getDirection(localAxis:Vector3): Vector3 {
             var result = Vector3.Zero();
 
@@ -1416,11 +1532,18 @@
             return result;
         }
 
-        public getDirectionToRef(localAxis:Vector3, result:Vector3): void {
+        /**
+         * Sets the Vector3 "result" as the rotated Vector3 "localAxis" in the same rotation than the mesh.
+         * localAxis is expressed in the mesh local space.
+         * result is computed in the Wordl space from the mesh World matrix.  
+         * Returns the AbstractMesh.  
+         */
+        public getDirectionToRef(localAxis:Vector3, result:Vector3): AbstractMesh {
             Vector3.TransformNormalToRef(localAxis, this.getWorldMatrix(), result);
+            return this;
         }
 
-        public setPivotPoint(point:Vector3, space:Space = Space.LOCAL): void{
+        public setPivotPoint(point:Vector3, space:Space = Space.LOCAL): AbstractMesh {
 
             if(this.getScene().getRenderId() == 0){
                 this.computeWorldMatrix(true);
@@ -1435,44 +1558,48 @@
             }
 
             Vector3.TransformCoordinatesToRef(point, wm, this.position);
-
             this._pivotMatrix.m[12] = -point.x;
             this._pivotMatrix.m[13] = -point.y;
             this._pivotMatrix.m[14] = -point.z;
-
             this._cache.pivotMatrixUpdated = true;
-
+            return this;
         }
 
+        /**
+         * Returns a new Vector3 set with the mesh pivot point coordinates in the local space.  
+         */
         public getPivotPoint(): Vector3 {
-
             var point = Vector3.Zero();
-
             this.getPivotPointToRef(point);
-
             return point;
-
         }
 
-        public getPivotPointToRef(result:Vector3): void{
-
+        /**
+         * Sets the passed Vector3 "result" with the coordinates of the mesh pivot point in the local space.   
+         * Returns the AbstractMesh.   
+         */
+        public getPivotPointToRef(result:Vector3): AbstractMesh{
             result.x = -this._pivotMatrix.m[12];
             result.y = -this._pivotMatrix.m[13];
             result.z = -this._pivotMatrix.m[14];
-
+            return this;
         }
 
+        /**
+         * Returns a new Vector3 set with the mesh pivot point World coordinates.  
+         */
         public getAbsolutePivotPoint(): Vector3 {
-
             var point = Vector3.Zero();
-
             this.getAbsolutePivotPointToRef(point);
-
             return point;
-
         }
 
-        public setParent(mesh:AbstractMesh, keepWorldPositionRotation = false): void{
+        /**
+         * Defines the passed mesh as the parent of the current mesh.  
+         * If keepWorldPositionRotation is set to `true` (default `false`), the current mesh position and rotation are kept.
+         * Returns the AbstractMesh.  
+         */
+        public setParent(mesh:AbstractMesh, keepWorldPositionRotation = false): AbstractMesh {
 
             var child = this;
             var parent = mesh;
@@ -1541,38 +1668,46 @@
                 }
 
             }
-
             child.parent = parent;
-
+            return this;
         }
 
-        public addChild(mesh:AbstractMesh, keepWorldPositionRotation = false): void{
-
+        /**
+         * Adds the passed mesh as a child to the current mesh.  
+         * If keepWorldPositionRotation is set to `true` (default `false`), the child world position and rotation are kept.  
+         * Returns the AbstractMesh.  
+         */
+        public addChild(mesh:AbstractMesh, keepWorldPositionRotation = false): AbstractMesh {
             mesh.setParent(this, keepWorldPositionRotation);
-
+            return this;
         }
 
-        public removeChild(mesh:AbstractMesh, keepWorldPositionRotation = false): void{
-
+        /**
+         * Removes the passed mesh from the current mesh children list.  
+         * Returns the AbstractMesh.  
+         */
+        public removeChild(mesh:AbstractMesh, keepWorldPositionRotation = false): AbstractMesh {
             mesh.setParent(null, keepWorldPositionRotation);
-
+            return this;
         }
 
-        public getAbsolutePivotPointToRef(result:Vector3): void{
-
+        /**
+         * Sets the Vector3 "result" coordinates with the mesh pivot point World coordinates.  
+         * Returns the AbstractMesh.  
+         */
+        public getAbsolutePivotPointToRef(result:Vector3): AbstractMesh {
             result.x = this._pivotMatrix.m[12];
             result.y = this._pivotMatrix.m[13];
             result.z = this._pivotMatrix.m[14];
-
             this.getPivotPointToRef(result);
-
             Vector3.TransformCoordinatesToRef(result, this.getWorldMatrix(), result);
-
+            return this;
         }
 
        // Facet data
         /** 
-         *  Initialize the facet data arrays : facetNormals, facetPositions and facetPartitioning
+         *  Initialize the facet data arrays : facetNormals, facetPositions and facetPartitioning.   
+         * Returns the AbstractMesh.  
          */
         private _initFacetData(): AbstractMesh {
             if (!this._facetNormals) {
@@ -1598,7 +1733,8 @@
         /**
          * Updates the mesh facetData arrays and the internal partitioning when the mesh is morphed or updated.  
          * This method can be called within the render loop.  
-         * You don't need to call this method by yourself in the render loop when you update/morph a mesh with the methods CreateXXX() as they automatically manage this computation.  
+         * You don't need to call this method by yourself in the render loop when you update/morph a mesh with the methods CreateXXX() as they automatically manage this computation.   
+         * Returns the AbstractMesh.  
          */
         public updateFacetData(): AbstractMesh {
             if (!this._facetDataEnabled) {
@@ -1652,7 +1788,7 @@
             return this._facetPositions;           
         }
         /**
-         * Returns the facetLocalPartioning array
+         * Returns the facetLocalPartioning array.
          */
         public getFacetLocalPartitioning(): number[][] {
             if (!this._facetPartitioning) {
@@ -1671,7 +1807,7 @@
         }
         /**
          * Sets the reference Vector3 with the i-th facet position in the world system.  
-         * Returns the mesh.  
+         * Returns the AbstractMesh.  
          */
         public getFacetPositionToRef(i: number, ref: Vector3): AbstractMesh {
             var localPos = (this.getFacetLocalPositions())[i];
@@ -1690,7 +1826,7 @@
         }
         /**
          * Sets the reference Vector3 with the i-th facet normal in the world system.  
-         * Returns the mesh.  
+         * Returns the AbstractMesh.  
          */
         public getFacetNormalToRef(i: number, ref: Vector3) {
             var localNorm = (this.getFacetLocalNormals())[i];
@@ -1801,7 +1937,7 @@
         }
         /** 
          * Disables the feature FacetData and frees the related memory.  
-         * Returns the mesh.  
+         * Returns the AbstractMesh.  
          */
         public disableFacetData(): AbstractMesh {
             if (this._facetDataEnabled) {

src/Mesh/babylon.groundMesh.ts

@@ -108,13 +108,15 @@
         /**
         * Force the heights to be recomputed for getHeightAtCoordinates() or getNormalAtCoordinates()
         * if the ground has been updated.
-        * This can be used in the render loop
+        * This can be used in the render loop.  
+        * Returns the GroundMesh.  
         */
-        public updateCoordinateHeights(): void {
+        public updateCoordinateHeights(): GroundMesh {
             if (!this._heightQuads || this._heightQuads.length == 0) {
                 this._initHeightQuads();
             }
             this._computeHeightQuads();
+            return this;
         }
 
         // Returns the element "facet" from the heightQuads array relative to (x, z) local coordinates
@@ -138,8 +140,9 @@
         // a quad is two triangular facets separated by a slope, so a "facet" element is 1 slope + 2 facets
         // slope : Vector2(c, h) = 2D diagonal line equation setting appart two triangular facets in a quad : z = cx + h
         // facet1 : Vector4(a, b, c, d) = first facet 3D plane equation : ax + by + cz + d = 0
-        // facet2 :  Vector4(a, b, c, d) = second facet 3D plane equation : ax + by + cz + d = 0
-        private _initHeightQuads(): void {
+        // facet2 :  Vector4(a, b, c, d) = second facet 3D plane equation : ax + by + cz + d = 0  
+        // Returns the GroundMesh.  
+        private _initHeightQuads(): GroundMesh {
             var subdivisionsX = this._subdivisionsX;
             var subdivisionsY = this._subdivisionsY;
             this._heightQuads = new Array();
@@ -149,13 +152,15 @@
                     this._heightQuads[row * subdivisionsX + col] = quad;
                 }
             }
+            return this;
         }
 
         // Compute each quad element values and update the the heightMap array :
         // slope : Vector2(c, h) = 2D diagonal line equation setting appart two triangular facets in a quad : z = cx + h
         // facet1 : Vector4(a, b, c, d) = first facet 3D plane equation : ax + by + cz + d = 0
-        // facet2 :  Vector4(a, b, c, d) = second facet 3D plane equation : ax + by + cz + d = 0
-        private _computeHeightQuads(): void {
+        // facet2 :  Vector4(a, b, c, d) = second facet 3D plane equation : ax + by + cz + d = 0  
+        // Returns the GroundMesh.  
+        private _computeHeightQuads(): GroundMesh {
             var positions = this.getVerticesData(VertexBuffer.PositionKind);
             var v1 = Tmp.Vector3[3];
             var v2 = Tmp.Vector3[2];
@@ -220,6 +225,7 @@
                     quad.facet2.copyFromFloats(norm2.x, norm2.y, norm2.z, d2);
                 }
             }
+            return this;
         }
     }
-}
+}

src/Mesh/babylon.instancedMesh.ts

@@ -30,6 +30,9 @@
             this._syncSubMeshes();
         }
 
+        /**
+         * Returns the string "InstancedMesh".  
+         */
         public getClassName(): string {
             return "InstancedMesh";
         }          
@@ -55,6 +58,9 @@
             return this._sourceMesh.renderingGroupId;
         }
 
+        /**
+         * Returns the total number of vertices (integer).  
+         */
         public getTotalVertices(): number {
             return this._sourceMesh.getTotalVertices();
         }
@@ -63,14 +69,23 @@
             return this._sourceMesh;
         }
 
+        /**
+         * Returns a float array or a Float32Array of the requested kind of data : positons, normals, uvs, etc.  
+         */
         public getVerticesData(kind: string, copyWhenShared?: boolean): number[] | Float32Array {
             return this._sourceMesh.getVerticesData(kind, copyWhenShared);
         }
 
+        /**
+         * Boolean : True if the mesh owns the requested kind of data.
+         */
         public isVerticesDataPresent(kind: string): boolean {
             return this._sourceMesh.isVerticesDataPresent(kind);
         }
 
+        /**
+         * Returns an array of indices (IndicesArray).  
+         */
         public getIndices(): IndicesArray {
             return this._sourceMesh.getIndices();
         }
@@ -79,26 +94,36 @@
             return this._sourceMesh._positions;
         }
 
-        public refreshBoundingInfo(): void {
+        /**
+         * Sets a new updated BoundingInfo to the mesh.  
+         * Returns the mesh.  
+         */
+        public refreshBoundingInfo(): InstancedMesh {
             var meshBB = this._sourceMesh.getBoundingInfo();
 
             this._boundingInfo = new BoundingInfo(meshBB.minimum.clone(), meshBB.maximum.clone());
 
             this._updateBoundingInfo();
+            return this;
         }
 
-        public _preActivate(): void {
+        public _preActivate(): InstancedMesh {
             if (this._currentLOD) {
                 this._currentLOD._preActivate();
             }
+            return this;
         }
 
-        public _activate(renderId: number): void {
+        public _activate(renderId: number): InstancedMesh {
             if (this._currentLOD) {
                 this._currentLOD._registerInstanceForRenderId(this, renderId);
             }
+            return this;
         }
 
+        /**
+         * Returns the current associated LOD AbstractMesh.  
+         */
         public getLOD(camera: Camera): AbstractMesh {
             this._currentLOD = <Mesh>this.sourceMesh.getLOD(this.getScene().activeCamera, this.getBoundingInfo().boundingSphere);
 
@@ -109,20 +134,28 @@
             return this._currentLOD;
         }
 
-        public _syncSubMeshes(): void {
+        public _syncSubMeshes(): InstancedMesh {
             this.releaseSubMeshes();
             if (this._sourceMesh.subMeshes) {
                 for (var index = 0; index < this._sourceMesh.subMeshes.length; index++) {
                     this._sourceMesh.subMeshes[index].clone(this, this._sourceMesh);
                 }
             }
+            return this;
         }
 
         public _generatePointsArray(): boolean {
             return this._sourceMesh._generatePointsArray();
         }
 
-        // Clone
+        /**
+         * Creates a new InstancedMesh from the current mesh.  
+         * - name (string) : the cloned mesh name
+         * - newParent (optional Node) : the optional Node to parent the clone to.  
+         * - doNotCloneChildren (optional boolean, default `false`) : if `true` the model children aren't cloned.  
+         * 
+         * Returns the clone.  
+         */
         public clone(name: string, newParent: Node, doNotCloneChildren?: boolean): InstancedMesh {
             var result = this._sourceMesh.createInstance(name);
 
@@ -153,7 +186,10 @@
             return result;
         }
 
-        // Dispose
+        /**
+         * Disposes the InstancedMesh.  
+         * Returns nothing.  
+         */
         public dispose(doNotRecurse?: boolean): void {
 
             // Remove from mesh
@@ -163,4 +199,4 @@
             super.dispose(doNotRecurse);
         }
     }
-} 
+} 

src/Mesh/babylon.linesMesh.ts

@@ -53,6 +53,9 @@
             this._positionBuffer[VertexBuffer.PositionKind] = null;
         }
 
+        /**
+         * Returns the string "LineMesh"  
+         */
         public getClassName(): string {
             return "LinesMesh";
         }      
@@ -70,7 +73,7 @@
             return null;
         }
 
-        public _bind(subMesh: SubMesh, effect: Effect, fillMode: number): void {
+        public _bind(subMesh: SubMesh, effect: Effect, fillMode: number): LinesMesh {
             var engine = this.getScene().getEngine();
 
             this._positionBuffer[VertexBuffer.PositionKind] = this._geometry.getVertexBuffer(VertexBuffer.PositionKind);
@@ -80,17 +83,19 @@
 
             // Color
             this._colorShader.setColor4("color", this.color.toColor4(this.alpha));
+            return this;
         }
 
-        public _draw(subMesh: SubMesh, fillMode: number, instancesCount?: number): void {
+        public _draw(subMesh: SubMesh, fillMode: number, instancesCount?: number): LinesMesh {
             if (!this._geometry || !this._geometry.getVertexBuffers() || !this._geometry.getIndexBuffer()) {
-                return;
+                return this;
             }
 
             var engine = this.getScene().getEngine();
 
             // Draw order
             engine.draw(false, subMesh.indexStart, subMesh.indexCount);
+            return this;
         }
 
         public dispose(doNotRecurse?: boolean): void {
@@ -99,8 +104,11 @@
             super.dispose(doNotRecurse);
         }
 
+        /**
+         * Returns a new LineMesh object cloned from the current one.  
+         */
         public clone(name: string, newParent?: Node, doNotCloneChildren?: boolean): LinesMesh {
             return new LinesMesh(name, this.getScene(), newParent, this, doNotCloneChildren);
         }
     }
-} 
+} 

src/Mesh/babylon.mesh.ts

@@ -204,11 +204,15 @@
         }
 
         // Methods
+        /**
+         * Returns the string "Mesh".  
+         */
         public getClassName(): string {
             return "Mesh";
         }   
 
         /**
+         * Returns a string.  
          * @param {boolean} fullDetails - support for multiple levels of logging within scene loading
          */
         public toString(fullDetails?: boolean): string {
@@ -228,6 +232,10 @@
             return ret;
         }
 
+        /**
+         * True if the mesh has some Levels Of Details (LOD).  
+         * Returns a boolean. 
+         */
         public get hasLODLevels(): boolean {
             return this._LODLevels.length > 0;
         }
@@ -273,6 +281,7 @@
          * Returns the LOD level mesh at the passed distance or null if not found.  
          * It is related to the method `addLODLevel(distance, mesh)`. 
          * tuto : http://doc.babylonjs.com/tutorials/How_to_use_LOD   
+         * Returns an object Mesh or `null`.  
          */
         public getLODLevelAtDistance(distance: number): Mesh {
             for (var index = 0; index < this._LODLevels.length; index++) {
@@ -534,19 +543,23 @@
         /**  
          * This function affects parametric shapes on vertex position update only : ribbons, tubes, etc. 
          * It has no effect at all on other shapes.
-         * It prevents the mesh normals from being recomputed on next `positions` array update.
+         * It prevents the mesh normals from being recomputed on next `positions` array update.  
+         * Returns the Mesh.  
          */
-        public freezeNormals(): void {
+        public freezeNormals(): Mesh {
             this._areNormalsFrozen = true;
+            return this;
         }
 
         /**  
          * This function affects parametric shapes on vertex position update only : ribbons, tubes, etc. 
          * It has no effect at all on other shapes.
-         * It reactivates the mesh normals computation if it was previously frozen.
+         * It reactivates the mesh normals computation if it was previously frozen.  
+         * Returns the Mesh.  
          */
-        public unfreezeNormals(): void {
+        public unfreezeNormals(): Mesh {
             this._areNormalsFrozen = false;
+            return this;
         }
 
         /**
@@ -557,23 +570,25 @@
         }
 
         // Methods
-        public _preActivate(): void {
+        public _preActivate(): Mesh {
             var sceneRenderId = this.getScene().getRenderId();
             if (this._preActivateId === sceneRenderId) {
-                return;
+                return this;
             }
 
             this._preActivateId = sceneRenderId;
             this._visibleInstances = null;
+            return this;
         }
 
-        public _preActivateForIntermediateRendering(renderId: number): void {
+        public _preActivateForIntermediateRendering(renderId: number): Mesh {
             if (this._visibleInstances) {
                 this._visibleInstances.intermediateDefaultRenderId = renderId;
             }
+            return this;
         }
 
-        public _registerInstanceForRenderId(instance: InstancedMesh, renderId: number) {
+        public _registerInstanceForRenderId(instance: InstancedMesh, renderId: number): Mesh {
             if (!this._visibleInstances) {
                 this._visibleInstances = {};
                 this._visibleInstances.defaultRenderId = renderId;
@@ -585,13 +600,15 @@
             }
 
             this._visibleInstances[renderId].push(instance);
+            return this;
         }
 
         /**
          * This method recomputes and sets a new BoundingInfo to the mesh unless it is locked.
-         * This means the mesh underlying bounding box and sphere are recomputed. 
+         * This means the mesh underlying bounding box and sphere are recomputed.   
+         * Returns the Mesh.  
          */
-        public refreshBoundingInfo(): void {
+        public refreshBoundingInfo(): Mesh {
             if (this._boundingInfo.isLocked) {
                 return;
             }
@@ -609,6 +626,7 @@
             }
 
             this._updateBoundingInfo();
+            return this;
         }
 
         public _createGlobalSubMesh(): SubMesh {
@@ -670,9 +688,11 @@
          * - BABYLON.VertexBuffer.MatricesIndicesKind
          * - BABYLON.VertexBuffer.MatricesIndicesExtraKind
          * - BABYLON.VertexBuffer.MatricesWeightsKind
-         * - BABYLON.VertexBuffer.MatricesWeightsExtraKind
+         * - BABYLON.VertexBuffer.MatricesWeightsExtraKind  
+         * 
+         * Returns the Mesh.  
          */
-        public setVerticesData(kind: string, data: number[] | Float32Array, updatable?: boolean, stride?: number): void {
+        public setVerticesData(kind: string, data: number[] | Float32Array, updatable?: boolean, stride?: number): Mesh {
             if (!this._geometry) {
                 var vertexData = new VertexData();
                 vertexData.set(data, kind);
@@ -684,9 +704,14 @@
             else {
                 this._geometry.setVerticesData(kind, data, updatable, stride);
             }
+            return this;
         }
 
-        public setVerticesBuffer(buffer: VertexBuffer): void {
+        /**
+         * Sets the mesh VertexBuffer.  
+         * Returns the Mesh.  
+         */
+        public setVerticesBuffer(buffer: VertexBuffer): Mesh {
             if (!this._geometry) {
                 var scene = this.getScene();
 
@@ -694,6 +719,7 @@
             }
 
             this._geometry.setVerticesBuffer(buffer);
+            return this;
         }
 
         /**
@@ -717,8 +743,10 @@
          * - BABYLON.VertexBuffer.MatricesIndicesExtraKind
          * - BABYLON.VertexBuffer.MatricesWeightsKind
          * - BABYLON.VertexBuffer.MatricesWeightsExtraKind
+         * 
+         * Returns the Mesh.  
          */
-        public updateVerticesData(kind: string, data: number[] | Float32Array, updateExtends?: boolean, makeItUnique?: boolean): void {
+        public updateVerticesData(kind: string, data: number[] | Float32Array, updateExtends?: boolean, makeItUnique?: boolean): Mesh {
             if (!this._geometry) {
                 return;
             }
@@ -729,6 +757,7 @@
                 this.makeGeometryUnique();
                 this.updateVerticesData(kind, data, updateExtends, false);
             }
+            return this;
         }
 
         /**
@@ -754,8 +783,9 @@
          * tuto : http://doc.babylonjs.com/tutorials/How_to_dynamically_morph_a_mesh#other-shapes-updatemeshpositions  
          * The parameter `positionFunction` is a simple JS function what is passed the mesh `positions` array. It doesn't need to return anything.
          * The parameter `computeNormals` is a boolean (default true) to enable/disable the mesh normal recomputation after the vertex position update.     
+         * Returns the Mesh.  
          */
-        public updateMeshPositions(positionFunction, computeNormals: boolean = true): void {
+        public updateMeshPositions(positionFunction, computeNormals: boolean = true): Mesh {
             var positions = this.getVerticesData(VertexBuffer.PositionKind);
             positionFunction(positions);
             this.updateVerticesData(VertexBuffer.PositionKind, positions, false, false);
@@ -765,28 +795,33 @@
                 VertexData.ComputeNormals(positions, indices, normals);
                 this.updateVerticesData(VertexBuffer.NormalKind, normals, false, false);
             }
+            return this;
         }
 
 
-        public makeGeometryUnique() {
+        /**
+         * Creates a un-shared specific occurence of the geometry for the mesh.  
+         * Returns the Mesh.  
+         */
+        public makeGeometryUnique(): Mesh {
             if (!this._geometry) {
                 return;
             }
             var oldGeometry = this._geometry;
-
             var geometry = this._geometry.copy(Geometry.RandomId());
-
             oldGeometry.releaseForMesh(this, true);
             geometry.applyToMesh(this);
+            return this;
         }
 
         /**
          * Sets the mesh indices.  
          * Expects an array populated with integers or a typed array (Int32Array, Uint32Array, Uint16Array).
          * If the mesh has no geometry, a new Geometry object is created and set to the mesh. 
-         * This method creates a new index buffer each call.
+         * This method creates a new index buffer each call.  
+         * Returns the Mesh.  
          */
-        public setIndices(indices: IndicesArray, totalVertices?: number): void {
+        public setIndices(indices: IndicesArray, totalVertices?: number): Mesh {
             if (!this._geometry) {
                 var vertexData = new VertexData();
                 vertexData.indices = indices;
@@ -798,20 +833,22 @@
             else {
                 this._geometry.setIndices(indices, totalVertices);
             }
+            return this;
         }
 
         /**
-         * Invert the geometry to move from a right handed system to a left handed one.
+         * Invert the geometry to move from a right handed system to a left handed one.  
+         * Returns the Mesh.  
          */
-        public toLeftHanded(): void {
+        public toLeftHanded(): Mesh {
             if (!this._geometry) {
                 return;
             }
-
             this._geometry.toLeftHanded();
+            return this;
         }
 
-        public _bind(subMesh: SubMesh, effect: Effect, fillMode: number): void {
+        public _bind(subMesh: SubMesh, effect: Effect, fillMode: number): Mesh {
             var engine = this.getScene().getEngine();
 
             // Wireframe
@@ -836,11 +873,12 @@
 
             // VBOs
             this._geometry._bind(effect, indexToBind);
+            return this;
         }
 
-        public _draw(subMesh: SubMesh, fillMode: number, instancesCount?: number): void {
+        public _draw(subMesh: SubMesh, fillMode: number, instancesCount?: number): Mesh {
             if (!this._geometry || !this._geometry.getVertexBuffers() || !this._geometry.getIndexBuffer()) {
-                return;
+                return this;
             }
 
             this.onBeforeDrawObservable.notifyObservers(this);
@@ -867,38 +905,47 @@
                         engine.draw(true, subMesh.indexStart, subMesh.indexCount, instancesCount);
                     }
             }
+            return this;
         }
 
         /**
          * Registers for this mesh a javascript function called just before the rendering process.
-         * This function is passed the current mesh and doesn't return anything.  
+         * This function is passed the current mesh.  
+         * Return the Mesh.  
          */
-        public registerBeforeRender(func: (mesh: AbstractMesh) => void): void {
+        public registerBeforeRender(func: (mesh: AbstractMesh) => void): Mesh {
             this.onBeforeRenderObservable.add(func);
+            return this;
         }
 
         /**
          * Disposes a previously registered javascript function called before the rendering.
-         * This function is passed the current mesh and doesn't return anything.  
+         * This function is passed the current mesh.  
+         * Returns the Mesh.  
          */
-        public unregisterBeforeRender(func: (mesh: AbstractMesh) => void): void {
+        public unregisterBeforeRender(func: (mesh: AbstractMesh) => void): Mesh {
             this.onBeforeRenderObservable.removeCallback(func);
+            return this;
         }
 
         /**
          * Registers for this mesh a javascript function called just after the rendering is complete.
-         * This function is passed the current mesh and doesn't return anything.  
+         * This function is passed the current mesh.  
+         * Returns the Mesh.  
          */
-        public registerAfterRender(func: (mesh: AbstractMesh) => void): void {
+        public registerAfterRender(func: (mesh: AbstractMesh) => void): Mesh {
             this.onAfterRenderObservable.add(func);
+            return this;
         }
 
         /**
          * Disposes a previously registered javascript function called after the rendering.
-         * This function is passed the current mesh and doesn't return anything.  
+         * This function is passed the current mesh.  
+         * Return the Mesh.  
          */
-        public unregisterAfterRender(func: (mesh: AbstractMesh) => void): void {
+        public unregisterAfterRender(func: (mesh: AbstractMesh) => void): Mesh {
             this.onAfterRenderObservable.removeCallback(func);
+            return this;
         }
 
         public _getInstancesRenderList(subMeshId: number): _InstancesBatch {
@@ -936,7 +983,7 @@
             return this._batchCache;
         }
 
-        public _renderWithInstances(subMesh: SubMesh, fillMode: number, batch: _InstancesBatch, effect: Effect, engine: Engine): void {
+        public _renderWithInstances(subMesh: SubMesh, fillMode: number, batch: _InstancesBatch, effect: Effect, engine: Engine): Mesh {
             var visibleInstances = batch.visibleInstances[subMesh._id];
             var matricesCount = visibleInstances.length + 1;
             var bufferSize = matricesCount * 16 * 4;
@@ -992,10 +1039,11 @@
             this._draw(subMesh, fillMode, instancesCount);
 
             engine.unbindInstanceAttributes();
+            return this;
         }
 
         public _processRendering(subMesh: SubMesh, effect: Effect, fillMode: number, batch: _InstancesBatch, hardwareInstancedRendering: boolean,
-            onBeforeDraw: (isInstance: boolean, world: Matrix, effectiveMaterial?: Material) => void, effectiveMaterial?: Material) {
+            onBeforeDraw: (isInstance: boolean, world: Matrix, effectiveMaterial?: Material) => void, effectiveMaterial?: Material): Mesh {
             var scene = this.getScene();
             var engine = scene.getEngine();
 
@@ -1026,25 +1074,27 @@
                     }
                 }
             }
+            return this;
         }
 
         /**
          * Triggers the draw call for the mesh.
-         * Usually, you don't need to call this method by your own because the mesh rendering is handled by the scene rendering manager.  
+         * Usually, you don't need to call this method by your own because the mesh rendering is handled by the scene rendering manager.   
+         * Returns the Mesh.   
          */
-        public render(subMesh: SubMesh, enableAlphaMode: boolean): void {
+        public render(subMesh: SubMesh, enableAlphaMode: boolean): Mesh {
             var scene = this.getScene();
 
             // Managing instances
             var batch = this._getInstancesRenderList(subMesh._id);
 
             if (batch.mustReturn) {
-                return;
+                return this;
             }
 
             // Checking geometry state
             if (!this._geometry || !this._geometry.getVertexBuffers() || !this._geometry.getIndexBuffer()) {
-                return;
+                return this;
             }
 
             var callbackIndex: number;
@@ -1057,7 +1107,7 @@
             var effectiveMaterial = subMesh.getMaterial();
 
             if (!effectiveMaterial || !effectiveMaterial.isReady(this, hardwareInstancedRendering)) {
-                return;
+                return this;
             }
 
             // Outline - step 1
@@ -1107,12 +1157,14 @@
             }
 
             this.onAfterRenderObservable.notifyObservers(this);
+            return this;
         }
 
-        private _onBeforeDraw(isInstance: boolean, world: Matrix, effectiveMaterial: Material): void {
+        private _onBeforeDraw(isInstance: boolean, world: Matrix, effectiveMaterial: Material): Mesh {
             if (isInstance) {
                 effectiveMaterial.bindOnlyWorldMatrix(world);
             }
+            return this;
         }
 
         /**
@@ -1126,7 +1178,6 @@
                     results.push(particleSystem);
                 }
             }
-
             return results;
         }
 
@@ -1148,9 +1199,8 @@
             return results;
         }
 
-        public _checkDelayState(): void {
+        public _checkDelayState(): Mesh {
             var scene = this.getScene();
-
             if (this._geometry) {
                 this._geometry.load(scene);
             }
@@ -1159,9 +1209,10 @@
 
                 this._queueLoad(this, scene);
             }
+            return this;
         }
 
-        private _queueLoad(mesh: Mesh, scene: Scene): void {
+        private _queueLoad(mesh: Mesh, scene: Scene): Mesh {
             scene._addPendingData(mesh);
 
             var getBinaryData = (this.delayLoadingFile.indexOf(".babylonbinarymeshdata") !== -1);
@@ -1178,6 +1229,7 @@
                 this.delayLoadState = Engine.DELAYLOADSTATE_LOADED;
                 scene._removePendingData(this);
             }, () => { }, scene.database, getBinaryData);
+            return this;
         }
 
         /**
@@ -1200,15 +1252,15 @@
         /**
          * Sets the mesh material by the material or multiMaterial `id` property.  
          * The material `id` is a string identifying the material or the multiMaterial.  
-         * This method returns nothing. 
+         * This method returns the Mesh. 
          */
-        public setMaterialByID(id: string): void {
+        public setMaterialByID(id: string): Mesh {
             var materials = this.getScene().materials;
             var index: number;
             for (index = 0; index < materials.length; index++) {
                 if (materials[index].id === id) {
                     this.material = materials[index];
-                    return;
+                    return this;
                 }
             }
 
@@ -1217,9 +1269,10 @@
             for (index = 0; index < multiMaterials.length; index++) {
                 if (multiMaterials[index].id === id) {
                     this.material = multiMaterials[index];
-                    return;
+                    return this;
                 }
             }
+            return this;
         }
 
         /**
@@ -1245,11 +1298,12 @@
          * The mesh normals are modified accordingly the same transformation.  
          * tuto : http://doc.babylonjs.com/tutorials/How_Rotations_and_Translations_Work#baking-transform  
          * Note that, under the hood, this method sets a new VertexBuffer each call.  
+         * Returns the Mesh.  
          */
-        public bakeTransformIntoVertices(transform: Matrix): void {
+        public bakeTransformIntoVertices(transform: Matrix): Mesh {
             // Position
             if (!this.isVerticesDataPresent(VertexBuffer.PositionKind)) {
-                return;
+                return this;
             }
 
             var submeshes = this.subMeshes.splice(0);
@@ -1267,7 +1321,7 @@
 
             // Normals
             if (!this.isVerticesDataPresent(VertexBuffer.NormalKind)) {
-                return;
+                return this;
             }
             data = this.getVerticesData(VertexBuffer.NormalKind);
             temp = [];
@@ -1282,6 +1336,7 @@
             // Restore submeshes
             this.releaseSubMeshes();
             this.subMeshes = submeshes;
+            return this;
         }
 
         /**
@@ -1289,9 +1344,10 @@
          * The mesh World Matrix is then reset.
          * This method returns nothing but really modifies the mesh even if it's originally not set as updatable.
          * tuto : tuto : http://doc.babylonjs.com/tutorials/How_Rotations_and_Translations_Work#baking-transform 
-         * Note that, under the hood, this method sets a new VertexBuffer each call.
+         * Note that, under the hood, this method sets a new VertexBuffer each call.   
+         * Returns the Mesh.  
          */
-        public bakeCurrentTransformIntoVertices(): void {
+        public bakeCurrentTransformIntoVertices(): Mesh {
             this.bakeTransformIntoVertices(this.computeWorldMatrix(true));
             this.scaling.copyFromFloats(1, 1, 1);
             this.position.copyFromFloats(0, 0, 0);
@@ -1301,11 +1357,13 @@
                 this.rotationQuaternion = Quaternion.Identity();
             }
             this._worldMatrix = Matrix.Identity();
+            return this;
         }
 
         // Cache
-        public _resetPointsArrayCache(): void {
+        public _resetPointsArrayCache(): Mesh {
             this._positions = null;
+            return this;
         }
 
         public _generatePointsArray(): boolean {
@@ -1388,9 +1446,11 @@
          * The parameters `minHeight` and `maxHeight` are the lower and upper limits of the displacement.
          * The parameter `onSuccess` is an optional Javascript function to be called just after the mesh is modified. It is passed the modified mesh and must return nothing.
          * The parameter `uvOffset` is an optional vector2 used to offset UV.
-         * The parameter `uvScale` is an optional vector2 used to scale UV.
+         * The parameter `uvScale` is an optional vector2 used to scale UV.  
+         * 
+         * Returns the Mesh.  
          */
-        public applyDisplacementMap(url: string, minHeight: number, maxHeight: number, onSuccess?: (mesh: Mesh) => void, uvOffset?: Vector2, uvScale?: Vector2): void {
+        public applyDisplacementMap(url: string, minHeight: number, maxHeight: number, onSuccess?: (mesh: Mesh) => void, uvOffset?: Vector2, uvScale?: Vector2): Mesh {
             var scene = this.getScene();
 
             var onload = img => {
@@ -1416,6 +1476,7 @@
             };
 
             Tools.LoadImage(url, onload, () => { }, scene.database);
+            return this;
         }
 
         /**
@@ -1427,14 +1488,16 @@
          * The parameters `heightMapWidth` and `heightMapHeight` are positive integers to set the width and height of the buffer image.     
          * The parameters `minHeight` and `maxHeight` are the lower and upper limits of the displacement.
          * The parameter `uvOffset` is an optional vector2 used to offset UV.
-         * The parameter `uvScale` is an optional vector2 used to scale UV.
+         * The parameter `uvScale` is an optional vector2 used to scale UV.  
+         * 
+         * Returns the Mesh.  
          */
-        public applyDisplacementMapFromBuffer(buffer: Uint8Array, heightMapWidth: number, heightMapHeight: number, minHeight: number, maxHeight: number, uvOffset?: Vector2, uvScale?: Vector2): void {
+        public applyDisplacementMapFromBuffer(buffer: Uint8Array, heightMapWidth: number, heightMapHeight: number, minHeight: number, maxHeight: number, uvOffset?: Vector2, uvScale?: Vector2): Mesh {
             if (!this.isVerticesDataPresent(VertexBuffer.PositionKind)
                 || !this.isVerticesDataPresent(VertexBuffer.NormalKind)
                 || !this.isVerticesDataPresent(VertexBuffer.UVKind)) {
                 Tools.Warn("Cannot call applyDisplacementMap: Given mesh is not complete. Position, Normal or UV are missing");
-                return;
+                return this;
             }
 
             var positions = this.getVerticesData(VertexBuffer.PositionKind);
@@ -1474,15 +1537,16 @@
 
             this.updateVerticesData(VertexBuffer.PositionKind, positions);
             this.updateVerticesData(VertexBuffer.NormalKind, normals);
+            return this;
         }
 
         /**
          * Modify the mesh to get a flat shading rendering.
          * This means each mesh facet will then have its own normals. Usually new vertices are added in the mesh geometry to get this result.
-         * This method returns nothing.
+         * This method returns the Mesh.   
          * Warning : the mesh is really modified even if not set originally as updatable and, under the hood, a new VertexBuffer is allocated.
          */
-        public convertToFlatShadedMesh(): void {
+        public convertToFlatShadedMesh(): Mesh {
             /// <summary>Update normals and vertices to get a flat shading rendering.</summary>
             /// <summary>Warning: This may imply adding vertices to the mesh in order to get exactly 3 vertices per face</summary>
 
@@ -1572,16 +1636,16 @@
             }
 
             this.synchronizeInstances();
+            return this;
         }
 
         /**
          * This method removes all the mesh indices and add new vertices (duplication) in order to unfold facets into buffers.
          * In other words, more vertices, no more indices and a single bigger VBO.
-         * This method returns nothing.
-         * The mesh is really modified even if not set originally as updatable. Under the hood, a new VertexBuffer is allocated.
-         * 
+         * The mesh is really modified even if not set originally as updatable. Under the hood, a new VertexBuffer is allocated.  
+         * Returns the Mesh.  
          */
-        public convertToUnIndexedMesh(): void {
+        public convertToUnIndexedMesh(): Mesh {
             /// <summary>Remove indices by unfolding faces into buffers</summary>
             /// <summary>Warning: This implies adding vertices to the mesh in order to get exactly 3 vertices per face</summary>
 
@@ -1646,14 +1710,15 @@
             this._unIndexed = true;
 
             this.synchronizeInstances();
+            return this;
         }
 
         /**
          * Inverses facet orientations and inverts also the normals with `flipNormals` (default `false`) if true.
-         * This method returns nothing.
+         * This method returns the Mesh.
          * Warning : the mesh is really modified even if not set originally as updatable. A new VertexBuffer is created under the hood each call.
          */
-        public flipFaces(flipNormals: boolean = false): void {
+        public flipFaces(flipNormals: boolean = false): Mesh {
             var vertex_data = VertexData.ExtractFromMesh(this);
             var i: number;
             if (flipNormals && this.isVerticesDataPresent(VertexBuffer.NormalKind)) {
@@ -1671,6 +1736,7 @@
             }
 
             vertex_data.applyToMesh(this);
+            return this;
         }
 
         // Instances
@@ -1693,24 +1759,25 @@
         /**
          * Synchronises all the mesh instance submeshes to the current mesh submeshes, if any.
          * After this call, all the mesh instances have the same submeshes than the current mesh.
-         * This method returns nothing.   
+         * This method returns the Mesh.   
          */
-        public synchronizeInstances(): void {
+        public synchronizeInstances(): Mesh {
             for (var instanceIndex = 0; instanceIndex < this.instances.length; instanceIndex++) {
                 var instance = this.instances[instanceIndex];
                 instance._syncSubMeshes();
             }
+            return this;
         }
 
         /**
          * Simplify the mesh according to the given array of settings.
-         * Function will return immediately and will simplify async. It returns nothing.  
+         * Function will return immediately and will simplify async. It returns the Mesh.  
          * @param settings a collection of simplification settings.
          * @param parallelProcessing should all levels calculate parallel or one after the other.
          * @param type the type of simplification to run.
          * @param successCallback optional success callback to be called after the simplification finished processing all settings.
          */
-        public simplify(settings: Array<ISimplificationSettings>, parallelProcessing: boolean = true, simplificationType: SimplificationType = SimplificationType.QUADRATIC, successCallback?: (mesh?: Mesh, submeshIndex?: number) => void) {
+        public simplify(settings: Array<ISimplificationSettings>, parallelProcessing: boolean = true, simplificationType: SimplificationType = SimplificationType.QUADRATIC, successCallback?: (mesh?: Mesh, submeshIndex?: number) => void): Mesh {
             this.getScene().simplificationQueue.addTask({
                 settings: settings,
                 parallelProcessing: parallelProcessing,
@@ -1718,15 +1785,17 @@
                 simplificationType: simplificationType,
                 successCallback: successCallback
             });
+            return this;
         }
 
         /**
          * Optimization of the mesh's indices, in case a mesh has duplicated vertices.   
          * The function will only reorder the indices and will not remove unused vertices to avoid problems with submeshes.   
-         * This should be used together with the simplification to avoid disappearing triangles.   
+         * This should be used together with the simplification to avoid disappearing triangles.  
+         * Returns the Mesh.   
          * @param successCallback an optional success callback to be called after the optimization finished.   
          */
-        public optimizeIndices(successCallback?: (mesh?: Mesh) => void) {
+        public optimizeIndices(successCallback?: (mesh?: Mesh) => void): Mesh {
             var indices = this.getIndices();
             var positions = this.getVerticesData(VertexBuffer.PositionKind);
             var vectorPositions = [];
@@ -1758,6 +1827,7 @@
                     successCallback(this);
                 }
             });
+            return this;
         }
 
         // Statics
@@ -2532,16 +2602,18 @@
         }
 
         /**
-         * Update the vertex buffers by applying transformation from the bones
+         * Updates the vertex buffer by applying transformation from the bones.  
+         * Returns the Mesh.  
+         * 
          * @param {skeleton} skeleton to apply
          */
         public applySkeleton(skeleton: Skeleton): Mesh {
             if (!this.geometry) {
-                return;
+                return this;
             }
 
             if (this.geometry._softwareSkinningRenderId == this.getScene().getRenderId()) {
-                return;
+                return this;
             }
 
             this.geometry._softwareSkinningRenderId = this.getScene().getRenderId();
@@ -2730,4 +2802,4 @@
             return meshSubclass;
         }
     }
-}
+}

src/Mesh/babylon.mesh.vertexData.ts

@@ -71,23 +71,45 @@
             }
         }
 
-        public applyToMesh(mesh: Mesh, updatable?: boolean): void {
+        /**
+         * Associates the vertexData to the passed Mesh.  
+         * Sets it as updatable or not (default `false`).  
+         * Returns the VertexData.  
+         */
+        public applyToMesh(mesh: Mesh, updatable?: boolean): VertexData {
             this._applyTo(mesh, updatable);
+            return this;
         }
 
-        public applyToGeometry(geometry: Geometry, updatable?: boolean): void {
+        /**
+         * Associates the vertexData to the passed Geometry.  
+         * Sets it as updatable or not (default `false`).  
+         * Returns the VertexData.  
+         */
+        public applyToGeometry(geometry: Geometry, updatable?: boolean): VertexData {
             this._applyTo(geometry, updatable);
+            return this;
         }
 
-        public updateMesh(mesh: Mesh, updateExtends?: boolean, makeItUnique?: boolean): void {
+        /**
+         * Updates the associated mesh.  
+         * Returns the VertexData.  
+         */
+        public updateMesh(mesh: Mesh, updateExtends?: boolean, makeItUnique?: boolean): VertexData {
             this._update(mesh);
+            return this;
         }
 
-        public updateGeometry(geometry: Geometry, updateExtends?: boolean, makeItUnique?: boolean): void {
+        /**
+         * Updates the associated geometry.  
+         * Returns the VertexData.  
+         */
+        public updateGeometry(geometry: Geometry, updateExtends?: boolean, makeItUnique?: boolean): VertexData {
             this._update(geometry);
+            return this;
         }
 
-        private _applyTo(meshOrGeometry: IGetSetVerticesData, updatable?: boolean) {
+        private _applyTo(meshOrGeometry: IGetSetVerticesData, updatable?: boolean): VertexData {
             if (this.positions) {
                 meshOrGeometry.setVerticesData(VertexBuffer.PositionKind, this.positions, updatable);
             }
@@ -143,9 +165,10 @@
             if (this.indices) {
                 meshOrGeometry.setIndices(this.indices);
             }
+            return this;
         }
 
-        private _update(meshOrGeometry: IGetSetVerticesData, updateExtends?: boolean, makeItUnique?: boolean) {
+        private _update(meshOrGeometry: IGetSetVerticesData, updateExtends?: boolean, makeItUnique?: boolean): VertexData {
             if (this.positions) {
                 meshOrGeometry.updateVerticesData(VertexBuffer.PositionKind, this.positions, updateExtends, makeItUnique);
             }
@@ -201,9 +224,14 @@
             if (this.indices) {
                 meshOrGeometry.setIndices(this.indices);
             }
+            return this;
         }
 
-        public transform(matrix: Matrix): void {
+        /**
+         * Transforms each position and each normal of the vertexData according to the passed Matrix.  
+         * Returns the VertexData.  
+         */
+        public transform(matrix: Matrix): VertexData {
             var transformed = Vector3.Zero();
             var index: number;
             if (this.positions) {
@@ -231,9 +259,14 @@
                     this.normals[index + 2] = transformed.z;
                 }
             }
+            return this;
         }
 
-        public merge(other: VertexData): void {
+        /**
+         * Merges the passed VertexData into the current one.  
+         * Returns the modified VertexData.  
+         */
+        public merge(other: VertexData): VertexData {
             if (other.indices) {
                 if (!this.indices) {
                     this.indices = [];
@@ -259,6 +292,7 @@
             this.matricesWeights = this._mergeElement(this.matricesWeights, other.matricesWeights);
             this.matricesIndicesExtra = this._mergeElement(this.matricesIndicesExtra, other.matricesIndicesExtra);
             this.matricesWeightsExtra = this._mergeElement(this.matricesWeightsExtra, other.matricesWeightsExtra);
+            return this;
         }
 
         private _mergeElement(source: number[] | Float32Array, other: number[] | Float32Array): number[] | Float32Array {
@@ -290,6 +324,10 @@
             }
         }
 
+        /**
+         * Serializes the VertexData.  
+         * Returns a serialized object.  
+         */
         public serialize(): any {
             var serializationObject = this.serialize();
 
@@ -353,10 +391,16 @@
         }
 
         // Statics
+        /**
+         * Returns the object VertexData associated to the passed mesh.  
+         */
         public static ExtractFromMesh(mesh: Mesh, copyWhenShared?: boolean): VertexData {
             return VertexData._ExtractFrom(mesh, copyWhenShared);
         }
 
+        /**
+         * Returns the object VertexData associated to the passed geometry.  
+         */
         public static ExtractFromGeometry(geometry: Geometry, copyWhenShared?: boolean): VertexData {
             return VertexData._ExtractFrom(geometry, copyWhenShared);
         }
@@ -421,6 +465,9 @@
             return result;
         }
 
+        /**
+         * Creates the vertexData of the Ribbon.  
+         */
         public static CreateRibbon(options: { pathArray: Vector3[][], closeArray?: boolean, closePath?: boolean, offset?: number, sideOrientation?: number, invertUV?: boolean }): VertexData {
             var pathArray: Vector3[][] = options.pathArray;
             var closeArray: boolean = options.closeArray || false;
@@ -624,6 +671,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Box.  
+         */
         public static CreateBox(options: { size?: number, width?: number, height?: number, depth?: number, faceUV?: Vector4[], faceColors?: Color4[], sideOrientation?: number }): VertexData {
             var normalsSource = [
                 new Vector3(0, 0, 1),
@@ -730,6 +780,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Sphere.  
+         */
         public static CreateSphere(options: { segments?: number, diameter?: number, diameterX?: number, diameterY?: number, diameterZ?: number, arc?: number, slice?: number, sideOrientation?: number }): VertexData {
             var segments: number = options.segments || 32;
             var diameterX: number = options.diameterX || options.diameter || 1;
@@ -799,7 +852,9 @@
             return vertexData;
         }
 
-        // Cylinder and cone
+        /**
+         * Creates the VertexData of the Cylinder or Cone.  
+         */
         public static CreateCylinder(options: { height?: number, diameterTop?: number, diameterBottom?: number, diameter?: number, tessellation?: number, subdivisions?: number, arc?: number, faceColors?: Color4[], faceUV?: Vector4[], hasRings?: boolean, enclose?: boolean, sideOrientation?: number }): VertexData {
             var height: number = options.height || 2;
             var diameterTop: number = (options.diameterTop === 0) ? 0 : options.diameterTop || options.diameter || 1;
@@ -1047,6 +1102,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Torus.  
+         */
         public static CreateTorus(options: { diameter?: number, thickness?: number, tessellation?: number, sideOrientation?: number }) {
             var indices = [];
             var positions = [];
@@ -1115,6 +1173,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the LineSystem.  
+         */
         public static CreateLineSystem(options: { lines: Vector3[][] }): VertexData {
             var indices = [];
             var positions = [];
@@ -1139,6 +1200,9 @@
             return vertexData;
         }
 
+        /**
+         * Create the VertexData of the DashedLines.  
+         */
         public static CreateDashedLines(options: { points: Vector3[], dashSize?: number, gapSize?: number, dashNb?: number }): VertexData {
             var dashSize = options.dashSize || 3;
             var gapSize = options.gapSize || 1;
@@ -1183,6 +1247,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Ground.  
+         */
         public static CreateGround(options: { width?: number, height?: number, subdivisions?: number, subdivisionsX?: number, subdivisionsY?: number }): VertexData {
             var indices = [];
             var positions = [];
@@ -1229,6 +1296,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the TiledGround.  
+         */
         public static CreateTiledGround(options: { xmin: number, zmin: number, xmax: number, zmax: number, subdivisions?: { w: number; h: number; }, precision?: { w: number; h: number; } }): VertexData {
             var xmin = options.xmin || -1.0;
             var zmin = options.zmin || -1.0;
@@ -1313,6 +1383,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Ground designed from a heightmap.  
+         */
         public static CreateGroundFromHeightMap(options: { width: number, height: number, subdivisions: number, minHeight: number, maxHeight: number, buffer: Uint8Array, bufferWidth: number, bufferHeight: number }): VertexData {
             var indices = [];
             var positions = [];
@@ -1372,6 +1445,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Plane.  
+         */
         public static CreatePlane(options: { size?: number, width?: number, height?: number, sideOrientation?: number }): VertexData {
             var indices = [];
             var positions = [];
@@ -1425,6 +1501,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the Disc or regular Polygon.  
+         */
         public static CreateDisc(options: { radius?: number, tessellation?: number, arc?: number, sideOrientation?: number }): VertexData {
             var positions = [];
             var indices = [];
@@ -1475,6 +1554,9 @@
             return vertexData;
         }
 
+        /**
+         * Creates the VertexData of the IcoSphere.  
+         */
         public static CreateIcoSphere(options: { radius?: number, radiusX?: number, radiusY?: number, radiusZ?: number, flat?: boolean, subdivisions?: number, sideOrientation?: number }): VertexData {
             var sideOrientation = options.sideOrientation || Mesh.DEFAULTSIDE;
             var radius = options.radius || 1;
@@ -1736,6 +1818,9 @@
 
 
         // inspired from // http://stemkoski.github.io/Three.js/Polyhedra.html
+        /**
+         * Creates the VertexData of the Polyhedron.  
+         */
         public static CreatePolyhedron(options: { type?: number, size?: number, sizeX?: number, sizeY?: number, sizeZ?: number, custom?: any, faceUV?: Vector4[], faceColors?: Color4[], flat?: boolean, sideOrientation?: number }): VertexData {
             // provided polyhedron types :
             // 0 : Tetrahedron, 1 : Octahedron, 2 : Dodecahedron, 3 : Icosahedron, 4 : Rhombicuboctahedron, 5 : Triangular Prism, 6 : Pentagonal Prism, 7 : Hexagonal Prism, 8 : Square Pyramid (J1)
@@ -1868,6 +1953,9 @@
         }
 
         // based on http://code.google.com/p/away3d/source/browse/trunk/fp10/Away3D/src/away3d/primitives/TorusKnot.as?spec=svn2473&r=2473
+        /**
+         * Creates the VertexData of the Torus Knot.  
+         */
         public static CreateTorusKnot(options: { radius?: number, tube?: number, radialSegments?: number, tubularSegments?: number, p?: number, q?: number, sideOrientation?: number }): VertexData {
             var indices = [];
             var positions = [];
@@ -2208,6 +2296,9 @@
             }
         }
 
+        /**
+         * Creates a new VertexData from the imported parameters.  
+         */
         public static ImportVertexData(parsedVertexData: any, geometry: Geometry) {
             var vertexData = new VertexData();
 
@@ -2287,4 +2378,3 @@
         }
     }
 }
-

src/Mesh/babylon.subMesh.ts

@@ -34,6 +34,9 @@
             return (this.verticesStart === 0 && this.verticesCount == this._mesh.getTotalVertices());
         }
 
+        /**
+         * Returns the submesh BoudingInfo object.  
+         */
         public getBoundingInfo(): BoundingInfo {
             if (this.IsGlobal) {
                 return this._mesh.getBoundingInfo();
@@ -42,18 +45,32 @@
             return this._boundingInfo;
         }
 
-        public setBoundingInfo(boundingInfo: BoundingInfo): void {
+        /**
+         * Sets the submesh BoundingInfo.  
+         * Return the SubMesh.  
+         */
+        public setBoundingInfo(boundingInfo: BoundingInfo): SubMesh {
             this._boundingInfo = boundingInfo;
+            return this;
         }
 
+        /** 
+         * Returns the mesh of the current submesh.  
+         */
         public getMesh(): AbstractMesh {
             return this._mesh;
         }
 
+        /**
+         * Returns the rendering mesh of the submesh.  
+         */
         public getRenderingMesh(): Mesh {
             return this._renderingMesh;
         }
 
+        /**
+         * Returns the submesh material.  
+         */
         public getMaterial(): Material {
             var rootMaterial = this._renderingMesh.material;
 
@@ -70,7 +87,11 @@
         }
 
         // Methods
-        public refreshBoundingInfo(): void {
+        /**
+         * Sets a new updated BoundingInfo object to the submesh.  
+         * Returns the SubMesh.  
+         */
+        public refreshBoundingInfo(): SubMesh {
             this._lastColliderWorldVertices = null;
 
             if (this.IsGlobal) {
@@ -94,31 +115,54 @@
                 extend = Tools.ExtractMinAndMaxIndexed(data, indices, this.indexStart, this.indexCount, this._renderingMesh.geometry.boundingBias);
             }
             this._boundingInfo = new BoundingInfo(extend.minimum, extend.maximum);
+            return this;
         }
 
         public _checkCollision(collider: Collider): boolean {
             return this.getBoundingInfo()._checkCollision(collider);
         }
 
-        public updateBoundingInfo(world: Matrix): void {
+        /**
+         * Updates the submesh BoundingInfo.  
+         * Returns the Submesh.  
+         */
+        public updateBoundingInfo(world: Matrix): SubMesh {
             if (!this.getBoundingInfo()) {
                 this.refreshBoundingInfo();
             }
             this.getBoundingInfo().update(world);
+            return this;
         }
 
+        /**
+         * True is the submesh bounding box intersects the frustum defined by the passed array of planes.  
+         * Boolean returned.  
+         */
         public isInFrustum(frustumPlanes: Plane[]): boolean {
             return this.getBoundingInfo().isInFrustum(frustumPlanes);
         }
 
+        /**
+         * True is the submesh bounding box is completely inside the frustum defined by the passed array of planes.  
+         * Boolean returned.  
+         */        
         public isCompletelyInFrustum(frustumPlanes: Plane[]): boolean {
             return this.getBoundingInfo().isCompletelyInFrustum(frustumPlanes);
         }
 
-        public render(enableAlphaMode: boolean): void {
+        /**
+         * Renders the submesh.  
+         * Returns it.  
+         */
+        public render(enableAlphaMode: boolean): SubMesh {
             this._renderingMesh.render(this, enableAlphaMode);
+            return this;
         }
 
+        /**
+         * Returns a new Index Buffer.  
+         * Type returned : WebGLBuffer.  
+         */
         public getLinesIndexBuffer(indices: IndicesArray, engine: Engine): WebGLBuffer {
             if (!this._linesIndexBuffer) {
                 var linesIndices = [];
@@ -135,10 +179,17 @@
             return this._linesIndexBuffer;
         }
 
+        /**
+         * True is the passed Ray intersects the submesh bounding box.  
+         * Boolean returned.  
+         */
         public canIntersects(ray: Ray): boolean {
             return ray.intersectsBox(this.getBoundingInfo().boundingBox);
         }
 
+        /**
+         * Returns an object IntersectionInfo.  
+         */
         public intersects(ray: Ray, positions: Vector3[], indices: IndicesArray, fastCheck?: boolean): IntersectionInfo {
             var intersectInfo: IntersectionInfo = null;
 
@@ -195,6 +246,9 @@
         }
 
         // Clone    
+        /**
+         * Creates a new Submesh from the passed Mesh.  
+         */
         public clone(newMesh: AbstractMesh, newRenderingMesh?: Mesh): SubMesh {
             var result = new SubMesh(this.materialIndex, this.verticesStart, this.verticesCount, this.indexStart, this.indexCount, newMesh, newRenderingMesh, false);
 
@@ -206,7 +260,11 @@
         }
 
         // Dispose
-        public dispose() {
+        /**
+         * Disposes the Submesh.  
+         * Returns nothing.  
+         */
+        public dispose(): void {
             if (this._linesIndexBuffer) {
                 this._mesh.getScene().getEngine()._releaseBuffer(this._linesIndexBuffer);
                 this._linesIndexBuffer = null;
@@ -218,6 +276,14 @@
         }
 
         // Statics
+        /**
+         * Creates a new Submesh from the passed parameters : 
+         * - materialIndex (integer) : the index of the main mesh material.  
+         * - startIndex (integer) : the index where to start the copy in the mesh indices array.  
+         * - indexCount (integer) : the number of indices to copy then from the startIndex.  
+         * - mesh (Mesh) : the main mesh to create the submesh from.  
+         * - renderingMesh (optional Mesh) : rendering mesh.  
+         */
         public static CreateFromIndices(materialIndex: number, startIndex: number, indexCount: number, mesh: AbstractMesh, renderingMesh?: Mesh): SubMesh {
             var minVertexIndex = Number.MAX_VALUE;
             var maxVertexIndex = -Number.MAX_VALUE;
@@ -238,4 +304,3 @@
         }
     }
 }
-

src/Mesh/babylon.vertexBuffer.ts

@@ -59,55 +59,92 @@
             this._kind = kind;
         }
 
-
+        /**
+         * Returns the kind of the VertexBuffer (string).  
+         */
         public getKind(): string {
             return this._kind;
         }
 
         // Properties
+        /**
+         * Boolean : is the VertexBuffer updatable ?
+         */
         public isUpdatable(): boolean {
             return this._buffer.isUpdatable();
         }
 
+        /**
+         * Returns an array of numbers or a Float32Array containing the VertexBuffer data.  
+         */
         public getData(): number[] | Float32Array {
             return this._buffer.getData();
         }
 
+        /**
+         * Returns the WebGLBuffer associated to the VertexBuffer.  
+         */
         public getBuffer(): WebGLBuffer {
             return this._buffer.getBuffer();
         }
 
+        /**
+         * Returns the stride of the VertexBuffer (integer).  
+         */
         public getStrideSize(): number {
             return this._stride;
         }
 
+        /**
+         * Returns the offset (integer).  
+         */
         public getOffset(): number {
             return this._offset;
         }
 
+        /**
+         * Returns the VertexBuffer total size (integer).  
+         */
         public getSize(): number {
             return this._size;
         }
 
+        /**
+         * Boolean : is the WebGLBuffer of the VertexBuffer instanced now ?
+         */
         public getIsInstanced(): boolean {
             return this._buffer.getIsInstanced();
         }
 
         // Methods
 
-
+        /**
+         * Creates the underlying WebGLBuffer from the passed numeric array or Float32Array.  
+         * Returns the created WebGLBuffer.   
+         */
         public create(data?: number[] | Float32Array): void {
             return this._buffer.create(data);
         }
 
+        /**
+         * Updates the underlying WebGLBuffer according to the passed numeric array or Float32Array.  
+         * Returns the updated WebGLBuffer.  
+         */
         public update(data: number[] | Float32Array): void {
             return this._buffer.update(data);
         }
 
+        /**
+         * Updates directly the underlying WebGLBuffer according to the passed numeric array or Float32Array.  
+         * Returns the directly updated WebGLBuffer. 
+         */
         public updateDirectly(data: Float32Array, offset: number): void {
             return this._buffer.updateDirectly(data, offset);
         }
 
+        /** 
+         * Disposes the VertexBuffer and the underlying WebGLBuffer.  
+         */
         public dispose(): void {
             if (this._ownsBuffer) {
                 this._buffer.dispose();

src/Shaders/ShadersInclude/fogFragmentDeclaration.fx

@@ -8,7 +8,7 @@
 
 uniform vec4 vFogInfos;
 uniform vec3 vFogColor;
-varying float fFogDistance;
+varying vec3 vFogDistance;
 
 float CalcFogFactor()
 {
@@ -16,18 +16,19 @@ float CalcFogFactor()
 	float fogStart = vFogInfos.y;
 	float fogEnd = vFogInfos.z;
 	float fogDensity = vFogInfos.w;
+	float fogDistance = length(vFogDistance);
 
 	if (FOGMODE_LINEAR == vFogInfos.x)
 	{
-		fogCoeff = (fogEnd - fFogDistance) / (fogEnd - fogStart);
+		fogCoeff = (fogEnd - fogDistance) / (fogEnd - fogStart);
 	}
 	else if (FOGMODE_EXP == vFogInfos.x)
 	{
-		fogCoeff = 1.0 / pow(E, fFogDistance * fogDensity);
+		fogCoeff = 1.0 / pow(E, fogDistance * fogDensity);
 	}
 	else if (FOGMODE_EXP2 == vFogInfos.x)
 	{
-		fogCoeff = 1.0 / pow(E, fFogDistance * fFogDistance * fogDensity * fogDensity);
+		fogCoeff = 1.0 / pow(E, fogDistance * fogDistance * fogDensity * fogDensity);
 	}
 
 	return clamp(fogCoeff, 0.0, 1.0);

src/Shaders/ShadersInclude/fogVertex.fx

@@ -1,3 +1,3 @@
 #ifdef FOG
-fFogDistance = abs((view * worldPos).z);
+vFogDistance = (view * worldPos).xyz;
 #endif

src/Shaders/ShadersInclude/fogVertexDeclaration.fx

@@ -1,3 +1,3 @@
 #ifdef FOG
-	varying float fFogDistance;
+	varying vec3 vFogDistance;
 #endif

src/Shaders/sprites.vertex.fx

@@ -46,6 +46,6 @@ void main(void) {
 
 	// Fog
 #ifdef FOG
-	fFogDistance = abs(viewPos.z);
+	vFogDistance = viewPos;
 #endif
 }

src/Tools/babylon.assetsManager.ts

@@ -219,6 +219,40 @@
         }
     }
 
+      export class HDRCubeTextureAssetTask implements IAssetTask {
+        public onSuccess: (task: IAssetTask) => void;
+        public onError: (task: IAssetTask) => void;
+
+        public isCompleted = false;
+        public texture: HDRCubeTexture;
+
+        constructor(public name: string, public url: string, public size?: number, public noMipmap = false, public generateHarmonics = true, public useInGammaSpace = false, public usePMREMGenerator = false) {
+        }
+
+        public run(scene: Scene, onSuccess: () => void, onError: () => void) {
+
+            var onload = () => {
+                this.isCompleted = true;
+
+                if (this.onSuccess) {
+                    this.onSuccess(this);
+                }
+
+                onSuccess();
+            };
+
+            var onerror = () => {
+                if (this.onError) {
+                    this.onError(this);
+                }
+
+                onError();
+            };
+
+            this.texture = new HDRCubeTexture(this.url, scene, this.size, this.noMipmap, this.generateHarmonics, this.useInGammaSpace, this.usePMREMGenerator, onload, onerror);
+        }
+    }
+
     export class AssetsManager {
         private _scene: Scene;
 

src/babylon.engine.ts

@@ -1008,7 +1008,7 @@
 
             var mode = 0;
             if (backBuffer && color) {
-                this._gl.clearColor(color.r, color.g, color.b, color.a);
+                this._gl.clearColor(color.r, color.g, color.b, color.a !== undefined ? color.a : 1.0);
                 mode |= this._gl.COLOR_BUFFER_BIT;
             }
             if (depth) {
@@ -2724,7 +2724,7 @@
 
         public createRawCubeTexture(url: string, scene: Scene, size: number, format: number, type: number, noMipmap: boolean,
             callback: (ArrayBuffer: ArrayBuffer) => ArrayBufferView[],
-            mipmmapGenerator: ((faces: ArrayBufferView[]) => ArrayBufferView[][])): WebGLTexture {
+            mipmmapGenerator: ((faces: ArrayBufferView[]) => ArrayBufferView[][]), onLoad: () => void = null, onError: () => void = null): WebGLTexture {
             var gl = this._gl;
             var texture = gl.createTexture();
             scene._addPendingData(texture);
@@ -2754,6 +2754,9 @@
 
             var onerror = () => {
                 scene._removePendingData(texture);
+                if (onError){
+                    onError();
+                }
             };
 
             var internalCallback = (data) => {
@@ -2838,6 +2841,10 @@
 
                 this.resetTextureCache();
                 scene._removePendingData(texture);
+
+                if (onLoad) {
+                    onLoad();
+                }
             };
 
             Tools.LoadFile(url, data => {