com.threed.jpct
Class Camera

java.lang.Object
  extended by com.threed.jpct.Camera
All Implemented Interfaces:
java.io.Serializable

public class Camera
extends java.lang.Object
implements java.io.Serializable

The Camera represents the position and direction of the camera/viewer in the current scene. It also contains information about the current field of view (FOV). One should keep in mind that the rotation matrix of the camera is actually a rotation matrix which will be aplied to all objects in the world. This is important when chosing the rotation angle for the camera: A (virtual) rotation of the camera around an axis using the angle w leads to the same results as if the world would rotate around this axis using -w. So the angle given to the rotate?()-methods is actually the angle by which the world rotates around the camera when the camera is viewed as static. If you dislike this behaviour, you may use the rotateCamera?()-methods instead which will take care of it.

See Also:
Serialized Form

Field Summary
static int CAMERA_DONT_MOVE
          Don't move the camera before checking for a collision.
static int CAMERA_MOVEDOWN
          Move the camera down (relative to its current direction)
static int CAMERA_MOVEIN
          Move the camera forward (relative to its current direction)
static int CAMERA_MOVELEFT
          Move the camera left (relative to its current direction)
static int CAMERA_MOVEOUT
          Move the camera backwards (relative to its current direction)
static int CAMERA_MOVERIGHT
          Move the camera right (relative to its current direction)
static int CAMERA_MOVEUP
          Move the camera up (relative to its current direction)
static boolean DONT_SLIDE
          Camera stops in front of obstacles
static int ELLIPSOID_ALIGNED
          The camera's ellipsoid won't be transformed when performing collision detection (default).
static int ELLIPSOID_TRANSFORMED
          The camera's ellipsoid will be transformed when performing collision detection.
static boolean SLIDE
          Camera slides along obstacles.
 
Constructor Summary
Camera()
          Creates a new Camera with default viewing direction (along the z-axis) and position (at the origin) as well as default FOV (as configured, 1.25 is default).
 
Method Summary
 void align(Object3D object)
          Aligns the camera with the (transformed) positive z-axis of an Object3D.
 float convertDEGAngleIntoFOV(float angle)
          Converts an angle in degrees into a FOV value that jPCT can handle.
 float convertRADAngleIntoFOV(float angle)
          Converts an angle in radians into a FOV value that jPCT can handle (=2*tan(angle/2)).
 void decreaseFOV(float dec)
          Decreases the FOV.
 Matrix getBack()
          Returns the Matrix that is used as the backbuffer matrix.
 SimpleVector getDirection()
          Returns the direction vector of the camera in world space.
 int getEllipsoidMode()
          Returns the current ellipsoid mode.
 float getFOV()
          Returns the FOV.
 float getMaxFOV()
          Gets the highest possible FOV.
 float getMinFOV()
          Gets the lowest possible FOV.
 SimpleVector getPosition()
          Gets the current position of the camera.
 SimpleVector getSideVector()
          Returns the side vector of the camera in world space.
 SimpleVector getUpVector()
          Returns the up vector of the camera in world space.
 SimpleVector getXAxis()
          Returns the (virtual) x-axis of the camera.
 SimpleVector getYAxis()
          Returns the (virtual) y-axis of the camera.
 float getYFOV()
          Returns the fov in y-direction.
 SimpleVector getZAxis()
          Returns the (virtual) z-axis of the camera.
 void increaseFOV(float inc)
          Increases the FOV.
 void lookAt(SimpleVector lookAt)
          Rotates the camera so that is looks at the given position in world-space.
 void moveCamera(int mode, float speed)
          Moves (translates) the camera with a given speed into "mode" direction relative to its current direction.
 void moveCamera(SimpleVector direction, float speed)
          Moves (translates) the camera with a given speed in an arbitrary direction (should be a normalized vector).
 void rotateCameraAxis(SimpleVector axis, float angle)
          Rotates the camera around an arbitrary axis.
 void rotateCameraX(float angle)
          Rotates the camera around the x-axis.
 void rotateCameraY(float angle)
          Rotates the camera around the y-axis.
 void rotateCameraZ(float angle)
          Rotates the camera around the z-axis.
 void rotateX(float angle)
          Rotates the camera around the x-axis.
 void rotateY(float angle)
          Rotates the camera around the y-axis.
 void rotateZ(float angle)
          Rotates the camera around the z-axis.
 void setBack(Matrix mat)
          Sets the backbuffer matrix.
 void setEllipsoidMode(int mode)
          When doing ellipsoid collision detection with a camera, the ellipsoid can be transformed according to the camera's transformation in camera space or it remains static in object space (i.e.
 void setFOV(float tanFOV)
          Sets the FOV (within the limits set by setFOVLimits).
 void setFOVLimits(float lower, float higher)
          Sets the limits for FOV jPCT should permit.
 void setFOVtoDefault()
          Resets the FOV to the default value configured in Config.
 void setOrientation(SimpleVector dir, SimpleVector up)
          Sets the orientation of the camera by giving a direction and an up-vector.
 void setPosition(float x, float y, float z)
          Sets the camera to a position in worldspace.
 void setPosition(SimpleVector pos)
          Sets the camera to a position in worldspace.
 void setPositionToCenter(Object3D object)
          Sets the camera to the position of the transformed center of an Object3D.
 void setYFOV(float tanFOV)
          Sets the FOV in y-direction (within the limits set by setFOVLimits).
 SimpleVector transform(SimpleVector vertex)
          Transforms a vertex from world into camera space.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CAMERA_MOVEIN

public static final int CAMERA_MOVEIN
Move the camera forward (relative to its current direction)

See Also:
Constant Field Values

CAMERA_MOVEOUT

public static final int CAMERA_MOVEOUT
Move the camera backwards (relative to its current direction)

See Also:
Constant Field Values

CAMERA_MOVEDOWN

public static final int CAMERA_MOVEDOWN
Move the camera down (relative to its current direction)

See Also:
Constant Field Values

CAMERA_MOVEUP

public static final int CAMERA_MOVEUP
Move the camera up (relative to its current direction)

See Also:
Constant Field Values

CAMERA_MOVELEFT

public static final int CAMERA_MOVELEFT
Move the camera left (relative to its current direction)

See Also:
Constant Field Values

CAMERA_MOVERIGHT

public static final int CAMERA_MOVERIGHT
Move the camera right (relative to its current direction)

See Also:
Constant Field Values

CAMERA_DONT_MOVE

public static final int CAMERA_DONT_MOVE
Don't move the camera before checking for a collision. This is only useful in combination with sphere-polygon-collision and ignored by ray-polygon-collision.

See Also:
Constant Field Values

SLIDE

public static final boolean SLIDE
Camera slides along obstacles. This doesn't work too well when using ray-polygon collision detection. However, it does work using sphere-polygon. Ellipsoid-polygon collision detection will always use sliding.

See Also:
Constant Field Values

DONT_SLIDE

public static final boolean DONT_SLIDE
Camera stops in front of obstacles

See Also:
Constant Field Values

ELLIPSOID_ALIGNED

public static final int ELLIPSOID_ALIGNED
The camera's ellipsoid won't be transformed when performing collision detection (default).

See Also:
Constant Field Values

ELLIPSOID_TRANSFORMED

public static final int ELLIPSOID_TRANSFORMED
The camera's ellipsoid will be transformed when performing collision detection.

See Also:
Constant Field Values
Constructor Detail

Camera

public Camera()
Creates a new Camera with default viewing direction (along the z-axis) and position (at the origin) as well as default FOV (as configured, 1.25 is default).

Method Detail

getPosition

public SimpleVector getPosition()
Gets the current position of the camera.

Returns:
the position

getXAxis

public SimpleVector getXAxis()
Returns the (virtual) x-axis of the camera.

Returns:
the x-axis

getYAxis

public SimpleVector getYAxis()
Returns the (virtual) y-axis of the camera.

Returns:
the y-axis

getZAxis

public SimpleVector getZAxis()
Returns the (virtual) z-axis of the camera.

Returns:
the z-axis

getDirection

public SimpleVector getDirection()
Returns the direction vector of the camera in world space. The returned SimpleVector is already normalized (it should always be normalized due to the nature of the rotation matrix it comes from, but to avoid any possible rounding errors, it's renormalized again within this method).

Returns:
the direction vector

getUpVector

public SimpleVector getUpVector()
Returns the up vector of the camera in world space. The returned SimpleVector is already normalized (it should always be normalized due to the nature of the rotation matrix it comes from, but to avoid any possible rounding errors, it's renormalized again within this method).

Returns:
the up vector

getSideVector

public SimpleVector getSideVector()
Returns the side vector of the camera in world space. The returned SimpleVector is already normalized (it should always be normalized due to the nature of the rotation matrix it comes from, but to avoid any possible rounding errors, it's renormalized again within this method).

Returns:
the side vector

convertRADAngleIntoFOV

public float convertRADAngleIntoFOV(float angle)
Converts an angle in radians into a FOV value that jPCT can handle (=2*tan(angle/2)).

Parameters:
angle - the angle in radians
Returns:
the FOV value

convertDEGAngleIntoFOV

public float convertDEGAngleIntoFOV(float angle)
Converts an angle in degrees into a FOV value that jPCT can handle.

Parameters:
angle - the angle in degrees
Returns:
the FOV value

setFOVLimits

public void setFOVLimits(float lower,
                         float higher)
Sets the limits for FOV jPCT should permit. Anything lower or higher will be clipped to the lowest or highest possible value.

Parameters:
lower - the lowest possible FOV (default is 0.5)
higher - the highest possible FOV (default is 1.5)

getMaxFOV

public float getMaxFOV()
Gets the highest possible FOV.

Returns:
the highest value allowed

getMinFOV

public float getMinFOV()
Gets the lowest possible FOV.

Returns:
the lowest value allowed

setFOV

public void setFOV(float tanFOV)
Sets the FOV (within the limits set by setFOVLimits).

Parameters:
tanFOV - the FOV (default is 1.25)
See Also:
setFOVLimits(float,float)

setYFOV

public void setYFOV(float tanFOV)
Sets the FOV in y-direction (within the limits set by setFOVLimits).

Parameters:
tanFOV - the y-FOV (default is -1, which means that its derived from the x-FOV)
See Also:
setFOVLimits(float,float)

getFOV

public float getFOV()
Returns the FOV.

Returns:
the FOV

getYFOV

public float getYFOV()
Returns the fov in y-direction. Default is -1, which means that the FOV-value in y-direction will be calculated from the x-fov depending on the aspect-ratio-setting in Config. Any other value will override this calculation with a fixed value.

Returns:
the y-fov

increaseFOV

public void increaseFOV(float inc)
Increases the FOV. Useful for zoomin effects.

Parameters:
inc - the amount by which FOV should be increased

decreaseFOV

public void decreaseFOV(float dec)
Decreases the FOV. Useful for zoomout effects.

Parameters:
dec - the amount by which FOV should be decreased

setFOVtoDefault

public void setFOVtoDefault()
Resets the FOV to the default value configured in Config.

See Also:
Config.defaultCameraFOV

lookAt

public void lookAt(SimpleVector lookAt)
Rotates the camera so that is looks at the given position in world-space. (it will only rotate, not move...).

Parameters:
lookAt - the position vector to look at

align

public void align(Object3D object)
Aligns the camera with the (transformed) positive z-axis of an Object3D. This method works on the object's own rotation matrix only. It doesn't take transformations of parent objects into account.

Parameters:
object - the object the camera should be aligned with

setPositionToCenter

public void setPositionToCenter(Object3D object)
Sets the camera to the position of the transformed center of an Object3D.

Parameters:
object - the object

setPosition

public void setPosition(SimpleVector pos)
Sets the camera to a position in worldspace. This method replaces the deprecated setCamera()-method.

Parameters:
pos - the position vector

setPosition

public void setPosition(float x,
                        float y,
                        float z)
Sets the camera to a position in worldspace. This method may be useful if x, y and z are already discrete values. This method replaces the deprecated setCamera()-method.

Parameters:
x - the x component of the position vector
y - the y component of the position vector
z - the z component of the position vector

setOrientation

public void setOrientation(SimpleVector dir,
                           SimpleVector up)
Sets the orientation of the camera by giving a direction and an up-vector.

Parameters:
dir - the direction
up - the up-vector

transform

public SimpleVector transform(SimpleVector vertex)
Transforms a vertex from world into camera space.

Parameters:
vertex - the vertex in world space
Returns:
the transformed vertex

moveCamera

public void moveCamera(int mode,
                       float speed)
Moves (translates) the camera with a given speed into "mode" direction relative to its current direction.

Parameters:
mode - the direction
speed - the speed (positional change in units)
See Also:
CAMERA_MOVEDOWN, CAMERA_MOVEUP, CAMERA_MOVEIN, CAMERA_MOVEOUT, CAMERA_MOVELEFT, CAMERA_MOVERIGHT

moveCamera

public void moveCamera(SimpleVector direction,
                       float speed)
Moves (translates) the camera with a given speed in an arbitrary direction (should be a normalized vector).

Parameters:
direction - the direction
speed - the speed (positional change in units)

rotateCameraAxis

public void rotateCameraAxis(SimpleVector axis,
                             float angle)
Rotates the camera around an arbitrary axis. The method is more powerful than the normal rotate-around-an-axis methods, but also a bit slower. The resulting matrix will be orthonormalized to ensure numerical accuracy.
Unlike the rotateAxis()-method inherited from BufferedMatrix, this method takes care of the fact that rotating the camera using an angle w actually means that the world rotates around -w.

Parameters:
axis - a direction-vector pointing into the axis direction
angle - the angle of the rotation

rotateCameraX

public void rotateCameraX(float angle)
Rotates the camera around the x-axis.
Unlike the rotateX()-method inherited from BufferedMatrix, this method takes care of the fact that rotating the camera using an angle w actually means that the world rotates around -w.

Parameters:
angle - the angle

rotateCameraY

public void rotateCameraY(float angle)
Rotates the camera around the y-axis.
Unlike the rotateAxisY()-method inherited from BufferedMatrix, this method takes care of the fact that rotating the camera using an angle w actually means that the world rotates around -w.

Parameters:
angle - the angle

rotateCameraZ

public void rotateCameraZ(float angle)
Rotates the camera around the z-axis.
Unlike the rotateZ()-method inherited from BufferedMatrix, this method takes care of the fact that rotating the camera using an angle w actually means that the world rotates around -w.

Parameters:
angle - the angle

rotateX

public void rotateX(float angle)
Rotates the camera around the x-axis.

Parameters:
angle - the angle

rotateY

public void rotateY(float angle)
Rotates the camera around the y-axis.

Parameters:
angle - the angle

rotateZ

public void rotateZ(float angle)
Rotates the camera around the z-axis.

Parameters:
angle - the angle

getBack

public Matrix getBack()
Returns the Matrix that is used as the backbuffer matrix.

Returns:
the backbuffer matrix

setBack

public void setBack(Matrix mat)
Sets the backbuffer matrix.

Parameters:
mat - the new backbuffer matrix

setEllipsoidMode

public void setEllipsoidMode(int mode)
When doing ellipsoid collision detection with a camera, the ellipsoid can be transformed according to the camera's transformation in camera space or it remains static in object space (i.e. "axis aligned").
The later is faster, but not suitable for all kinds of ellipsoids and objects.

Parameters:
mode - int the mode
See Also:
ELLIPSOID_ALIGNED, ELLIPSOID_TRANSFORMED

getEllipsoidMode

public int getEllipsoidMode()
Returns the current ellipsoid mode.

Returns:
the mode
See Also:
ELLIPSOID_ALIGNED, ELLIPSOID_TRANSFORMED