Merge pull request #1048 from jbousquie/doc

API doc : MeshBuilder class completed + SPS cosmetic fixes

src/Mesh/babylon.meshBuilder.ts

@@ -88,7 +88,7 @@
          * The parameter `pathArray` is a required array of paths, what are each an array of successive Vector3. The pathArray parameter depicts the ribbon geometry.    
          * The parameter `closeArray` (boolean, default false) creates a seam between the first and the last paths of the path array.  
          * The parameter `closePath` (boolean, default false) creates a seam between the first and the last points of each path of the path array.  
-         * The optional parameter èinstance` is an instance of an existing Ribbon object to be updated with the passed `pathArray` parameter : http://doc.babylonjs.com/tutorials/How_to_dynamically_morph_a_mesh#ribbon   
+         * The optional parameter `instance` is an instance of an existing Ribbon object to be updated with the passed `pathArray` parameter : http://doc.babylonjs.com/tutorials/How_to_dynamically_morph_a_mesh#ribbon   
          * You can also set the mesh side orientation with the values : BABYLON.Mesh.FRONTSIDE (default), BABYLON.Mesh.BACKSIDE or BABYLON.Mesh.DOUBLESIDE  
          * Detail here : http://doc.babylonjs.com/tutorials/02._Discover_Basic_Elements#side-orientation    
          * The mesh can be set to updatable with the boolean parameter `updatable` (default false) if its internal geometry is supposed to change once created.  
@@ -462,16 +462,16 @@
          * The lathe is a shape with a symetry axis : a 2D model shape is rotated around this axis to design the lathe.      
          * tuto : http://doc.babylonjs.com/tutorials/Mesh_CreateXXX_Methods_With_Options_Parameter#lathe  
          *
-         * The parameter "shape" is a required array of successive Vector3. This array depicts the shape to be rotated in its local space : the shape must be designed in the xOy plane and will be
+         * The parameter `shape` is a required array of successive Vector3. This array depicts the shape to be rotated in its local space : the shape must be designed in the xOy plane and will be
          * rotated around the Y axis. It's usually a 2D shape, so the Vector3 z coordinates are often set to zero.    
-         * The parameter "radius" (positive float, default 1) is the radius value of the lathe.        
-         * The parameter "tessellation" (positive integer, default 64) is the side number of the lathe.      
-         * The parameter "arc" (positive float, default 1) is the ratio of the lathe. 0.5 builds for instance half a lathe, so an opened shape.  
-         * The parameter "closed" (boolean, default true) opens/closes the lathe circumference. This should be set to false when used with the parameter "arc".        
-         * The parameter "cap" sets the way the extruded shape is capped. Possible values : BABYLON.Mesh.NO_CAP (default), BABYLON.Mesh.CAP_START, BABYLON.Mesh.CAP_END, BABYLON.Mesh.CAP_ALL          
+         * The parameter `radius` (positive float, default 1) is the radius value of the lathe.        
+         * The parameter `tessellation` (positive integer, default 64) is the side number of the lathe.      
+         * The parameter `arc` (positive float, default 1) is the ratio of the lathe. 0.5 builds for instance half a lathe, so an opened shape.  
+         * The parameter `closed` (boolean, default true) opens/closes the lathe circumference. This should be set to false when used with the parameter "arc".        
+         * The parameter `cap` sets the way the extruded shape is capped. Possible values : BABYLON.Mesh.NO_CAP (default), BABYLON.Mesh.CAP_START, BABYLON.Mesh.CAP_END, BABYLON.Mesh.CAP_ALL          
          * You can also set the mesh side orientation with the values : BABYLON.Mesh.FRONTSIDE (default), BABYLON.Mesh.BACKSIDE or BABYLON.Mesh.DOUBLESIDE  
          * Detail here : http://doc.babylonjs.com/tutorials/02._Discover_Basic_Elements#side-orientation    
-         * The mesh can be set to updatable with the boolean parameter "updatable" (default false) if its internal geometry is supposed to change once created.  
+         * The mesh can be set to updatable with the boolean parameter `updatable` (default false) if its internal geometry is supposed to change once created.  
          */
         public static CreateLathe(name: string, options: { shape: Vector3[], radius?: number, tessellation?: number, arc?: number, closed?: boolean, updatable?: boolean, sideOrientation?: number, cap?: number }, scene: Scene): Mesh {
             var arc: number = (options.arc <= 0 || options.arc > 1) ? 1.0 : options.arc || 1.0;
@@ -659,6 +659,27 @@
             return ground;
         }
 
+        /**
+         * Creates a tube mesh.    
+         * The tube is a parametric shape :  http://doc.babylonjs.com/tutorials/Parametric_Shapes.  It has no predefined shape. Its final shape will depend on the input parameters.    
+         *
+         * tuto : http://doc.babylonjs.com/tutorials/Mesh_CreateXXX_Methods_With_Options_Parameter#tube     
+         * The parameter `path` is a required array of successive `Vector3`. It is the curve used as the axis of the tube.        
+         * The parameter `radius` (positive float, default 1) sets the tube radius size.    
+         * The parameter `tessellation` (positive float, default 64) is the number of sides on the tubular surface.  
+         * The parameter `radiusFunction` (javascript function, default null) is a vanilla javascript function. If it is not null, it overwrittes the parameter `radius`. 
+         * This function is called on each point of the tube path and is passed the index `i` of the i-th point and the distance of this point from the first point of the path. 
+         * It must return a radius value (positive float) : 
+         * ```var radiusFunction = function(i, distance) {
+         *   // do things
+         *   return radius; }```
+         * The parameter `arc` (positive float, maximum 1, default 1) is the ratio to apply to the tube circumference : 2 x PI x arc.  
+         * The parameter `cap` sets the way the extruded shape is capped. Possible values : BABYLON.Mesh.NO_CAP (default), BABYLON.Mesh.CAP_START, BABYLON.Mesh.CAP_END, BABYLON.Mesh.CAP_ALL         
+         * The optional parameter `instance` is an instance of an existing Tube object to be updated with the passed `pathArray` parameter : http://doc.babylonjs.com/tutorials/How_to_dynamically_morph_a_mesh#tube    
+         * You can also set the mesh side orientation with the values : BABYLON.Mesh.FRONTSIDE (default), BABYLON.Mesh.BACKSIDE or BABYLON.Mesh.DOUBLESIDE  
+         * Detail here : http://doc.babylonjs.com/tutorials/02._Discover_Basic_Elements#side-orientation    
+         * The mesh can be set to updatable with the boolean parameter `updatable` (default false) if its internal geometry is supposed to change once created.  
+         */
         public static CreateTube(name: string, options: { path: Vector3[], radius?: number, tessellation?: number, radiusFunction?: { (i: number, distance: number): number; }, cap?: number, arc?: number, updatable?: boolean, sideOrientation?: number, instance?: Mesh }, scene: Scene): Mesh {
             var path = options.path;
             var radius = options.radius || 1;
@@ -759,6 +780,23 @@
             return tube;
         }
 
+        /**
+         * Creates a polyhedron mesh.  
+         * 
+         * tuto : http://doc.babylonjs.com/tutorials/Mesh_CreateXXX_Methods_With_Options_Parameter#polyhedron  
+         * The parameter `type` (positive integer, max 14, default 0) sets the polyhedron type to build among the 15 embbeded types. Please refer to the type sheet in the tutorial
+         *  to choose the wanted type.  
+         * The parameter `size` (positive float, default 1) sets the polygon size.  
+         * You can overwrite the `size` on each dimension bu using the parameters `sizeX`, `sizeY` or `sizeZ` (positive floats, default to `size` value).  
+         * You can build other polyhedron types than the 15 embbeded ones by setting the parameter `custom` (`polyhedronObject`, default null). If you set the parameter `custom`, this overwrittes the parameter `type`.  
+         * A `polyhedronObject` is a formatted javascript object. You'll find a full file with pre-set polyhedra here : https://github.com/BabylonJS/Extensions/tree/master/Polyhedron    
+         * You can set the color and the UV of each side of the polyhedron with the parameters `faceColors` (`Color4`, default `(1, 1, 1, 1)`) and faceUV (`Vector4`, default `(0, 0, 1, 1)`). 
+         * To understand how to set `faceUV` or `faceColors`, please read this by considering the right number of faces of your polyhedron, instead of only 6 for the box : http://doc.babylonjs.com/tutorials/CreateBox_Per_Face_Textures_And_Colors  
+         * The parameter `flat` (boolean, default true). If set to false, it gives the polyhedron a single global face, so less vertices and shared normals. In this case, `faceColors` and `faceUV` are ignored.    
+         * You can also set the mesh side orientation with the values : BABYLON.Mesh.FRONTSIDE (default), BABYLON.Mesh.BACKSIDE or BABYLON.Mesh.DOUBLESIDE  
+         * Detail here : http://doc.babylonjs.com/tutorials/02._Discover_Basic_Elements#side-orientation    
+         * The mesh can be set to updatable with the boolean parameter `updatable` (default false) if its internal geometry is supposed to change once created.   
+         */
         public static CreatePolyhedron(name: string, options: { type?: number, size?: number, sizeX?: number, sizeY?: number, sizeZ?: number, custom?: any, faceUV?: Vector4[], faceColors?: Color4[], flat?: boolean, updatable?: boolean, sideOrientation?: number }, scene: Scene): Mesh {
             var polyhedron = new Mesh(name, scene);
 
@@ -769,6 +807,15 @@
             return polyhedron;
         }
 
+        /**
+         * Creates a decal mesh.  
+         * tuto : http://doc.babylonjs.com/tutorials/Mesh_CreateXXX_Methods_With_Options_Parameter#decals  
+         * A decal is a mesh usually applied as a model onto the surface of another mesh. So don't forget the parameter `sourceMesh` depicting the decal.  
+         * The parameter `position` (`Vector3`, default `(0, 0, 0)`) sets the position of the decal in World coordinates.  
+         * The parameter `normal` (`Vector3`, default `Vector3.Up`) sets the normal of the mesh where the decal is applied onto in World coordinates.  
+         * The parameter `size` (`Vector3`, default `(1, 1, 1)`) sets the decal scaling.  
+         * The parameter `angle` (float in radian, default 0) sets the angle to rotate the decal.  
+         */
         public static CreateDecal(name: string, sourceMesh: AbstractMesh, options: { position?: Vector3, normal?: Vector3, size?: Vector3, angle?: number }): Mesh {
             var indices = sourceMesh.getIndices();
             var positions = sourceMesh.getVerticesData(VertexBuffer.PositionKind);

src/Particles/babylon.solidParticleSystem.ts

@@ -36,12 +36,12 @@ module BABYLON {
         */
         public vars: any = {};
         /**
-        * This array is populated when the SPS is set as 'pickable'.
-        * Each key of this array is a faceId value that you can get from a pickResult object.
-        * Each element of this array is an object {idx: int, faceId: int}.
-        * idx is the picked particle index in the SPS.particles array
-        * faceId is the picked face index counted within this particles
-        * Please read : http://doc.babylonjs.com/tutorials/Solid_Particle_System#pickable-particles
+        * This array is populated when the SPS is set as 'pickable'.  
+        * Each key of this array is a `faceId` value that you can get from a pickResult object.  
+        * Each element of this array is an object `{idx: int, faceId: int}`.  
+        * `idx` is the picked particle index in the `SPS.particles` array  
+        * `faceId` is the picked face index counted within this particle.  
+        * Please read : http://doc.babylonjs.com/tutorials/Solid_Particle_System#pickable-particles  
         */
         public pickedParticles: { idx: number; faceId: number }[];
 
@@ -106,9 +106,10 @@ module BABYLON {
 
         /**
         * Creates a SPS (Solid Particle System) object.
-        * @param name the SPS name, this will be the underlying mesh name
-        * @param scene the scene in which the SPS is added
-        * @param options "updatable" (default true) : if the SPS must be updatable or immutable, "isPickable" (default false) : if the solid particles must be pickable
+        * `name` (String) is the SPS name, this will be the underlying mesh name.  
+        * `scene` (Scene) is the scene in which the SPS is added.  
+        * `updatableè (default true) : if the SPS must be updatable or immutable.  
+        * `isPickable` (default false) : if the solid particles must be pickable.  
         */
         constructor(name: string, scene: Scene, options?: { updatable?: boolean; isPickable?: boolean }) {
             this.name = name;
@@ -127,7 +128,7 @@ module BABYLON {
 
         /**
         * Builds the SPS underlying mesh. Returns a standard Mesh.
-        * If no model shape was added to the SPS, the return mesh is only a single triangular plane.
+        * If no model shape was added to the SPS, the returned mesh is just a single triangular plane.
         */
         public buildMesh(): Mesh {
             if (this.nbParticles === 0) {
@@ -170,15 +171,15 @@ module BABYLON {
         }
 
         /**
-        * Digests the mesh and generates as many solid particles in the system as wanted.
+        * Digests the mesh and generates as many solid particles in the system as wanted. Returns the SPS.  
         * These particles will have the same geometry than the mesh parts and will be positioned at the same localisation than the mesh original places.
-        * Thus the particles generated from digest() have their property "positiion" yet set.
-        * @param mesh the mesh to be digested
-        * @param facetNb the number of mesh facets per particle (optional, default 1), this parameter is overriden by the parameter "number" if any
-        * @param delta the random extra number of facets per partical (optional, default 0), each particle will have between facetNb and facetNb + delta facets
-        * @param number the wanted number of particles : each particle is built with mesh_total_facets / number facets (optional)
+        * Thus the particles generated from `digest()` have their property `position` set yet.  
+        * `mesh` (`Mesh`) is the mesh to be digested  
+        * `facetNb` (optional integer, default 1) is the number of mesh facets per particle, this parameter is overriden by the parameter `number` if any
+        * `delta` (optional integer, default 0) is the random extra number of facets per particle , each particle will have between `facetNb` and `facetNb + delta` facets
+        * `number` (optional positive integer) is the wanted number of particles : each particle is built with `mesh_total_facets / number` facets
         */
-        public digest(mesh: Mesh, options?: { facetNb?: number; number?: number; delta?: number }): void {
+        public digest(mesh: Mesh, options?: { facetNb?: number; number?: number; delta?: number }): SolidParticleSystem {
             var size: number = (options && options.facetNb) || 1;
             var number: number = (options && options.number);
             var delta: number = (options && options.delta) || 0;
@@ -262,6 +263,7 @@ module BABYLON {
                 this._shapeCounter++;
                 f += size;
             }
+            return this;
         }
 
         //reset copy
@@ -382,11 +384,12 @@ module BABYLON {
         }
 
         /**
-        * Adds some particles to the SPS from the model shape.
+        * Adds some particles to the SPS from the model shape. Returns the shape id.   
         * Please read the doc : http://doc.babylonjs.com/tutorials/Solid_Particle_System#create-an-immutable-sps
-        * @param mesh any Mesh object that will be used as a model for the solid particles.
-        * @param nb the number of particles to be created from this model
-        * @param options positionFunction is an optional javascript function to called for each particle on SPS creation. vertexFunction an optional javascript function to called for each vertex of each particle on SPS creation
+        * `mesh` is any `Mesh` object that will be used as a model for the solid particles.
+        * `nb` (positive integer) the number of particles to be created from this model
+        * `positionFunction` is an optional javascript function to called for each particle on SPS creation. 
+        * `vertexFunction` is an optional javascript function to called for each vertex of each particle on SPS creation
         */
         public addShape(mesh: Mesh, nb: number, options?: { positionFunction?: any; vertexFunction?: any }): number {
             var meshPos = mesh.getVerticesData(VertexBuffer.PositionKind);
@@ -482,7 +485,7 @@ module BABYLON {
 
         /**
         *  Sets all the particles : this method actually really updates the mesh according to the particle positions, rotations, colors, textures, etc.
-        *  This method calls updateParticle() for each particles of the SPS.
+        *  This method calls `updateParticle()` for each particle of the SPS.
         *  For an animated SPS, it is usually called within the render loop.
         * @param start (default 0) the particle index in the particle array where to start to compute the particle property values
         * @param end (default nbParticle - 1)  the particle index in the particle array where to stop to compute the particle property values
@@ -734,7 +737,7 @@ module BABYLON {
         }
 
         /**
-        *  Visibilty helper : Recomputes the visible size according to the mesh bounding box
+        * Visibilty helper : Recomputes the visible size according to the mesh bounding box
         * doc : http://doc.babylonjs.com/tutorials/Solid_Particle_System#sps-visibility
         */
         public refreshVisibleSize(): void {
@@ -743,7 +746,8 @@ module BABYLON {
             }
         }
 
-        /** Visibility helper : Sets the size of a visibility box, this sets the underlying mesh bounding box.
+        /** 
+        * Visibility helper : Sets the size of a visibility box, this sets the underlying mesh bounding box.
         * @param size the size (float) of the visibility box
         * note : this doesn't lock the SPS mesh bounding box.
         * doc : http://doc.babylonjs.com/tutorials/Solid_Particle_System#sps-visibility
@@ -755,9 +759,6 @@ module BABYLON {
 
 
         // getter and setter
-        /**
-        * True if the SPS is set as always visible
-        */
         public get isAlwaysVisible(): boolean {
             return this._alwaysVisible;
         }
@@ -780,40 +781,37 @@ module BABYLON {
             this.mesh.getBoundingInfo().isLocked = val;
         }
 
-        /**
-        * True if the SPS visibility box is locked. The underlying mesh bounding box is then not updatable any more.
-        */
         public get isVisibilityBoxLocked(): boolean {
             return this._isVisibilityBoxLocked;
         }
 
         // Optimizer setters
         /**
-        * Tells to setParticles() to compute the particle rotations or not.
+        * Tells to `setParticles()` to compute the particle rotations or not.
         * Default value : true. The SPS is faster when it's set to false.
-        * Note : the particle rotations aren't stored values, so setting computeParticleRotation to false will prevents the particle to rotate.
+        * Note : the particle rotations aren't stored values, so setting `computeParticleRotation` to false will prevents the particle to rotate.
         */
         public set computeParticleRotation(val: boolean) {
             this._computeParticleRotation = val;
         }
         /**
-        * Tells to setParticles() to compute the particle colors or not.
+        * Tells to `setParticles()` to compute the particle colors or not.
         * Default value : true. The SPS is faster when it's set to false.
-        * Note : the particle colors are stored values, so setting computeParticleColor to false will keep yet the last colors set.
+        * Note : the particle colors are stored values, so setting `computeParticleColor` to false will keep yet the last colors set.
         */
         public set computeParticleColor(val: boolean) {
             this._computeParticleColor = val;
         }
         /**
-        * Tells to setParticles() to compute the particle textures or not.
+        * Tells to `setParticles()` to compute the particle textures or not.
         * Default value : true. The SPS is faster when it's set to false.
-        * Note : the particle textures are stored values, so setting computeParticleTexture to false will keep yet the last colors set.
+        * Note : the particle textures are stored values, so setting `computeParticleTexture` to false will keep yet the last colors set.
         */
         public set computeParticleTexture(val: boolean) {
             this._computeParticleTexture = val;
         }
         /**
-        * Tells to setParticles() to call the vertex function for each vertex of each particle, or not.
+        * Tells to `setParticles()` to call the vertex function for each vertex of each particle, or not.
         * Default value : false. The SPS is faster when it's set to false.
         * Note : the particle custom vertex positions aren't stored values.
         */
@@ -821,7 +819,7 @@ module BABYLON {
             this._computeParticleVertex = val;
         }
         /**
-        * Tells to setParticles() to compute or not the mesh bounding box when computing the particle positions.
+        * Tells to `setParticles()` to compute or not the mesh bounding box when computing the particle positions.
         */
         public set computeBoundingBox(val: boolean) {
             this._computeBoundingBox = val;
@@ -854,7 +852,7 @@ module BABYLON {
 
 
         /**
-        * This function does nothing. It may be overwritten to set all the particles first values.
+        * This function does nothing. It may be overwritten to set all the particle first values.
         * The SPS doesn't call this function, you may have to call it by your own.
         * doc : http://doc.babylonjs.com/tutorials/Solid_Particle_System#particle-management
         */
@@ -872,7 +870,7 @@ module BABYLON {
 
         /**
         * Updates a particle : this function should  be overwritten by the user.
-        * It is called on each particle by setParticles(). This is the place to code each particle behavior.
+        * It is called on each particle by `setParticles()`. This is the place to code each particle behavior.
         * doc : http://doc.babylonjs.com/tutorials/Solid_Particle_System#particle-management
         * ex : just set a particle position or velocity and recycle conditions
         */
@@ -882,7 +880,7 @@ module BABYLON {
 
         /**
         * Updates a vertex of a particle : it can be overwritten by the user.
-        * This will be called on each vertex particle by setParticles() if computeParticleVertex is set to true only.
+        * This will be called on each vertex particle by `setParticles()` if `computeParticleVertex` is set to true only.
         * @param particle the current particle
         * @param vertex the current index of the current particle
         * @param pt the index of the current vertex in the particle shape
@@ -894,7 +892,7 @@ module BABYLON {
         }
 
         /**
-        * This will be called before any other treatment by setParticles() and will be passed three parameters.
+        * This will be called before any other treatment by `setParticles()` and will be passed three parameters.
         * This does nothing and may be overwritten by the user.
         * @param start the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
         * @param stop the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()
@@ -903,7 +901,7 @@ module BABYLON {
         public beforeUpdateParticles(start?: number, stop?: number, update?: boolean): void {
         }
         /**
-        * This will be called  by setParticles() after all the other treatments and just before the actual mesh update.
+        * This will be called  by `setParticles()` after all the other treatments and just before the actual mesh update.
         * This will be passed three parameters.
         * This does nothing and may be overwritten by the user.
         * @param start the particle index in the particle array where to stop to iterate, same than the value passed to setParticle()