Main   Class List   Namespace List   Wiki

Camera Class Reference
[Base Camera]

Represents a position, direction and field of view to render a scene from. More...

Inheritance diagram for Camera:
Inheritance graph
[legend]

List of all members.

Public Member Functions

void autoFitRadius (float radius)
 Move the camera to fully view the given radius.
VectorF getAngularVelocity ()
 Get the angular velocity for a Newton mode camera.
Camera::CameraMotionMode getMode ()
 Returns the current camera control mode.
Point3F getOffset ()
 Get the camera's offset from its orbit or tracking point.
Point3F getPosition ()
 Get the camera's position in the world.
Point3F getRotation ()
 Get the camera's Euler rotation in radians.
VectorF getVelocity ()
 Get the velocity for the camera.
bool isEditOrbitMode ()
 Is the camera in edit orbit mode?
bool isRotationDamped ()
 Is this a Newton Fly mode camera with damped rotation?
void lookAt (Point3F point)
 Point the camera at the specified position. Does not work in Orbit or Track modes.
void setAngularDrag (float drag)
 Set the angular drag for a Newton mode camera.
void setAngularForce (float force)
 Set the angular force for a Newton mode camera.
void setAngularVelocity (VectorF velocity)
 Set the angular velocity for a Newton mode camera.
void setBrakeMultiplier (float multiplier)
 Set the Newton mode camera brake multiplier when trigger[1] is active.
void setDrag (float drag)
 Set the drag for a Newton mode camera.
void setEditOrbitMode ()
 Set the editor camera to orbit around a point set with Camera::setEditOrbitPoint().
void setEditOrbitPoint (Point3F point)
 Set the editor camera's orbit point.
void setFlyForce (float force)
 Set the force applied to a Newton mode camera while moving.
void setFlyMode ()
 Set the camera to fly freely.
void setMass (float mass)
 Set the mass for a Newton mode camera.
void setNewtonFlyMode ()
 Set the camera to fly freely, but with ease-in and ease-out.
void setOffset (Point3F offset)
 Set the camera's offset.
void setOrbitMode (GameBase orbitObject, TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, bool ownClientObj=false, Point3F offset=Point3F(0.0f, 0.0f, 0.0f), bool locked=false)
 Set the camera to orbit around the given object, or if none is given, around the given point.
bool setOrbitObject (GameBase orbitObject, VectorF rotation, float minDistance, float maxDistance, float initDistance, bool ownClientObject=false, Point3F offset=Point3F(0.0f, 0.0f, 0.0f), bool locked=false)
 Set the camera to orbit around a given object.
void setOrbitPoint (TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, Point3F offset=Point3F(0.0f, 0.0f, 0.0f), bool locked=false)
 Set the camera to orbit around a given point.
void setRotation (Point3F rot)
 Set the camera's Euler rotation in radians.
void setSpeedMultiplier (float multiplier)
 Set the Newton mode camera speed multiplier when trigger[0] is active.
bool setTrackObject (GameBase trackObject, Point3F offset=Point3F(0.0f, 0.0f, 0.0f))
 Set the camera to track a given object.
void setValidEditOrbitPoint (bool validPoint)
 Set if there is a valid editor camera orbit point.
void setVelocity (VectorF velocity)
 Set the velocity for the camera.

Public Attributes

Camera: Newton Mode

float angularDrag
 Drag on camera when rotating (Newton mode only). Default value is 2.
float angularForce
 Force applied on camera when asked to rotate (Newton mode only). Default value is 100.
float brakeMultiplier
 Speed multiplier when triggering the brake (Newton mode only). Default value is 2.
float drag
 Drag on camera when moving (Newton mode only). Default value is 2.
float force
 Force applied on camera when asked to move (Newton mode only). Default value is 500.
float mass
 The camera's mass (Newton mode only). Default value is 10.
bool newtonMode
 Apply smoothing (acceleration and damping) to camera movements.
bool newtonRotation
 Apply smoothing (acceleration and damping) to camera rotations.
float speedMultiplier
 Speed multiplier when triggering the accelerator (Newton mode only). Default value is 2.
Camera

CameraMotionMode controlMode
 The current camera control mode.

Static Public Attributes

static bool isRenderable
 Disables rendering of all instances of this type.
static bool isSelectable
 Disables selection of all instances of this type.
static float movementSpeed
 Global camera movement speed in units/s (typically m/s), with a base value of 40.

Detailed Description

Represents a position, direction and field of view to render a scene from.

A camera is typically manipulated by a GameConnection. When set as the connection's control object, the camera handles all movement actions ($mvForwardAction, $mvPitch, etc.) just like a Player.

Example:
// Set an already created camera as the GameConnection's control object
%connection.setControlObject(%camera);

Methods of Operation

The camera has two general methods of operation. The first is the standard mode where the camera starts and stops its motion and rotation instantly. This is the default operation of the camera and is used by most games. It may be specifically set with Camera::setFlyMode() for 6 DoF motion. It is also typically the method used with Camera::setOrbitMode() or one of its helper methods to orbit about a specific object (such as the Player's dead body) or a specific point.

The second method goes under the name of Newton as it follows Newton's 2nd law of motion: F=ma. This provides the camera with an ease-in and ease-out feel for both movement and rotation. To activate this method for movement, either use Camera::setNewtonFlyMode() or set the Camera::newtonMode field to true. To activate this method for rotation, set the Camera::newtonRotation to true. This method of operation is not typically used in games, and was developed to allow for a smooth fly through of a game level while recording a demo video. But with the right force and drag settings, it may give a more organic feel to the camera to games that use an overhead view, such as a RTS.

There is a third, minor method of operation but it is not generally used for games. This is when the camera is used with Torque's World Editor in Edit Orbit Mode. When set, this allows the camera to rotate about a specific point in the world, and move towards and away from this point. See Camera::setEditOrbitMode() and Camera::setEditOrbitPoint(). While in this mode, Camera::autoFitRadius() may also be used.

Example:
// Create a camera in the level and set its position to a given spawn point.
// Note: The camera starts in the standard fly mode.
%cam = new Camera() {
   datablock = "Observer";
};
MissionCleanup.add( %cam );
%cam.setTransform( %spawnPoint.getTransform() );
Example:
// Create a camera at the given spawn point for the specified
// GameConnection i.e. the client.  Uses the standard
// Sim::spawnObject() function to create the camera using the
// defined default settings.
// Note: The camera starts in the standard fly mode.
function GameConnection::spawnCamera(%this, %spawnPoint)
{
   // Set the control object to the default camera
   if (!isObject(%this.camera))
   {
      if (isDefined("$Game::DefaultCameraClass"))
         %this.camera = spawnObject($Game::DefaultCameraClass, $Game::DefaultCameraDataBlock);
   }

   // If we have a camera then set up some properties
   if (isObject(%this.camera))
   {
      // Make sure we're cleaned up when the mission ends
      MissionCleanup.add( %this.camera );

      // Make sure the camera is always in scope for the connection
      %this.camera.scopeToClient(%this);

      // Send all user input from the connection to the camera
      %this.setControlObject(%this.camera);

      if (isDefined("%spawnPoint"))
      {
         // Attempt to treat %spawnPoint as an object, such as a
         // SpawnSphere class.
         if (getWordCount(%spawnPoint) == 1 && isObject(%spawnPoint))
         {
            %this.camera.setTransform(%spawnPoint.getTransform());
         }
         else
         {
            // Treat %spawnPoint as an AngleAxis transform
            %this.camera.setTransform(%spawnPoint);
         }
      }
   }
}

Motion Modes

Beyond the different operation methods, the Camera may be set to one of a number of motion modes. These motion modes determine how the camera will respond to input and may be used to constrain how the Camera moves. The CameraMotionMode enumeration defines the possible set of modes and the Camera's current may be obtained by using getMode().

Some of the motion modes may be set using specific script methods. These often provide additional parameters to set up the mode in one go. Otherwise, it is always possible to set a Camera's motion mode using the controlMode property. Just pass in the name of the mode enum. The following table lists the motion modes, how to set them up, and what they offer:

ModeSet From ScriptInput MoveInput RotateCan Use Newton Mode?
StationarycontrolMode propertyNoNoNo
FreeRotatecontrolMode propertyNoYesRotate Only
FlysetFlyMode()YesYesYes
OrbitObjectsetOrbitMode()Orbits objectPoints to objectMove only
OrbitPointsetOrbitPoint()Orbits pointPoints to locationMove only
TrackObjectsetTrackObject()NoPoints to objectYes
OverheadcontrolMode propertyYesNoYes
EditOrbit (object selected)setEditOrbitMode()Orbits objectPoints to objectMove only
EditOrbit (no object)setEditOrbitMode()YesYesYes

Trigger Input

Passing a move trigger ($mvTriggerCount0, $mvTriggerCount1, etc.) on to a Camera performs different actions depending on which mode the camera is in. While in Fly, Overhead or EditOrbit mode, either trigger0 or trigger1 will cause a camera to move twice its normal movement speed. You can see this in action within the World Editor, where holding down the left mouse button while in mouse look mode (right mouse button is also down) causes the Camera to move faster.

Passing along trigger2 will put the camera into strafe mode. While in this mode a Fly, FreeRotate or Overhead Camera will not rotate from the move input. Instead the yaw motion will be applied to the Camera's x motion, and the pitch motion will be applied to the Camera's z motion. You can see this in action within the World Editor where holding down the middle mouse button allows the user to move the camera up, down and side-to-side.

While the camera is operating in Newton Mode, trigger0 and trigger1 behave slightly differently. Here trigger0 activates a multiplier to the applied acceleration force as defined by speedMultiplier. This has the affect of making the camera move up to speed faster. trigger1 has the opposite affect by acting as a brake. When trigger1 is active a multiplier is added to the Camera's drag as defined by brakeMultiplier.

See also:
CameraData
CameraMotionMode
Camera::movementSpeed

Member Function Documentation

void Camera::autoFitRadius ( float  radius  ) 

Move the camera to fully view the given radius.

Note:
For this operation to take affect a valid edit orbit point must first be specified. See Camera::setEditOrbitPoint().
Parameters:
radius The radius to view.
VectorF Camera::getAngularVelocity (  ) 

Get the angular velocity for a Newton mode camera.

Returns:
The angular velocity in the form of "x y z".
Note:
Only returns useful results when Camera::newtonRotation is set to true.
Camera::CameraMotionMode Camera::getMode (  ) 

Returns the current camera control mode.

See also:
CameraMotionMode
Point3F Camera::getOffset (  ) 

Get the camera's offset from its orbit or tracking point.

The offset is added to the camera's position when set to CameraMode::OrbitObject.

Returns:
The offset in the form of "x y z".
Point3F Camera::getPosition (  ) 

Get the camera's position in the world.

Returns:
The position in the form of "x y z".

Reimplemented from SceneObject.

Point3F Camera::getRotation (  ) 

Get the camera's Euler rotation in radians.

Returns:
The rotation in radians in the form of "x y z".
VectorF Camera::getVelocity (  ) 

Get the velocity for the camera.

Returns:
The camera's velocity in the form of "x y z".
Note:
Only useful when the Camera is in Newton mode.

Reimplemented from ShapeBase.

bool Camera::isEditOrbitMode (  ) 

Is the camera in edit orbit mode?

Returns:
true if the camera is in edit orbit mode.
bool Camera::isRotationDamped (  ) 

Is this a Newton Fly mode camera with damped rotation?

Returns:
true if the camera uses a damped rotation. i.e. Camera::newtonRotation is set to true.
void Camera::lookAt ( Point3F  point  ) 

Point the camera at the specified position. Does not work in Orbit or Track modes.

Parameters:
point The position to point the camera at.
void Camera::setAngularDrag ( float  drag  ) 

Set the angular drag for a Newton mode camera.

Parameters:
drag The angular drag applied while the camera is rotating.
Note:
Only takes affect when Camera::newtonRotation is set to true.
void Camera::setAngularForce ( float  force  ) 

Set the angular force for a Newton mode camera.

Parameters:
force The angular force applied when attempting to rotate the camera.
Note:
Only takes affect when Camera::newtonRotation is set to true.
void Camera::setAngularVelocity ( VectorF  velocity  ) 

Set the angular velocity for a Newton mode camera.

Parameters:
velocity The angular velocity infor form of "x y z".
Note:
Only takes affect when Camera::newtonRotation is set to true.
void Camera::setBrakeMultiplier ( float  multiplier  ) 

Set the Newton mode camera brake multiplier when trigger[1] is active.

Parameters:
multiplier The brake multiplier to apply.
Note:
Only used when Camera is in Newton mode.
void Camera::setDrag ( float  drag  ) 

Set the drag for a Newton mode camera.

Parameters:
drag The drag applied to the camera while moving.
Note:
Only used when Camera is in Newton mode.
void Camera::setEditOrbitMode (  ) 

Set the editor camera to orbit around a point set with Camera::setEditOrbitPoint().

Note:
This method is generally used only within the World Editor and other tools. To orbit about an object or point within a game, see Camera::setOrbitMode() and its helper methods.
void Camera::setEditOrbitPoint ( Point3F  point  ) 

Set the editor camera's orbit point.

Parameters:
point The point the camera will orbit in the form of "x y z".
void Camera::setFlyForce ( float  force  ) 

Set the force applied to a Newton mode camera while moving.

Parameters:
force The force applied to the camera while attempting to move.
Note:
Only used when Camera is in Newton mode.
void Camera::setFlyMode (  ) 

Set the camera to fly freely.

Allows the camera to have 6 degrees of freedom. Provides for instantaneous motion and rotation unless one of the Newton fields has been set to true. See Camera::newtonMode and Camera::newtonRotation.

void Camera::setMass ( float  mass  ) 

Set the mass for a Newton mode camera.

Parameters:
mass The mass used during ease-in and ease-out calculations.
Note:
Only used when Camera is in Newton mode.
void Camera::setNewtonFlyMode (  ) 

Set the camera to fly freely, but with ease-in and ease-out.

This method allows for the same 6 degrees of freedom as Camera::setFlyMode() but activates the ease-in and ease-out on the camera's movement. To also activate Newton mode for the camera's rotation, set Camera::newtonRotation to true.

void Camera::setOffset ( Point3F  offset  ) 

Set the camera's offset.

The offset is added to the camera's position when set to CameraMode::OrbitObject.

Parameters:
offset The distance to offset the camera by in the form of "x y z".
void Camera::setOrbitMode ( GameBase  orbitObject,
TransformF  orbitPoint,
float  minDistance,
float  maxDistance,
float  initDistance,
bool  ownClientObj = false,
Point3F  offset = Point3F(0.0f, 0.0f, 0.0f),
bool  locked = false 
)

Set the camera to orbit around the given object, or if none is given, around the given point.

Parameters:
orbitObject The object to orbit around. If no object is given (0 or blank string is passed in) use the orbitPoint instead
orbitPoint The point to orbit around when no object is given. In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform().
minDistance The minimum distance allowed to the orbit object or point.
maxDistance The maximum distance allowed from the orbit object or point.
initDistance The initial distance from the orbit object or point.
ownClientObj [optional] Are we orbiting an object that is owned by us? Default is false.
offset [optional] An offset added to the camera's position. Default is no offset.
locked [optional] Indicates the camera does not receive input from the player. Default is false.
See also:
Camera::setOrbitObject()
Camera::setOrbitPoint()
bool Camera::setOrbitObject ( GameBase  orbitObject,
VectorF  rotation,
float  minDistance,
float  maxDistance,
float  initDistance,
bool  ownClientObject = false,
Point3F  offset = Point3F(0.0f, 0.0f, 0.0f),
bool  locked = false 
)

Set the camera to orbit around a given object.

Parameters:
orbitObject The object to orbit around.
rotation The initial camera rotation about the object in radians in the form of "x y z".
minDistance The minimum distance allowed to the orbit object or point.
maxDistance The maximum distance allowed from the orbit object or point.
initDistance The initial distance from the orbit object or point.
ownClientObject [optional] Are we orbiting an object that is owned by us? Default is false.
offset [optional] An offset added to the camera's position. Default is no offset.
locked [optional] Indicates the camera does not receive input from the player. Default is false.
Returns:
false if the given object could not be found.
See also:
Camera::setOrbitMode()
void Camera::setOrbitPoint ( TransformF  orbitPoint,
float  minDistance,
float  maxDistance,
float  initDistance,
Point3F  offset = Point3F(0.0f, 0.0f, 0.0f),
bool  locked = false 
)

Set the camera to orbit around a given point.

Parameters:
orbitPoint The point to orbit around. In the form of "x y z ax ay az aa" such as returned by SceneObject::getTransform().
minDistance The minimum distance allowed to the orbit object or point.
maxDistance The maximum distance allowed from the orbit object or point.
initDistance The initial distance from the orbit object or point.
offset [optional] An offset added to the camera's position. Default is no offset.
locked [optional] Indicates the camera does not receive input from the player. Default is false.
See also:
Camera::setOrbitMode()
void Camera::setRotation ( Point3F  rot  ) 

Set the camera's Euler rotation in radians.

Parameters:
rot The rotation in radians in the form of "x y z".
Note:
Rotation around the Y axis is ignored
void Camera::setSpeedMultiplier ( float  multiplier  ) 

Set the Newton mode camera speed multiplier when trigger[0] is active.

Parameters:
multiplier The speed multiplier to apply.
Note:
Only used when Camera is in Newton mode.
bool Camera::setTrackObject ( GameBase  trackObject,
Point3F  offset = Point3F(0.0f, 0.0f, 0.0f) 
)

Set the camera to track a given object.

Parameters:
trackObject The object to track.
offset [optional] An offset added to the camera's position. Default is no offset.
Returns:
false if the given object could not be found.
void Camera::setValidEditOrbitPoint ( bool  validPoint  ) 

Set if there is a valid editor camera orbit point.

When validPoint is set to false the Camera operates as if it is in Fly mode rather than an Orbit mode.

Parameters:
validPoint Indicates the validity of the orbit point.
Note:
Only used when Camera is in Edit Orbit Mode.
void Camera::setVelocity ( VectorF  velocity  ) 

Set the velocity for the camera.

Parameters:
velocity The camera's velocity in the form of "x y z".
Note:
Only affects the Camera when in Newton mode.

Member Data Documentation

Drag on camera when rotating (Newton mode only). Default value is 2.

Force applied on camera when asked to rotate (Newton mode only). Default value is 100.

Speed multiplier when triggering the brake (Newton mode only). Default value is 2.

The current camera control mode.

float Camera::drag

Drag on camera when moving (Newton mode only). Default value is 2.

Force applied on camera when asked to move (Newton mode only). Default value is 500.

bool Camera::isRenderable [static]

Disables rendering of all instances of this type.

Reimplemented from ShapeBase.

bool Camera::isSelectable [static]

Disables selection of all instances of this type.

Reimplemented from ShapeBase.

float Camera::mass

The camera's mass (Newton mode only). Default value is 10.

Apply smoothing (acceleration and damping) to camera movements.

Apply smoothing (acceleration and damping) to camera rotations.

Speed multiplier when triggering the accelerator (Newton mode only). Default value is 2.



Copyright © GarageGames, LLC. All Rights Reserved.