Merge pull request #5190 from TrevorDev/miscDocs

Misc docs

dist/preview release/typedocValidationBaseline.json

@@ -313,201 +313,6 @@
         }
       }
     },
-    "BoundingInfo": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new BoundingInfo": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "minimum": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "maximum": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "boundingBox": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "boundingSphere": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isLocked": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "maximum": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "minimum": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "centerOn": {
-          "Comments": {
-            "MissingReturn": true
-          }
-        },
-        "intersects": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "boundingInfo": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "precise": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "intersectsPoint": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "point": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "isCompletelyInFrustum": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "frustumPlanes": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "update": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "world": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
-    "BoundingSphere": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "center": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "centerWorld": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "maximum": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "minimum": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "radius": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "radiusWorld": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "intersectsPoint": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "point": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "isInFrustum": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "frustumPlanes": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "Intersects": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "sphere0": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "sphere1": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
     "Buffer": {
       "Class": {
         "Comments": {
@@ -11301,286 +11106,6 @@
         }
       }
     },
-    "VolumetricLightScatteringPostProcess": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "useDiffuseColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "getClassName": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "setCustomMeshPosition": {
-          "Parameter": {
-            "position": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "CreateDefaultMesh": {
-          "Parameter": {
-            "name": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "scene": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
-    "DDSInfo": {
-      "Interface": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "dxgiFormat": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "height": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isCompressed": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isCube": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isFourCC": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isLuminance": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isRGB": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "mipmapCount": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "textureType": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "width": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
-    "DistanceJointData": {
-      "Interface": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "maxDistance": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
-    "IAnimatable": {
-      "Interface": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "animations": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
-    "ICullable": {
-      "Interface": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Method": {
-        "isCompletelyInFrustum": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "frustumPlanes": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "isInFrustum": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "frustumPlanes": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
-    "IFileRequest": {
-      "Interface": {
-        "Comments": {
-          "MissingText": true
-        }
-      }
-    },
-    "IGetSetVerticesData": {
-      "Method": {
-        "getVerticesData": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "kind": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "copyWhenShared": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "forceCopy": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "isVerticesDataPresent": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "kind": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setIndices": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "indices": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "totalVertices": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "updatable": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setVerticesData": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "kind": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "data": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "updatable": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "updateVerticesData": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "kind": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "data": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "updateExtends": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "makeItUnique": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
     "ILoadingScreen": {
       "Interface": {
         "Comments": {

src/Culling/babylon.boundingInfo.ts

@@ -22,22 +22,62 @@
         return extentsOverlap(result0.min, result0.max, result1.min, result1.max);
     }
 
+    /**
+     * Interface for cullable objects 
+     * @see https://doc.babylonjs.com/babylon101/materials#back-face-culling
+     */
     export interface ICullable {
+        /**
+         * Checks if the object or part of the object is in the frustum
+         * @param frustumPlanes Camera near/planes
+         * @returns true if the object is in frustum otherwise false
+         */
         isInFrustum(frustumPlanes: Plane[]): boolean;
+        /**
+         * Checks if a cullable object (mesh...) is in the camera frustum
+         * Unlike isInFrustum this cheks the full bounding box
+         * @param frustumPlanes Camera near/planes
+         * @returns true if the object is in frustum otherwise false
+         */
         isCompletelyInFrustum(frustumPlanes: Plane[]): boolean;
     }
 
+    /** 
+     * Info for a bounding data of a mesh
+     */
     export class BoundingInfo implements ICullable {
+        /**
+         * Bounding box for the mesh
+         */
         public boundingBox: BoundingBox;
+        /**
+         * Bounding sphere for the mesh
+         */
         public boundingSphere: BoundingSphere;
 
         private _isLocked = false;
-
-        constructor(public minimum: Vector3, public maximum: Vector3) {
+        /**
+         * Constructs bounding info
+         * @param minimum min vector of the bounding box/sphere
+         * @param maximum max vector of the bounding box/sphere
+         */
+        constructor(
+            /**
+             * min vector of the bounding box/sphere
+             */
+            public minimum: Vector3, 
+            /**
+             * max vector of the bounding box/sphere
+             */
+            public maximum: Vector3
+        ) {
             this.boundingBox = new BoundingBox(minimum, maximum);
             this.boundingSphere = new BoundingSphere(minimum, maximum);
         }
 
+        /**
+         * If the info is locked and won't be updated to avoid perf overhead
+         */
         public get isLocked(): boolean {
             return this._isLocked;
         }
@@ -47,6 +87,10 @@
         }
 
         // Methods
+        /**
+         * Updates the boudning sphere and box
+         * @param world world matrix to be used to update
+         */
         public update(world: Matrix) {
             if (this._isLocked) {
                 return;
@@ -59,6 +103,7 @@
          * Recreate the bounding info to be centered around a specific point given a specific extend.
          * @param center New center of the bounding info
          * @param extend New extend of the bounding info
+         * @returns the current bounding info
          */
         public centerOn(center: Vector3, extend: Vector3): BoundingInfo {
             this.minimum = center.subtract(extend);
@@ -108,6 +153,12 @@
             return size.length();
         }
 
+        /**
+         * Checks if a cullable object (mesh...) is in the camera frustum
+         * Unlike isInFrustum this cheks the full bounding box
+         * @param frustumPlanes Camera near/planes
+         * @returns true if the object is in frustum otherwise false
+         */
         public isCompletelyInFrustum(frustumPlanes: Plane[]): boolean {
             return this.boundingBox.isCompletelyInFrustum(frustumPlanes);
         }
@@ -116,6 +167,12 @@
             return collider._canDoCollision(this.boundingSphere.centerWorld, this.boundingSphere.radiusWorld, this.boundingBox.minimumWorld, this.boundingBox.maximumWorld);
         }
 
+        /**
+         * Checks if a point is inside the bounding box and bounding sphere or the mesh 
+         * @see https://doc.babylonjs.com/babylon101/intersect_collisions_-_mesh
+         * @param point the point to check intersection with
+         * @returns if the point intersects
+         */
         public intersectsPoint(point: Vector3): boolean {
             if (!this.boundingSphere.centerWorld) {
                 return false;
@@ -132,6 +189,13 @@
             return true;
         }
 
+        /**
+         * Checks if another bounding info intersects the bounding box and bounding sphere or the mesh
+         * @see https://doc.babylonjs.com/babylon101/intersect_collisions_-_mesh
+         * @param boundingInfo the bounding info to check intersection with
+         * @param precise if the intersection should be done using OBB
+         * @returns if the bounding info intersects
+         */
         public intersects(boundingInfo: BoundingInfo, precise: boolean): boolean {
             if (!this.boundingSphere.centerWorld || !boundingInfo.boundingSphere.centerWorld) {
                 return false;

src/Culling/babylon.boundingSphere.ts

@@ -3,12 +3,33 @@
     const _identityMatrix = Matrix.Identity();
     const _tempRadiusVector = new Vector3(0, 0, 0);
 
+    /**
+     * Class used to store bounding sphere information
+     */
     export class BoundingSphere {
+        /**
+         * Gets the center of the bounding sphere in local space
+         */
         public center: Vector3;
+        /**
+         * Radius of the bounding sphere in local space
+         */
         public radius: number;
+        /**
+         * Gets the center of the bounding sphere in world space
+         */
         public centerWorld: Vector3;
+        /**
+         * Radius of the bounding sphere in world space
+         */
         public radiusWorld: number;
+        /**
+         * Gets the minimum vector in local space
+         */
         public minimum: Vector3;
+        /**
+         * Gets the maximum vector in local space
+         */
         public maximum: Vector3;
 
         /**
@@ -65,6 +86,11 @@
             this.radiusWorld = Math.max(Math.abs(_tempRadiusVector.x), Math.abs(_tempRadiusVector.y), Math.abs(_tempRadiusVector.z)) * this.radius;
         }
 
+        /**
+         * Tests if the bounding sphere is intersecting the frustum planes
+         * @param frustumPlanes defines the frustum planes to test
+         * @returns true if there is an intersection
+         */
         public isInFrustum(frustumPlanes: Plane[]): boolean {
             for (var i = 0; i < 6; i++) {
                 if (frustumPlanes[i].dotCoordinate(this.centerWorld) <= -this.radiusWorld)
@@ -74,6 +100,11 @@
             return true;
         }
 
+        /**
+         * Tests if a point is inside the bounding sphere
+         * @param point defines the point to test
+         * @returns true if the point is inside the bounding sphere
+         */
         public intersectsPoint(point: Vector3): boolean {
             var x = this.centerWorld.x - point.x;
             var y = this.centerWorld.y - point.y;
@@ -88,6 +119,12 @@
         }
 
         // Statics
+        /**
+         * Checks if two sphere intersct
+         * @param sphere0 sphere 0
+         * @param sphere1 sphere 1
+         * @returns true if the speres intersect
+         */
         public static Intersects(sphere0: BoundingSphere, sphere1: BoundingSphere): boolean {
             var x = sphere0.centerWorld.x - sphere1.centerWorld.x;
             var y = sphere0.centerWorld.y - sphere1.centerWorld.y;

src/Mesh/babylon.mesh.vertexData.ts

@@ -3,7 +3,19 @@
      * Define an interface for all classes that will get and set the data on vertices
      */
     export interface IGetSetVerticesData {
+        /** 
+         * Gets a boolean indicating if specific vertex data is present
+         * @param kind defines the vertex data kind to use
+         * @returns true is data kind is present
+         */
         isVerticesDataPresent(kind: string): boolean;
+        /**
+         * Gets a specific vertex data attached to this geometry. Float data is constructed if the vertex buffer data cannot be returned directly.
+         * @param kind defines the data kind (Position, normal, etc...)
+         * @param copyWhenShared defines if the returned array must be cloned upon returning it if the current geometry is shared between multiple meshes
+         * @param forceCopy defines a boolean indicating that the returned array must be cloned upon returning it
+         * @returns a float array containing vertex data
+         */
         getVerticesData(kind: string, copyWhenShared?: boolean, forceCopy?: boolean): Nullable<FloatArray>;
         /**
          * Returns an array of integers or a typed array (Int32Array, Uint32Array, Uint16Array) populated with the mesh indices.  
@@ -12,8 +24,40 @@
          * @returns the indices array or an empty array if the mesh has no geometry
          */
         getIndices(copyWhenShared?: boolean, forceCopy?: boolean): Nullable<IndicesArray>;
+        /**
+         * Set specific vertex data
+         * @param kind defines the data kind (Position, normal, etc...)
+         * @param data defines the vertex data to use
+         * @param updatable defines if the vertex must be flagged as updatable (false as default)
+         * @param stride defines the stride to use (0 by default). This value is deduced from the kind value if not specified
+         */
         setVerticesData(kind: string, data: FloatArray, updatable: boolean): void;
+        /**
+         * Update a specific associated vertex buffer
+         * @param kind defines which buffer to write to (positions, indices, normals, etc). Possible `kind` values :
+         * - BABYLON.VertexBuffer.PositionKind
+         * - BABYLON.VertexBuffer.UVKind
+         * - BABYLON.VertexBuffer.UV2Kind
+         * - BABYLON.VertexBuffer.UV3Kind
+         * - BABYLON.VertexBuffer.UV4Kind
+         * - BABYLON.VertexBuffer.UV5Kind
+         * - BABYLON.VertexBuffer.UV6Kind
+         * - BABYLON.VertexBuffer.ColorKind
+         * - BABYLON.VertexBuffer.MatricesIndicesKind
+         * - BABYLON.VertexBuffer.MatricesIndicesExtraKind
+         * - BABYLON.VertexBuffer.MatricesWeightsKind
+         * - BABYLON.VertexBuffer.MatricesWeightsExtraKind 
+         * @param data defines the data source
+         * @param updateExtends defines if extends info of the mesh must be updated (can be null). This is mostly useful for "position" kind
+         * @param makeItUnique defines if the geometry associated with the mesh must be cloned to make the change only for this mesh (and not all meshes associated with the same geometry)
+         */
         updateVerticesData(kind: string, data: FloatArray, updateExtends?: boolean, makeItUnique?: boolean): void;
+        /**
+         * Creates a new index buffer
+         * @param indices defines the indices to store in the index buffer
+         * @param totalVertices defines the total number of vertices (could be null)
+         * @param updatable defines if the index buffer must be flagged as updatable (false by default)
+         */
         setIndices(indices: IndicesArray, totalVertices: Nullable<number>, updatable?: boolean): void;
     }
 

src/Physics/babylon.physicsJoint.ts

@@ -179,15 +179,33 @@ module BABYLON {
         setLimit(upperLimit: number, lowerLimit?: number, motorIndex?: number): void;
     }
 
+    /**
+     * Joint data for a distance joint
+     */
     export interface DistanceJointData extends PhysicsJointData {
+        /**
+         * Max distance the 2 joint objects can be apart
+         */
         maxDistance: number;
         //Oimo - minDistance
         //Cannon - maxForce
     }
 
+    /**
+     * Joint data from a spring joint
+     */
     export interface SpringJointData extends PhysicsJointData {
+        /**
+         * Length of the spring
+         */
         length: number;
+        /**
+         * Stiffness of the spring
+         */
         stiffness: number;
+        /**
+         * Damping of the spring
+         */
         damping: number;
         /** this callback will be called when applying the force to the impostors. */
         forceApplicationCallback: () => void;

src/PostProcess/babylon.volumetricLightScatteringPostProcess.ts

@@ -1,5 +1,7 @@
 module BABYLON {
-    // Inspired by http://http.developer.nvidia.com/GPUGems3/gpugems3_ch13.html
+    /**
+     *  Inspired by http://http.developer.nvidia.com/GPUGems3/gpugems3_ch13.html
+     */
     export class VolumetricLightScatteringPostProcess extends PostProcess {
         // Members
         private _volumetricLightScatteringPass: Effect;
@@ -37,7 +39,10 @@
         @serializeAsMeshReference()
         public mesh: Mesh;
 
-
+        /**
+         * @hidden
+         * VolumetricLightScatteringPostProcess.useDiffuseColor is no longer used, use the mesh material directly instead
+         */
         public get useDiffuseColor(): boolean {
             Tools.Warn("VolumetricLightScatteringPostProcess.useDiffuseColor is no longer used, use the mesh material directly instead");
             return false;
@@ -122,6 +127,10 @@
             });
         }
 
+        /**
+         * Returns the string "VolumetricLightScatteringPostProcess"
+         * @returns "VolumetricLightScatteringPostProcess"
+         */
         public getClassName(): string {
             return "VolumetricLightScatteringPostProcess";
         }
@@ -190,7 +199,7 @@
 
         /**
          * Sets the new light position for light scattering effect
-         * @param {BABYLON.Vector3} The new custom light position
+         * @param position The new custom light position
          */
         public setCustomMeshPosition(position: Vector3): void {
             this.customMeshPosition = position;
@@ -423,8 +432,8 @@
         // Static methods
         /**
         * Creates a default mesh for the Volumeric Light Scattering post-process
-        * @param {string} The mesh name
-        * @param {BABYLON.Scene} The scene where to create the mesh
+        * @param name The mesh name
+        * @param scene The scene where to create the mesh
         * @return {BABYLON.Mesh} the default mesh
         */
         public static CreateDefaultMesh(name: string, scene: Scene): Mesh {

src/Tools/babylon.dds.ts

@@ -86,18 +86,58 @@
     // var off_caps4 = 30;
     var off_dxgiFormat = 32
 
+    /**
+     * Direct draw surface info
+     * @see https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds-pguide
+     */
     export interface DDSInfo {
+        /**
+         * Width of the texture
+         */
         width: number;
+        /**
+         * Width of the texture
+         */
         height: number;
+        /**
+         * Number of Mipmaps for the texture
+         * @see https://en.wikipedia.org/wiki/Mipmap
+         */
         mipmapCount: number;
+        /**
+         * If the textures format is a known fourCC format
+         * @see https://www.fourcc.org/
+         */
         isFourCC: boolean;
+        /**
+         * If the texture is an RGB format eg. DXGI_FORMAT_B8G8R8X8_UNORM format
+         */
         isRGB: boolean;
+        /**
+         * If the texture is a lumincance format
+         */
         isLuminance: boolean;
+        /**
+         * If this is a cube texture
+         * @see https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dds-file-layout-for-cubic-environment-maps
+         */
         isCube: boolean;
+        /**
+         * If the texture is a compressed format eg. FOURCC_DXT1
+         */
         isCompressed: boolean;
+        /**
+         * The dxgiFormat of the texture
+         * @see https://docs.microsoft.com/en-us/windows/desktop/api/dxgiformat/ne-dxgiformat-dxgi_format
+         */
         dxgiFormat: number;
+        /**
+         * Texture type eg. Engine.TEXTURETYPE_UNSIGNED_INT, Engine.TEXTURETYPE_FLOAT
+         */
         textureType: number;
-        /** Sphericle polynomial created for the dds texture */
+        /** 
+         * Sphericle polynomial created for the dds texture
+         */
         sphericalPolynomial?: SphericalPolynomial;
     };
 

src/Tools/babylon.tools.ts

@@ -1,5 +1,11 @@
 module BABYLON {
+    /**
+     * Interface containing an array of animations
+     */
     export interface IAnimatable {
+        /**
+         * Array of animations
+         */
         animations: Array<Animation>;
     }
 
@@ -110,6 +116,9 @@
         }
     }
 
+    /**
+     * File request interface
+     */
     export interface IFileRequest {
         /**
          * Raised when the request is complete (success or error).