Update ShadowLight Documentation

src/Lights/babylon.directionalLight.ts

@@ -43,11 +43,11 @@
             this.forceProjectionMatrixCompute();
         }
 
-        @serialize()
         /**
-         * Automatically compute the projection matrix to best fit (including all the caster and receivers)
+         * Automatically compute the projection matrix to best fit (including all the casters)
          * on each frame.
          */
+        @serialize()
         public autoUpdateExtends = true;
 
         // Cache

src/Lights/babylon.shadowLight.ts

@@ -1,87 +1,198 @@
 module BABYLON {
+    /**
+     * Interface describing all the common properties and methods a shadow light needs to implement.
+     * This helps both the shadow generator and materials to genrate the corresponding shadow maps
+     * as well as binding the different shadow properties to the effects.
+     */
     export interface IShadowLight extends Light {
+        /**
+         * The light id in the scene (used in scene.findLighById for instance)
+         */
         id: string;
+        /**
+         * The position the shdow will be casted from.
+         */
         position: Vector3;
+        /**
+         * In 2d mode (needCube being false), the direction used to cast the shadow.
+         */
         direction: Vector3;
+        /**
+         * The transformed position. Position of the light in world space taking parenting in account.
+         */
         transformedPosition: Vector3;
+        /**
+         * The transformed direction. Direction of the light in world space taking parenting in account.
+         */
         transformedDirection: Vector3;
+        /**
+         * The friendly name of the light in the scene.
+         */
         name: string;
+        /**
+         * Defines the shadow projection clipping minimum z value.
+         */
         shadowMinZ: number;
+        /**
+         * Defines the shadow projection clipping maximum z value.
+         */
         shadowMaxZ: number;
 
+        /**
+         * Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
+         * @returns true if the information has been computed, false if it does not need to (no parenting)
+         */
         computeTransformedInformation(): boolean;
+
+        /**
+         * Gets the scene the light belongs to.
+         * @returns The scene
+         */
         getScene(): Scene;
 
+        /**
+         * Callback defining a custom Projection Matrix Builder.
+         * This can be used to override the default projection matrix computation.
+         */
         customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
+
+        /**
+         * Sets the shadow projection matrix in parameter to the generated projection matrix.
+         * @param matrix The materix to updated with the projection information
+         * @param viewMatrix The transform matrix of the light
+         * @param renderList The list of mesh to render in the map
+         * @returns The current light
+         */
         setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight;
+
+        /**
+         * Gets the current depth scale used in ESM.
+         * @returns The scale
+         */
         getDepthScale(): number;
 
+        /**
+         * Returns whether or not the shadow generation require a cube texture or a 2d texture.
+         * @returns true if a cube texture needs to be use
+         */
         needCube(): boolean;
+
+        /**
+         * Detects if the projection matrix requires to be recomputed this frame.
+         * @returns true if it requires to be recomputed otherwise, false.
+         */
         needProjectionMatrixCompute(): boolean;
+
+        /**
+         * Forces the shadow generator to recompute the projection matrix even if position and direction did not changed.
+         */
         forceProjectionMatrixCompute(): void;
 
+        /**
+         * Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
+         * @param faceIndex The index of the face we are computed the direction to generate shadow
+         * @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
+         */
         getShadowDirection(faceIndex?: number): Vector3;
 
         /**
          * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the min for
+         * @returns the depth min z
          */
         getDepthMinZ(activeCamera: Camera): number;
 
         /**
-         * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * Gets the maxZ used for shadow according to both the scene and the light.
+         * @param activeCamera The camera we are returning the max for
+         * @returns the depth max z
          */
         getDepthMaxZ(activeCamera: Camera): number;
     }
 
+    /**
+     * Base implementation of @see IShadowLight
+     * It groups all the common behaviour in order to reduce dupplication and better follow the DRY pattern.
+     */
     export abstract class ShadowLight extends Light implements IShadowLight {
 
         protected abstract _setDefaultShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): void;
 
+        /**
+         * The position the shdow will be casted from.
+         */
         @serializeAsVector3()
         public position: Vector3;
 
         protected _direction: Vector3;
         @serializeAsVector3()
+        /**
+         * In 2d mode (needCube being false), gets the direction used to cast the shadow.
+         */
         public get direction(): Vector3 {
             return this._direction;
         }
+        /**
+         * In 2d mode (needCube being false), sets the direction used to cast the shadow.
+         */
         public set direction(value: Vector3) {
             this._direction = value;
         }
 
         private _shadowMinZ: number;
+        /**
+         * Gets the shadow projection clipping minimum z value.
+         */
         @serialize()
         public get shadowMinZ(): number {
             return this._shadowMinZ
         }
+        /**
+         * Sets the shadow projection clipping minimum z value.
+         */
         public set shadowMinZ(value: number) {
             this._shadowMinZ = value;
             this.forceProjectionMatrixCompute();
         }
 
         private _shadowMaxZ: number;
+        /**
+         * Sets the shadow projection clipping maximum z value.
+         */
         @serialize()
         public get shadowMaxZ(): number {
             return this._shadowMaxZ
         }
+        /**
+         * Gets the shadow projection clipping maximum z value.
+         */
         public set shadowMaxZ(value: number) {
             this._shadowMaxZ = value;
             this.forceProjectionMatrixCompute();
         }
 
+        /**
+         * Callback defining a custom Projection Matrix Builder.
+         * This can be used to override the default projection matrix computation.
+         */
         public customProjectionMatrixBuilder: (viewMatrix: Matrix, renderList: Array<AbstractMesh>, result: Matrix) => void;
 
+        /**
+         * The transformed position. Position of the light in world space taking parenting in account.
+         */
         public transformedPosition: Vector3;
 
+        /**
+         * The transformed direction. Direction of the light in world space taking parenting in account.
+         */
         public transformedDirection: Vector3;
 
         private _worldMatrix: Matrix;
         private _needProjectionMatrixCompute: boolean = true;
 
         /**
-         * Computes the light transformed position/direction in case the light is parented. Returns true if parented, else false.
+         * Computes the transformed information (transformedPosition and transformedDirection in World space) of the current light
+         * @returns true if the information has been computed, false if it does not need to (no parenting)
          */
         public computeTransformedInformation(): boolean {
             if (this.parent && this.parent.getWorldMatrix) {
@@ -104,13 +215,16 @@
 
         /**
          * Return the depth scale used for the shadow map.
+         * @returns the depth scale.
          */
         public getDepthScale(): number {
             return 50.0;
         }
 
         /**
-         * Returns the light direction (Vector3) for any passed face index.
+         * Get the direction to use to render the shadow map. In case of cube texture, the face index can be passed.
+         * @param faceIndex The index of the face we are computed the direction to generate shadow
+         * @returns The set direction in 2d mode otherwise the direction to the cubemap face if needCube() is true
          */
         public getShadowDirection(faceIndex?: number): Vector3 {
             return this.transformedDirection ? this.transformedDirection : this.direction;
@@ -118,14 +232,16 @@
 
         /**
          * Returns the ShadowLight absolute position in the World.
+         * @returns the position vector in world space
          */
         public getAbsolutePosition(): Vector3 {
             return this.transformedPosition ? this.transformedPosition : this.position;
         }
 
         /**
-         * Sets the ShadowLight direction toward the passed target (Vector3).
-         * Returns the updated ShadowLight direction (Vector3).
+         * Sets the ShadowLight direction toward the passed target.
+         * @param target The point tot target in local space
+         * @returns the updated ShadowLight direction
          */
         public setDirectionToTarget(target: Vector3): Vector3 {
             this.direction = Vector3.Normalize(target.subtract(this.position));
@@ -133,7 +249,8 @@
         }
 
         /**
-         * Returns the light rotation (Vector3).
+         * Returns the light rotation in euler definition.
+         * @returns the x y z rotation in local space.
          */
         public getRotation(): Vector3 {
             this.direction.normalize();
@@ -143,14 +260,16 @@
         }
 
         /**
-         * Boolean : false by default.
+         * Returns whether or not the shadow generation require a cube texture or a 2d texture.
+         * @returns true if a cube texture needs to be use
          */
         public needCube(): boolean {
             return false;
         }
 
         /**
-         * Specifies wether or not the projection matrix should be recomputed this frame.
+         * Detects if the projection matrix requires to be recomputed this frame.
+         * @returns true if it requires to be recomputed otherwise, false.
          */
         public needProjectionMatrixCompute(): boolean {
             return this._needProjectionMatrixCompute;
@@ -165,6 +284,7 @@
 
         /**
          * Get the world matrix of the sahdow lights.
+         * @ignore Internal Use Only
          */
         public _getWorldMatrix(): Matrix {
             if (!this._worldMatrix) {
@@ -178,7 +298,8 @@
 
         /**
          * Gets the minZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the min for
+         * @returns the depth min z
          */
         public getDepthMinZ(activeCamera: Camera): number {
             return this.shadowMinZ !== undefined ? this.shadowMinZ : activeCamera.minZ;
@@ -186,15 +307,19 @@
 
         /**
          * Gets the maxZ used for shadow according to both the scene and the light.
-         * @param activeCamera 
+         * @param activeCamera The camera we are returning the max for
+         * @returns the depth max z
          */
         public getDepthMaxZ(activeCamera: Camera): number {
             return this.shadowMaxZ !== undefined ? this.shadowMaxZ : activeCamera.maxZ;
         }
 
         /**
-         * Sets the projection matrix according to the type of light and custom projection matrix definition.
-         * Returns the light.
+         * Sets the shadow projection matrix in parameter to the generated projection matrix.
+         * @param matrix The materix to updated with the projection information
+         * @param viewMatrix The transform matrix of the light
+         * @param renderList The list of mesh to render in the map
+         * @returns The current light
          */
         public setShadowProjectionMatrix(matrix: Matrix, viewMatrix: Matrix, renderList: Array<AbstractMesh>): IShadowLight {
             if (this.customProjectionMatrixBuilder) {