comments for babylon.csg.ts

src/Mesh/babylon.csg.ts

@@ -72,13 +72,27 @@
      * Represents a plane in 3D space.
      */
     class Plane {
+        /**
+         * Initializes the plane
+         * @param normal The normal for the plane
+         * @param w 
+         */
         constructor(public normal: Vector3, public w: number) {
         }
 
-        // `BABYLON.CSG.Plane.EPSILON` is the tolerance used by `splitPolygon()` to decide if a
-        // point is on the plane.
+        
+        /**
+         * `BABYLON.CSG.Plane.EPSILON` is the tolerance used by `splitPolygon()` to decide if a
+         * point is on the plane
+         */
         static EPSILON = 1e-5;
 
+        /**
+         * Construct a plane from three points
+         * @param a Point a
+         * @param b Point b
+         * @param c Point c
+         */
         public static FromPoints(a: Vector3, b: Vector3, c: Vector3): Nullable<Plane> {
             var v0 = c.subtract(a);
             var v1 = b.subtract(a);
@@ -91,20 +105,34 @@
             return new Plane(n, Vector3.Dot(n, a));
         }
 
+        /**
+         * Clone, or make a deep copy of the plane
+         */
         public clone(): Plane {
             return new Plane(this.normal.clone(), this.w);
         }
 
+        /**
+         * Flip the face of the plane
+         */
         public flip() {
             this.normal.scaleInPlace(-1);
             this.w = -this.w;
         }
 
-        // Split `polygon` by this plane if needed, then put the polygon or polygon
-        // fragments in the appropriate lists. Coplanar polygons go into either
-        // `coplanarFront` or `coplanarBack` depending on their orientation with
-        // respect to this plane. Polygons in front or in back of this plane go into
-        // either `front` or `back`.
+        
+        /**
+         * Split `polygon` by this plane if needed, then put the polygon or polygon
+         * fragments in the appropriate lists. Coplanar polygons go into either
+        `* coplanarFront` or `coplanarBack` depending on their orientation with
+         * respect to this plane. Polygons in front or in back of this plane go into
+         * either `front` or `back`
+         * @param polygon The polygon to be split
+         * @param coplanarFront Will contain polygons coplanar with the plane that are oriented to the front of the plane
+         * @param coplanarBack Will contain polygons coplanar with the plane that are oriented to the back of the plane
+         * @param front Will contain the polygons in front of the plane
+         * @param back Will contain the polygons begind the plane
+         */
         public splitPolygon(polygon: Polygon, coplanarFront: Polygon[], coplanarBack: Polygon[], front: Polygon[], back: Polygon[]): void {
             var COPLANAR = 0;
             var FRONT = 1;
@@ -124,7 +152,7 @@
                 types.push(type);
             }
 
-            // Put the polygon in the correct list, splitting it when necessary.
+            // Put the polygon in the correct list, splitting it when necessary
             switch (polygonType) {
                 case COPLANAR:
                     (Vector3.Dot(this.normal, polygon.plane.normal) > 0 ? coplanarFront : coplanarBack).push(polygon);
@@ -169,19 +197,33 @@
         }
     }
 
-    // # class Polygon
-
-    // Represents a convex polygon. The vertices used to initialize a polygon must
-    // be coplanar and form a convex loop.
-    // 
-    // Each convex polygon has a `shared` property, which is shared between all
-    // polygons that are clones of each other or were split from the same polygon.
-    // This can be used to define per-polygon properties (such as surface color).
+    /**
+     * Represents a convex polygon. The vertices used to initialize a polygon must
+     * be coplanar and form a convex loop.
+     *
+     * Each convex polygon has a `shared` property, which is shared between all
+     * polygons that are clones of each other or were split from the same polygon.
+     * This can be used to define per-polygon properties (such as surface color)
+     */
     class Polygon {
+        /**
+         * Vertices of the polygon
+         */
         public vertices: Vertex[];
+        /**
+         * Properties that are shared across all polygons
+         */
         public shared: any;
+        /**
+         * A plane formed from the vertices of the polygon
+         */
         public plane: Plane;
 
+        /**
+         * Initializes the polygon
+         * @param vertices The vertices of the polygon
+         * @param shared The properties shared across all polygons
+         */
         constructor(vertices: Vertex[], shared: any) {
             this.vertices = vertices;
             this.shared = shared;
@@ -189,36 +231,50 @@
 
         }
 
+        /**
+         * Clones, or makes a deep copy, or the polygon
+         */
         public clone(): Polygon {
             var vertices = this.vertices.map(v => v.clone());
             return new Polygon(vertices, this.shared);
         }
 
+        /**
+         * Flips the faces of the polygon
+         */
         public flip() {
             this.vertices.reverse().map(v => { v.flip(); });
             this.plane.flip();
         }
     }
 
-    // # class Node
-
-    // Holds a node in a BSP tree. A BSP tree is built from a collection of polygons
-    // by picking a polygon to split along. That polygon (and all other coplanar
-    // polygons) are added directly to that node and the other polygons are added to
-    // the front and/or back subtrees. This is not a leafy BSP tree since there is
-    // no distinction between internal and leaf nodes.
+    /**
+     * Holds a node in a BSP tree. A BSP tree is built from a collection of polygons
+     * by picking a polygon to split along. That polygon (and all other coplanar
+     * polygons) are added directly to that node and the other polygons are added to
+     * the front and/or back subtrees. This is not a leafy BSP tree since there is
+     * no distinction between internal and leaf nodes
+     */
     class Node {
         private plane: Nullable<Plane> = null;
         private front: Nullable<Node> = null;
         private back: Nullable<Node> = null;
         private polygons = new Array<Polygon>();
 
+        /**
+         * Initializes the node
+         * @param polygons A collection of polygons held in the node
+         */
         constructor(polygons?: Array<Polygon>) {
             if (polygons) {
                 this.build(polygons);
             }
         }
 
+        /**
+         * Clones, or makes a deep copy, of the node
+         * @returns The cloned node
+         */
         public clone(): Node {
             var node = new Node();
             node.plane = this.plane && this.plane.clone();
@@ -228,7 +284,9 @@
             return node;
         }
 
-        // Convert solid space to empty space and empty space to solid space.
+        /**
+         * Convert solid space to empty space and empty space to solid space
+         */
         public invert(): void {
             for (var i = 0; i < this.polygons.length; i++) {
                 this.polygons[i].flip();
@@ -247,8 +305,13 @@
             this.back = temp;
         }
 
-        // Recursively remove all polygons in `polygons` that are inside this BSP
-        // tree.
+        
+        /**
+         * Recursively remove all polygons in `polygons` that are inside this BSP
+         * tree.
+         * @param polygons Polygons to remove from the BSP
+         * @returns Polygons clipped from the BSP
+         */
         clipPolygons(polygons: Polygon[]): Polygon[] {
             if (!this.plane) return polygons.slice();
             var front = new Array<Polygon>(), back = new Array<Polygon>();
@@ -266,15 +329,22 @@
             return front.concat(back);
         }
 
-        // Remove all polygons in this BSP tree that are inside the other BSP tree
-        // `bsp`.
+        
+        /**
+         * Remove all polygons in this BSP tree that are inside the other BSP tree
+         * `bsp`.
+         * @param bsp BSP containing polygons to remove from this BSP
+         */
         clipTo(bsp: Node): void {
             this.polygons = bsp.clipPolygons(this.polygons);
             if (this.front) this.front.clipTo(bsp);
             if (this.back) this.back.clipTo(bsp);
         }
 
-        // Return a list of all polygons in this BSP tree.
+        /**
+         * Return a list of all polygons in this BSP tree
+         * @returns List of all polygons in this BSP tree
+         */
         allPolygons(): Polygon[] {
             var polygons = this.polygons.slice();
             if (this.front) polygons = polygons.concat(this.front.allPolygons());
@@ -282,10 +352,14 @@
             return polygons;
         }
 
-        // Build a BSP tree out of `polygons`. When called on an existing tree, the
-        // new polygons are filtered down to the bottom of the tree and become new
-        // nodes there. Each set of polygons is partitioned using the first polygon
-        // (no heuristic is used to pick a good split).
+        
+        /**
+         * Build a BSP tree out of `polygons`. When called on an existing tree, the
+         * new polygons are filtered down to the bottom of the tree and become new
+         * nodes there. Each set of polygons is partitioned using the first polygon
+         * (no heuristic is used to pick a good split)
+         * @param polygons Polygons used to construct the BSP tree
+         */
         build(polygons: Polygon[]): void {
             if (!polygons.length) return;
             if (!this.plane) this.plane = polygons[0].plane.clone();
@@ -304,15 +378,36 @@
         }
     }
 
+    /**
+     * Class for building Constructive Solid Geometry
+     */
     export class CSG {
         private polygons = new Array<Polygon>();
+        /**
+         * The world matrix  
+         */
         public matrix: Matrix;
+        /**
+         * Stores the position
+         */
         public position: Vector3;
+        /**
+         * Stores the rotation
+         */
         public rotation: Vector3;
+        /**
+         * Stores the rotation quaternion
+         */
         public rotationQuaternion: Nullable<Quaternion>;
+        /**
+         * Stores the scaling vector
+         */
         public scaling: Vector3;
 
-        // Convert BABYLON.Mesh to BABYLON.CSG
+        /**
+         * Convert the BABYLON.Mesh to BABYLON.CSG
+         * @param mesh The BABYLON.Mesh to convert to BABYLON.CSG
+         */
         public static FromMesh(mesh: Mesh): CSG {
             var vertex: Vertex, normal: Vector3, uv: Vector2, position: Vector3,
                 polygon: Polygon,
@@ -379,13 +474,19 @@
         }
 
 
-        // Construct a BABYLON.CSG solid from a list of `BABYLON.CSG.Polygon` instances.
+        /**
+         * Construct a BABYLON.CSG solid from a list of `BABYLON.CSG.Polygon` instances.
+         * @param polygons Polygons used to construct a BABYLON.CSG solid
+         */
         private static FromPolygons(polygons: Polygon[]): CSG {
             var csg = new CSG();
             csg.polygons = polygons;
             return csg;
         }
 
+        /**
+         * Clones, or makes a deep copy, of the BABYLON.CSG
+         */
         public clone(): CSG {
             var csg = new CSG();
             csg.polygons = this.polygons.map(p => p.clone());
@@ -393,6 +494,11 @@
             return csg;
         }
 
+        /**
+         * Unions this CSG with another CSG
+         * @param csg The CSG to union against this CSG
+         * @returns The unioned CSG
+         */
         public union(csg: CSG): CSG {
             var a = new Node(this.clone().polygons);
             var b = new Node(csg.clone().polygons);
@@ -405,6 +511,10 @@
             return CSG.FromPolygons(a.allPolygons()).copyTransformAttributes(this);
         }
 
+        /**
+         * Unions this CSG with another CSG in place
+         * @param csg The CSG to union against this CSG
+         */
         public unionInPlace(csg: CSG): void {
             var a = new Node(this.polygons);
             var b = new Node(csg.polygons);
@@ -419,6 +529,10 @@
             this.polygons = a.allPolygons();
         }
 
+        /**
+         * Subtracts this CSG with another CSG
+         * @param csg The CSG to subtract against this CSG
+         */
         public subtract(csg: CSG): CSG {
             var a = new Node(this.clone().polygons);
             var b = new Node(csg.clone().polygons);
@@ -433,6 +547,10 @@
             return CSG.FromPolygons(a.allPolygons()).copyTransformAttributes(this);
         }
 
+        /**
+         * Subtracts this CSG with another CSG in place 
+         * @param csg The CSG to subtact against this CSG
+         */
         public subtractInPlace(csg: CSG): void {
             var a = new Node(this.polygons);
             var b = new Node(csg.polygons);
@@ -449,6 +567,10 @@
             this.polygons = a.allPolygons();
         }
 
+        /**
+         * Intersect this CSG with another CSG
+         * @param csg The CSG to intersect against this CSG
+         */
         public intersect(csg: CSG): CSG {
             var a = new Node(this.clone().polygons);
             var b = new Node(csg.clone().polygons);
@@ -462,6 +584,10 @@
             return CSG.FromPolygons(a.allPolygons()).copyTransformAttributes(this);
         }
 
+        /**
+         * Intersects this CSG with another CSG in place
+         * @param csg The CSG to intersect against this CSG
+         */
         public intersectInPlace(csg: CSG): void {
             var a = new Node(this.polygons);
             var b = new Node(csg.polygons);
@@ -477,8 +603,12 @@
             this.polygons = a.allPolygons();
         }
 
-        // Return a new BABYLON.CSG solid with solid and empty space switched. This solid is
-        // not modified.
+        
+        /**
+         * Return a new BABYLON.CSG solid with solid and empty space switched. This solid is
+         * not modified.
+         * @returns A new BABYLON.CSG solid with solid and empty space switched
+         */
         public inverse(): CSG {
             var csg = this.clone();
             csg.inverseInPlace();
@@ -489,9 +619,14 @@
             this.polygons.map(p => { p.flip(); });
         }
 
-        // This is used to keep meshes transformations so they can be restored
-        // when we build back a Babylon Mesh
-        // NB : All CSG operations are performed in world coordinates
+        
+        /**
+         * This is used to keep meshes transformations so they can be restored
+         * when we build back a Babylon Mesh
+         * NB : All CSG operations are performed in world coordinates
+         * @param csg The BABYLON.CSG to copy the transform attributes from
+         * @returns This BABYLON.CSG
+         */
         public copyTransformAttributes(csg: CSG): CSG {
             this.matrix = csg.matrix;
             this.position = csg.position;
@@ -502,8 +637,14 @@
             return this;
         }
 
-        // Build Raw mesh from CSG
-        // Coordinates here are in world space
+        /**
+         * Build Raw mesh from CSG
+         * Coordinates here are in world space
+         * @param name The name of the mesh geometry
+         * @param scene The BABYLON.Scene
+         * @param keepSubMeshes Specifies if the submeshes should be kept
+         * @returns A new BABYLON.Mesh
+         */
         public buildMeshGeometry(name: string, scene: Scene, keepSubMeshes: boolean): Mesh {
             var matrix = this.matrix.clone();
             matrix.invert();
@@ -617,7 +758,14 @@
             return mesh;
         }
 
-        // Build Mesh from CSG taking material and transforms into account
+        /**
+         * Build Mesh from CSG taking material and transforms into account
+         * @param name The name of the BABYLON.Mesh
+         * @param material The material of the BABYLON.Mesh
+         * @param scene The BABYLON.Scene
+         * @param keepSubMeshes Specifies if submeshes should be kept
+         * @returns The new BABYLON.Mesh
+         */
         public toMesh(name: string, material: Nullable<Material>, scene: Scene, keepSubMeshes: boolean): Mesh {
             var mesh = this.buildMeshGeometry(name, scene, keepSubMeshes);