Camera

consoledoc.h

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

More...

CameraMotionMode

controlMode 

bool

newtonMode 

bool

newtonRotation 

float

mass 

float

drag 

float

force 

float

angularDrag 

float

angularForce 

float

speedMultiplier 

float

brakeMultiplier 

int

extendedMovePosRotIndex 

bool

isRenderable 

bool

isSelectable 

float

movementSpeed 

void

autoFitRadius(float radius)

VectorF

getAngularVelocity()

Camera::CameraMotionMode

getMode()

Point3F

getOffset()

Point3F

getPosition()

Point3F

getRotation()

VectorF

getVelocity()

bool

isEditOrbitMode()

bool

isRotationDamped()

void

lookAt(Point3F point)

void

setAngularDrag(float drag)

void

setAngularForce(float force)

void

setAngularVelocity(VectorF velocity)

void

setBrakeMultiplier(float multiplier)

void

setDrag(float drag)

void

setEditOrbitMode()

void

setEditOrbitPoint(Point3F point)

void

setFlyForce(float force)

void

setFlyMode()

void

setMass(float mass)

void

setNewtonFlyMode()

void

setOffset(Point3F offset)

void

setOrbitMode(GameBase orbitObject, TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, bool ownClientObj, Point3F offset, bool locked)

bool

setOrbitObject(GameBase orbitObject, VectorF rotation, float minDistance, float maxDistance, float initDistance, bool ownClientObject, Point3F offset, bool locked)

void

setOrbitPoint(TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, Point3F offset, bool locked)

void

setRotation(Point3F rot)

void

setSpeedMultiplier(float multiplier)

bool

setTrackObject(GameBase trackObject, Point3F offset)

void

setValidEditOrbitPoint(bool validPoint)

void

setVelocity(VectorF velocity)

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.

// 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.

// 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() );

// 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:

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.

CameraMotionMode controlMode 

bool newtonMode 

bool newtonRotation 

float mass 

float drag 

float force 

float angularDrag 

float angularForce 

float speedMultiplier 

float brakeMultiplier 

int extendedMovePosRotIndex 

bool isRenderable 

bool isSelectable 

float movementSpeed 

autoFitRadius(float radius)

getAngularVelocity()

getMode()

getOffset()

getPosition()

getRotation()

getVelocity()

isEditOrbitMode()

isRotationDamped()

lookAt(Point3F point)

setAngularDrag(float drag)

setAngularForce(float force)

setAngularVelocity(VectorF velocity)

setBrakeMultiplier(float multiplier)

setDrag(float drag)

setEditOrbitMode()

setEditOrbitPoint(Point3F point)

setFlyForce(float force)

setFlyMode()

setMass(float mass)

setNewtonFlyMode()

setOffset(Point3F offset)

setOrbitMode(GameBase orbitObject, TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, bool ownClientObj, Point3F offset, bool locked)

setOrbitObject(GameBase orbitObject, VectorF rotation, float minDistance, float maxDistance, float initDistance, bool ownClientObject, Point3F offset, bool locked)

setOrbitPoint(TransformF orbitPoint, float minDistance, float maxDistance, float initDistance, Point3F offset, bool locked)

setRotation(Point3F rot)

setSpeedMultiplier(float multiplier)

setTrackObject(GameBase trackObject, Point3F offset)

setValidEditOrbitPoint(bool validPoint)

setVelocity(VectorF velocity)