More camera doc

src/Cameras/babylon.freeCamera.ts

@@ -4,22 +4,45 @@
         return () => new UniversalCamera(name, Vector3.Zero(), scene);
     });
 
+    /**
+     * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+     * Please consider using the new UniversalCamera instead as it adds more functionality like the gamepad.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class FreeCamera extends TargetCamera {
+        /**
+         * Define the collision ellipsoid of the camera.
+         * This is helpful to simulate a camera body like the player body around the camera
+         * @see http://doc.babylonjs.com/babylon101/cameras,_mesh_collisions_and_gravity#arcrotatecamera
+         */
         @serializeAsVector3()
         public ellipsoid = new Vector3(0.5, 1, 0.5);
 
+        /**
+         * Define an offset for the position of the ellipsoid around the camera.
+         * This can be helpful to determine the center of the body near the gravity center of the body 
+         * instead of its head.
+         */
         @serializeAsVector3()
         public ellipsoidOffset = new Vector3(0, 0, 0);
 
+        /**
+         * Enable or disable collisions of the camera with the rest of the scene objects.
+         */
         @serialize()
         public checkCollisions = false;
 
+        /**
+         * Enable or disable gravity on the camera.
+         */
         @serialize()
         public applyGravity = false;
 
+        /**
+         * Define the input manager associated to the camera.
+         */
         public inputs: FreeCameraInputsManager;
 
-        //-- begin properties for backward compatibility for inputs
         /**
          * Gets the input sensibility for a mouse input. (default is 2000.0)
          * Higher values reduce sensitivity.
@@ -42,6 +65,9 @@
                 mouse.angularSensibility = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the forward move of the camera.
+         */
         public get keysUp(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -56,6 +82,9 @@
                 keyboard.keysUp = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the backward move of the camera.
+         */
         public get keysDown(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -70,6 +99,9 @@
                 keyboard.keysDown = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the left strafe move of the camera.
+         */
         public get keysLeft(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -84,6 +116,9 @@
                 keyboard.keysLeft = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the right strafe move of the camera.
+         */
         public get keysRight(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -98,8 +133,9 @@
                 keyboard.keysRight = value;
         }
 
-        //-- end properties for backward compatibility for inputs
-
+        /**
+         * Event raised when the camera collide with a mesh in the scene.
+         */
         public onCollide: (collidedMesh: AbstractMesh) => void;
 
         private _collider: Collider;
@@ -113,17 +149,36 @@
         /** @hidden */
         public _transformedDirection: Vector3;
 
+        /**
+         * Instantiates a Free Camera.
+         * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+         * Please consider using the new UniversalCamera instead as it adds more functionality like touch to this camera.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         * @param setActiveOnSceneIfNoneActive Defines wheter the camera should be marked as active if not other active cameras have been defined
+         */
         constructor(name: string, position: Vector3, scene: Scene, setActiveOnSceneIfNoneActive = true) {
             super(name, position, scene, setActiveOnSceneIfNoneActive);
             this.inputs = new FreeCameraInputsManager(this);
             this.inputs.addKeyboard().addMouse();
         }
 
-        // Controls
+        /**
+         * Attached controls to the current camera.
+         * @param element Defines the element the controls should be listened from
+         * @param noPreventDefault Defines whether event caught by the controls should call preventdefault() (https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)
+         */
         public attachControl(element: HTMLElement, noPreventDefault?: boolean): void {
             this.inputs.attachElement(element, noPreventDefault);
         }
 
+        /**
+         * Detach the current controls from the camera.
+         * The camera will stop reacting to inputs.
+         * @param element Defines the element to stop listening the inputs from
+         */
         public detachControl(element: HTMLElement): void {
             this.inputs.detachElement(element);
 
@@ -134,6 +189,9 @@
         // Collisions
         private _collisionMask = -1;
 
+        /**
+         * Define a collision mask to limit the list of object the camera can collide with
+         */
         public get collisionMask(): number {
             return this._collisionMask;
         }
@@ -222,11 +280,18 @@
             }
         }
 
+        /**
+         * Destroy the camera and release the current resources hold by it.
+         */
         public dispose(): void {
             this.inputs.clear();
             super.dispose();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "FreeCamera";
         }

src/Cameras/babylon.freeCameraInputsManager.ts

@@ -1,29 +1,58 @@
 module BABYLON {
+    /**
+     * Default Inputs manager for the FreeCamera.
+     * It groups all the default supported inputs for ease of use.
+     * @see http://doc.babylonjs.com/how_to/customizing_camera_inputs
+     */
     export class FreeCameraInputsManager extends CameraInputsManager<FreeCamera> {
+        /**
+         * Instantiates a new FreeCameraInputsManager.
+         * @param camera Defines the camera the inputs belong to
+         */
         constructor(camera: FreeCamera) {
             super(camera);
         }
 
+        /**
+         * Add keyboard input support to the input manager.
+         * @returns the current input manager
+         */
         addKeyboard(): FreeCameraInputsManager {
             this.add(new FreeCameraKeyboardMoveInput());
             return this;
         }
 
+        /**
+         * Add mouse input support to the input manager.
+         * @returns the current input manager
+         */
         addMouse(touchEnabled = true): FreeCameraInputsManager {
             this.add(new FreeCameraMouseInput(touchEnabled));
             return this;
         }
 
+        /**
+         * Add orientation input support to the input manager.
+         * @returns the current input manager
+         */
         addDeviceOrientation(): FreeCameraInputsManager {
             this.add(new FreeCameraDeviceOrientationInput());
             return this;
         }
 
+        /**
+         * Add touch input support to the input manager.
+         * @returns the current input manager
+         */
         addTouch(): FreeCameraInputsManager {
             this.add(new FreeCameraTouchInput());
             return this;
         }
 
+        /**
+         * Add virtual joystick input support to the input manager.
+         * @returns the current input manager
+         */
         addVirtualJoystick(): FreeCameraInputsManager {
             this.add(new FreeCameraVirtualJoystickInput());
             return this;

src/Cameras/babylon.gamepadCamera.ts

@@ -3,43 +3,29 @@ module BABYLON {
         return () => new GamepadCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a FPS type of camera. This is only here for back compat purpose.
+     * Please use the UniversalCamera instead as both are identical.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class GamepadCamera extends UniversalCamera {
-        //-- Begin properties for backward compatibility for inputs
-        public get gamepadAngularSensibility(): number {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                return gamepad.gamepadAngularSensibility;
-
-            return 0;
-        }
-
-        public set gamepadAngularSensibility(value: number) {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                gamepad.gamepadAngularSensibility = value;
-        }
-
-        public get gamepadMoveSensibility(): number {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                return gamepad.gamepadMoveSensibility;
-
-            return 0;
-        }
-
-        public set gamepadMoveSensibility(value: number) {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                gamepad.gamepadMoveSensibility = value;
-        }
-        //-- end properties for backward compatibility for inputs
-
-
+        /**
+         * Instantiates a new Gamepad Camera
+         * This represents a FPS type of camera. This is only here for back compat purpose.
+         * Please use the UniversalCamera instead as both are identical.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "GamepadCamera";
         }

src/Cameras/babylon.targetCamera.ts

@@ -1,19 +1,46 @@
 module BABYLON {
+    /**
+     * A target camera takes a mesh or position as a target and continues to look at it while it moves. 
+     * This is the base of the follow, arc rotate cameras and Free camera
+     * @see http://doc.babylonjs.com/features/cameras
+     */
     export class TargetCamera extends Camera {
 
+        /**
+         * Define the current direction the camera is moving to
+         */
         public cameraDirection = new Vector3(0, 0, 0);
+        /**
+         * Define the current rotation the camera is rotating to
+         */
         public cameraRotation = new Vector2(0, 0);
 
+        /**
+         * Define the current rotation of the camera
+         */
         @serializeAsVector3()
         public rotation = new Vector3(0, 0, 0);
 
+        /**
+         * Define the current rotation of the camera as a quaternion to prevent Gimbal lock
+         */
         public rotationQuaternion: Quaternion;
 
+        /**
+         * Define the current speed of the camera
+         */
         @serialize()
         public speed = 2.0;
 
+        /**
+         * Add cconstraint to the camera to prevent it to move freely in all directions and
+         * around all axis.
+         */
         public noRotationConstraint = false;
 
+        /**
+         * Define the current target of the camera as an object or a position.
+         */
         @serializeAsMeshReference("lockedTargetId")
         public lockedTarget: any = null;
 
@@ -42,10 +69,24 @@
 
         private _defaultUp = BABYLON.Vector3.Up();
 
+        /**
+         * Instantiates a target camera that takes a meshor position as a target and continues to look at it while it moves. 
+         * This is the base of the follow, arc rotate cameras and Free camera
+         * @see http://doc.babylonjs.com/features/cameras
+         * @param name Defines the name of the camera in the scene
+         * @param position Defines the start position of the camera in the scene
+         * @param scene Defines the scene the camera belongs to
+         * @param setActiveOnSceneIfNoneActive Defines wheter the camera should be marked as active if not other active cameras have been defined
+         */
         constructor(name: string, position: Vector3, scene: Scene, setActiveOnSceneIfNoneActive = true) {
             super(name, position, scene, setActiveOnSceneIfNoneActive);
         }
 
+        /**
+         * Gets the position in front of the camera at a given distance.
+         * @param distance The distance from the camera we want the position to be
+         * @returns the position
+         */
         public getFrontPosition(distance: number): Vector3 {
             this.getWorldMatrix();
             var direction = this.getTarget().subtract(this.position);
@@ -67,15 +108,14 @@
             return this.lockedTarget.absolutePosition || this.lockedTarget;
         }
 
-        // State
-
-        /**
-         * Store current camera state (fov, position, etc..)
-         */
         private _storedPosition: Vector3;
         private _storedRotation: Vector3;
         private _storedRotationQuaternion: Quaternion;
 
+        /**
+         * Store current camera state of the camera (fov, position, rotation, etc..)
+         * @returns the camera
+         */
         public storeState(): Camera {
             this._storedPosition = this.position.clone();
             this._storedRotation = this.rotation.clone();
@@ -109,7 +149,6 @@
             return true;
         }
 
-        // Cache
         /** @hidden */
         public _initCache() {
             super._initCache();
@@ -206,6 +245,7 @@
 
         /**
          * Return the current target position of the camera. This value is expressed in local space.
+         * @returns the target position
          */
         public getTarget(): Vector3 {
             return this._currentTarget;
@@ -355,8 +395,7 @@
         }
 
         /**
-         * @override
-         * Override Camera.createRigCamera
+         * @hidden
          */
         public createRigCamera(name: string, cameraIndex: number): Nullable<Camera> {
             if (this.cameraRigMode !== Camera.RIG_MODE_NONE) {
@@ -375,8 +414,6 @@
 
         /**
          * @hidden
-         * @override
-         * Override Camera._updateRigCameras
          */
         public _updateRigCameras() {
             var camLeft = <TargetCamera>this._rigCameras[0];
@@ -425,6 +462,10 @@
             Vector3.TransformCoordinatesToRef(this.position, this._rigCamTransformMatrix, result);
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "TargetCamera";
         }

src/Cameras/babylon.touchCamera.ts

@@ -3,9 +3,16 @@ module BABYLON {
         return () => new TouchCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a FPS type of camera controlled by touch.
+     * This is like a universal camera minus the Gamepad controls.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class TouchCamera extends FreeCamera {
-        //-- Begin properties for backward compatibility for inputs
+        /**
+         * Defines the touch sensibility for rotation.
+         * The higher the faster.
+         */
         public get touchAngularSensibility(): number {
             var touch = <FreeCameraTouchInput>this.inputs.attached["touch"];
             if (touch)
@@ -20,6 +27,10 @@ module BABYLON {
                 touch.touchAngularSensibility = value;
         }
 
+        /**
+         * Defines the touch sensibility for move.
+         * The higher the faster.
+         */
         public get touchMoveSensibility(): number {
             var touch = <FreeCameraTouchInput>this.inputs.attached["touch"];
             if (touch)
@@ -33,8 +44,16 @@ module BABYLON {
             if (touch)
                 touch.touchMoveSensibility = value;
         }
-        //-- end properties for backward compatibility for inputs
-
+        
+        /**
+         * Instantiates a new touch camera.
+         * This represents a FPS type of camera controlled by touch.
+         * This is like a universal camera minus the Gamepad controls.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addTouch();
@@ -42,6 +61,10 @@ module BABYLON {
             this._setupInputs();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "TouchCamera";
         }

src/Cameras/babylon.universalCamera.ts

@@ -1,7 +1,14 @@
 module BABYLON {
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * The Universal Camera is the one to choose for first person shooter type games, and works with all the keyboard, mouse, touch and gamepads. This replaces the earlier Free Camera, 
+     * which still works and will still be found in many Playgrounds.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class UniversalCamera extends TouchCamera {
-        //-- Begin properties for backward compatibility for inputs
+        /**
+         * Defines the gamepad rotation sensiblity.
+         * This is the threshold from when rotation starts to be accounted for to prevent jittering.
+         */
         public get gamepadAngularSensibility(): number {
             var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
             if (gamepad)
@@ -16,6 +23,10 @@ module BABYLON {
                 gamepad.gamepadAngularSensibility = value;
         }
 
+        /**
+         * Defines the gamepad move sensiblity.
+         * This is the threshold from when moving starts to be accounted for for to prevent jittering.
+         */
         public get gamepadMoveSensibility(): number {
             var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
             if (gamepad)
@@ -29,13 +40,24 @@ module BABYLON {
             if (gamepad)
                 gamepad.gamepadMoveSensibility = value;
         }
-        //-- end properties for backward compatibility for inputs
 
+        /**
+         * The Universal Camera is the one to choose for first person shooter type games, and works with all the keyboard, mouse, touch and gamepads. This replaces the earlier Free Camera, 
+         * which still works and will still be found in many Playgrounds.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addGamepad();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "UniversalCamera";
         }

src/Cameras/babylon.virtualJoysticksCamera.ts

@@ -3,14 +3,32 @@
         return () => new VirtualJoysticksCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+     * It is identical to the Free Camera and simply adds by default a virtual joystick.
+     * Virtual Joysticks are on-screen 2D graphics that are used to control the camera or other scene items.
+     * @see http://doc.babylonjs.com/features/cameras#virtual-joysticks-camera
+     */
     export class VirtualJoysticksCamera extends FreeCamera {
         
+        /**
+         * Intantiates a VirtualJoysticksCamera. It can be usefull in First Person Shooter game for instance.
+         * It is identical to the Free Camera and simply adds by default a virtual joystick.
+         * Virtual Joysticks are on-screen 2D graphics that are used to control the camera or other scene items.
+         * @see http://doc.babylonjs.com/features/cameras#virtual-joysticks-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addVirtualJoystick();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "VirtualJoysticksCamera";
         }