Camera Class Reference
[Base Camera]

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

Inheritance diagram for Camera:

[legend]

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:

Mode	Set From Script	Input Move	Input Rotate	Can Use Newton Mode?
Stationary	controlMode property	No	No	No
FreeRotate	controlMode property	No	Yes	Rotate Only
Fly	setFlyMode()	Yes	Yes	Yes
OrbitObject	setOrbitMode()	Orbits object	Points to object	Move only
OrbitPoint	setOrbitPoint()	Orbits point	Points to location	Move only
TrackObject	setTrackObject()	No	Points to object	Yes
Overhead	controlMode property	Yes	No	Yes
EditOrbit (object selected)	setEditOrbitMode()	Orbits object	Points to object	Move only
EditOrbit (no object)	setEditOrbitMode()	Yes	Yes	Yes

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.