Merge pull request #5242 from TrevorDev/transformNodeDocs

transform node docs

src/Mesh/babylon.transformNode.ts

@@ -1,10 +1,29 @@
 module BABYLON {
+    /**
+     * A TransformNode is an object that is not rendered but can be used as a center of transformation. This can decrease memory usage and increase rendering speed compared to using an empty mesh as a parent and is less complicated than using a pivot matrix.
+     * @see https://doc.babylonjs.com/how_to/transformnode
+     */
     export class TransformNode extends Node {
         // Statics
+        /**
+         * Object will not rotate to face the camera
+         */
         public static BILLBOARDMODE_NONE = 0;
+        /**
+         * Object will rotate to face the camera but only on the x axis
+         */
         public static BILLBOARDMODE_X = 1;
+        /**
+         * Object will rotate to face the camera but only on the y axis
+         */
         public static BILLBOARDMODE_Y = 2;
+        /**
+         * Object will rotate to face the camera but only on the z axis
+         */
         public static BILLBOARDMODE_Z = 4;
+        /**
+         * Object will rotate to face the camera
+         */
         public static BILLBOARDMODE_ALL = 7;
 
         private _forward = new Vector3(0, 0, 1);
@@ -43,9 +62,15 @@ module BABYLON {
         @serialize()
         public billboardMode = TransformNode.BILLBOARDMODE_NONE;
 
+        /**
+         * Multiplication factor on scale x/y/z when computing the world matrix. Eg. for a 1x1x1 cube setting this to 2 will make it a 2x2x2 cube
+         */
         @serialize()
         public scalingDeterminant = 1;
 
+        /**
+         * Sets the distance of the object to max, often used by skybox
+         */
         @serialize()
         public infiniteDistance = false;
 
@@ -174,7 +199,8 @@ module BABYLON {
 
         /**
          * Copies the parameter passed Matrix into the mesh Pose matrix.  
-         * Returns the TransformNode.  
+         * @param matrix the matrix to copy the pose from
+         * @returns this TransformNode.  
          */
         public updatePoseMatrix(matrix: Matrix): TransformNode {
             this._poseMatrix.copyFrom(matrix);
@@ -183,7 +209,7 @@ module BABYLON {
 
         /**
          * Returns the mesh Pose matrix.  
-         * Returned object : Matrix
+         * @returns the pose matrix
          */
         public getPoseMatrix(): Matrix {
             return this._poseMatrix;
@@ -235,6 +261,11 @@ module BABYLON {
             this._cache.billboardMode = -1;
         }
 
+         /**
+         * Flag the transform node as dirty (Forcing it to update everything)
+         * @param property if set to "rotation" the objects rotationQuaternion will be set to null
+         * @returns this transform node
+         */
         public markAsDirty(property: string): TransformNode {
             if (property === "rotation") {
                 this.rotationQuaternion = null;
@@ -286,7 +317,7 @@ module BABYLON {
         /**
          * Returns the mesh pivot matrix.
          * Default : Identity.  
-         * A Matrix is returned.  
+         * @returns the matrix  
          */
         public getPivotMatrix(): Matrix {
             return this._pivotMatrix;
@@ -294,7 +325,7 @@ module BABYLON {
 
         /**
          * Prevents the World matrix to be computed any longer.
-         * Returns the TransformNode.  
+         * @returns the TransformNode.  
          */
         public freezeWorldMatrix(): TransformNode {
             this._isWorldMatrixFrozen = false;  // no guarantee world is not already frozen, switch off temporarily
@@ -305,7 +336,7 @@ module BABYLON {
 
         /**
          * Allows back the World matrix computation. 
-         * Returns the TransformNode.  
+         * @returns the TransformNode.  
          */
         public unfreezeWorldMatrix() {
             this._isWorldMatrixFrozen = false;
@@ -315,16 +346,15 @@ module BABYLON {
 
         /**
          * True if the World matrix has been frozen.  
-         * Returns a boolean.  
          */
         public get isWorldMatrixFrozen(): boolean {
             return this._isWorldMatrixFrozen;
         }
 
         /**
-            * Retuns the mesh absolute position in the World.  
-            * Returns a Vector3.
-            */
+        * Retuns the mesh absolute position in the World.  
+        * @returns a Vector3.
+        */
         public getAbsolutePosition(): Vector3 {
             this.computeWorldMatrix();
             return this._absolutePosition;
@@ -332,7 +362,8 @@ module BABYLON {
 
         /**
          * Sets the mesh absolute position in the World from a Vector3 or an Array(3).
-         * Returns the TransformNode.  
+         * @param absolutePosition the absolute position to set
+         * @returns the TransformNode.  
          */
         public setAbsolutePosition(absolutePosition: Vector3): TransformNode {
             if (!absolutePosition) {
@@ -368,9 +399,10 @@ module BABYLON {
         }
 
         /**
-           * Sets the mesh position in its local space.  
-           * Returns the TransformNode.  
-           */
+         * Sets the mesh position in its local space.  
+         * @param vector3 the position to set in localspace
+         * @returns the TransformNode.  
+         */
         public setPositionWithLocalVector(vector3: Vector3): TransformNode {
             this.computeWorldMatrix();
             this.position = Vector3.TransformNormal(vector3, this._localWorld);
@@ -379,7 +411,7 @@ module BABYLON {
 
         /**
          * Returns the mesh position in the local space from the current World matrix values.
-         * Returns a new Vector3.
+         * @returns a new Vector3.
          */
         public getPositionExpressedInLocalSpace(): Vector3 {
             this.computeWorldMatrix();
@@ -391,7 +423,8 @@ module BABYLON {
 
         /**
          * Translates the mesh along the passed Vector3 in its local space.  
-         * Returns the TransformNode. 
+         * @param vector3 the distance to translate in localspace
+         * @returns the TransformNode. 
          */
         public locallyTranslate(vector3: Vector3): TransformNode {
             this.computeWorldMatrix(true);
@@ -429,8 +462,10 @@ module BABYLON {
         }
 
         /**
-          * Returns a new Vector3 what is the localAxis, expressed in the mesh local space, rotated like the mesh.  
+          * Returns a new Vector3 that is the localAxis, expressed in the mesh local space, rotated like the mesh.  
           * This Vector3 is expressed in the World space.  
+          * @param localAxis axis to rotate
+          * @returns a new Vector3 that is the localAxis, expressed in the mesh local space, rotated like the mesh. 
           */
         public getDirection(localAxis: Vector3): Vector3 {
             var result = Vector3.Zero();
@@ -444,7 +479,9 @@ module BABYLON {
          * 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 TransformNode.  
+         * @param localAxis axis to rotate
+         * @param result the resulting transformnode
+         * @returns this TransformNode.  
          */
         public getDirectionToRef(localAxis: Vector3, result: Vector3): TransformNode {
             Vector3.TransformNormalToRef(localAxis, this.getWorldMatrix(), result);
@@ -475,6 +512,7 @@ module BABYLON {
 
         /**
          * Returns a new Vector3 set with the mesh pivot point coordinates in the local space.  
+         * @returns the pivot point
          */
         public getPivotPoint(): Vector3 {
             var point = Vector3.Zero();
@@ -484,7 +522,8 @@ module BABYLON {
 
         /**
          * Sets the passed Vector3 "result" with the coordinates of the mesh pivot point in the local space.   
-         * Returns the TransformNode.   
+         * @param result the vector3 to store the result
+         * @returns this TransformNode.   
          */
         public getPivotPointToRef(result: Vector3): TransformNode {
             result.x = -this._pivotMatrix.m[12];
@@ -495,6 +534,7 @@ module BABYLON {
 
         /**
          * Returns a new Vector3 set with the mesh pivot point World coordinates.  
+         * @returns a new Vector3 set with the mesh pivot point World coordinates.  
          */
         public getAbsolutePivotPoint(): Vector3 {
             var point = Vector3.Zero();
@@ -504,7 +544,8 @@ module BABYLON {
 
         /**
          * Sets the Vector3 "result" coordinates with the mesh pivot point World coordinates.  
-         * Returns the TransformNode.  
+         * @param result vector3 to store the result
+         * @returns this TransformNode.  
          */
         public getAbsolutePivotPointToRef(result: Vector3): TransformNode {
             result.x = this._pivotMatrix.m[12];
@@ -518,7 +559,8 @@ module BABYLON {
         /**
          * Defines the passed node as the parent of the current node.  
          * The node will remain exactly where it is and its position / rotation will be updated accordingly
-         * Returns the TransformNode.
+         * @param node the node ot set as the parent
+         * @returns this TransformNode.
          */
         public setParent(node: Nullable<Node>): TransformNode {
             if (!node && !this.parent) {
@@ -582,6 +624,9 @@ module BABYLON {
         }
 
         private _nonUniformScaling = false;
+        /**
+         * True if the scaling property of this object is non uniform eg. (1,2,1)
+         */
         public get nonUniformScaling(): boolean {
             return this._nonUniformScaling;
         }
@@ -600,6 +645,7 @@ module BABYLON {
          * Attach the current TransformNode to another TransformNode associated with a bone
          * @param bone Bone affecting the TransformNode
          * @param affectedTransformNode TransformNode associated with the bone 
+         * @returns this object
          */
         public attachToBone(bone: Bone, affectedTransformNode: TransformNode): TransformNode {
             this._transformToBoneReferal = affectedTransformNode;
@@ -611,6 +657,10 @@ module BABYLON {
             return this;
         }
 
+        /**
+         * Detach the transform node if its associated with a bone
+         * @returns this object
+         */
         public detachFromBone(): TransformNode {
             if (!this.parent) {
                 return this;
@@ -629,8 +679,11 @@ module BABYLON {
          * 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.
          * 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 TransformNode.
+         * The passed axis is also normalized. 
+         * @param axis the axis to rotate around
+         * @param amount the amount to rotate in radians
+         * @param space Space to rotate in (Default: local)
+         * @returns the TransformNode.
          */
         public rotate(axis: Vector3, amount: number, space?: Space): TransformNode {
             axis.normalize();
@@ -658,9 +711,12 @@ module BABYLON {
         /**
          * Rotates the mesh around the axis vector for the passed angle (amount) expressed in radians, in world space.  
          * 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 TransformNode.
+         * The passed axis is also normalized. .
          * Method is based on http://www.euclideanspace.com/maths/geometry/affine/aroundPoint/index.htm
+         * @param point the point to rotate around
+         * @param axis the axis to rotate around
+         * @param amount the amount to rotate in radians
+         * @returns the TransformNode
          */
         public rotateAround(point: Vector3, axis: Vector3, amount: number): TransformNode {
             axis.normalize();
@@ -686,7 +742,10 @@ module BABYLON {
         /**
          * 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.
-         * Returns the TransformNode.
+         * @param axis the axis to translate in
+         * @param distance the distance to translate
+         * @param space Space to rotate in (Default: local)
+         * @returns the TransformNode.
          */
         public translate(axis: Vector3, distance: number, space?: Space): TransformNode {
             var displacementVector = axis.scale(distance);
@@ -712,7 +771,10 @@ module BABYLON {
          * ```
          * 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.   
-         * Returns the TransformNode.  
+         * @param x Rotation to add
+         * @param y Rotation to add
+         * @param z Rotation to add
+         * @returns the TransformNode.  
          */
         public addRotation(x: number, y: number, z: number): TransformNode {
             var rotationQuaternion;
@@ -914,9 +976,9 @@ module BABYLON {
 
         /**
         * If you'd like to be called back after the mesh position, rotation or scaling has been updated.  
-        * @param func: callback function to add
+        * @param func callback function to add
         *
-        * Returns the TransformNode. 
+        * @returns the TransformNode. 
         */
         public registerAfterWorldMatrixUpdate(func: (mesh: TransformNode) => void): TransformNode {
             this.onAfterWorldMatrixUpdateObservable.add(func);
@@ -925,7 +987,8 @@ module BABYLON {
 
         /**
          * Removes a registered callback function.  
-         * Returns the TransformNode.
+         * @param func callback function to remove
+         * @returns the TransformNode.
          */
         public unregisterAfterWorldMatrixUpdate(func: (mesh: TransformNode) => void): TransformNode {
             this.onAfterWorldMatrixUpdateObservable.removeCallback(func);
@@ -934,10 +997,10 @@ module BABYLON {
 
         /**
          * Clone the current transform node
-         * Returns the new transform node
          * @param name Name of the new clone
          * @param newParent New parent for the clone
          * @param doNotCloneChildren Do not clone children hierarchy
+         * @returns the new transform node
          */
         public clone(name: string, newParent: Node, doNotCloneChildren?: boolean): Nullable<TransformNode> {
             var result = SerializationHelper.Clone(() => new TransformNode(name, this.getScene()), this);
@@ -964,6 +1027,11 @@ module BABYLON {
             return result;
         }
 
+        /**
+         * Serializes the objects information.
+         * @param currentSerializationObject defines the object to serialize in
+         * @returns the serialized object
+         */
         public serialize(currentSerializationObject?: any): any {
             let serializationObject = SerializationHelper.Serialize(this, currentSerializationObject);
             serializationObject.type = this.getClassName();
@@ -992,8 +1060,10 @@ module BABYLON {
         // Statics
         /**
          * Returns a new TransformNode object parsed from the source provided.   
-         * The parameter `parsedMesh` is the source.   
-         * The parameter `rootUrl` is a string, it's the root URL to prefix the `delayLoadingFile` property with
+         * @param parsedTransformNode is the source.  
+         * @param scene the scne the object belongs to 
+         * @param rootUrl is a string, it's the root URL to prefix the `delayLoadingFile` property with
+         * @returns a new TransformNode object parsed from the source provided.   
          */
         public static Parse(parsedTransformNode: any, scene: Scene, rootUrl: string): TransformNode {
             var transformNode = SerializationHelper.Parse(() => new TransformNode(parsedTransformNode.name, scene), parsedTransformNode, scene, rootUrl);