com.threed.jpct
Class Camera

java.lang.Object
  com.threed.jpct.BufferedMatrix
      com.threed.jpct.Camera

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Projector

public class Camera

extends BufferedMatrix

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). This class extends BufferedMatrix, so the methods for rotating the camera can be found there. 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	adjustFovToNearPlane() Adjusts the fov so that a changed near plane doesn't cause a zoom-in/zoom-out effect.
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	getBillBoardMatrix() Returns the bill board matrix or null if none has been set.
SimpleVector	getDirection() Returns the direction vector of the camera in world space.
SimpleVector	getDirection(SimpleVector toFill) Returns the direction vector of the camera in world space and fills the given SimpleVector with the result.
int	getEllipsoidMode() Returns the current ellipsoid mode.
float	getFarClippingPlane() Returns the far clipping plane.
float	getFOV() Returns the FOV.
float	getFrustumOffsetX() Returns the current frustum offset in x-direction.
float	getFrustumOffsetY() Returns the current frustum offset in y-direction.
float	getMaxFOV() Gets the highest possible FOV.
float	getMinFOV() Gets the lowest possible FOV.
float	getNearClippingPlane() Returns the near clipping plane.
SimpleVector	getPosition() Gets the current position of the camera.
SimpleVector	getPosition(SimpleVector toFill) Gets the current position of the camera and fill the given SimpleVector with the result.
Matrix	getProjectionMatrix(FrameBuffer buffer) Returns the projection matrix.
Matrix	getProjectionMatrix(FrameBuffer buffer, float nearPlane, float farPlane) Returns the projection matrix with arbitrary values for near and far clipping plane.
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	setBillBoardMatrix(Matrix billBoardMatrix) Sets a special matrix used for the bill board calculations.
void	setClippingPlanes(float near, float far) If set, this overrides the settings in Config for the near and the far clipping plane for this world.
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	setFovAngle(float radians) An alternative to setFOV, which works directly with the angle.
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	setFrustumOffset(float frustumOffsetX, float frustumOffsetY) Sets relative offsetss to view frustum in x and y-direction.
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).
void	setYFovAngle(float radians) An alternative to setYFOV, which works directly with the angle.
SimpleVector	transform(SimpleVector vertex) Transforms a vertex from world into camera space.
SimpleVector	transform(SimpleVector vertex, SimpleVector toFill) Transforms a vertex from world into camera space.

Methods inherited from class com.threed.jpct.BufferedMatrix

copyBackToFront, getBack, getFront, matMul, rotateAxis, rotateX, rotateY, rotateZ, setBack

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

getPosition

public SimpleVector getPosition(SimpleVector toFill)

Gets the current position of the camera and fill the given SimpleVector with the result.

Parameters:

toFill - the vector that should contain the position

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

getDirection

public SimpleVector getDirection(SimpleVector toFill)

Returns the direction vector of the camera in world space and fills the given SimpleVector with the result. 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).

Parameters:

toFill - the vector that should contain the position

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). This method doesn't take the angle directly but the value calculated by tan(angle / 2) * 2. If you want to work with the angle, use setFovAngle() instead.

Parameters:

tanFOV - the FOV (default is 1.25).

See Also:

setFOVLimits(float,float)

setFovAngle

public void setFovAngle(float radians)

An alternative to setFOV, which works directly with the angle.

Parameters:

radians - the fov angle (between 0 and PI/2)

setYFOV

public void setYFOV(float tanFOV)

Sets the FOV in y-direction (within the limits set by setFOVLimits). This method doesn't take the angle directly but the value calculated by tan(angle / 2) * 2. If you want to work with the angle, use setYFovAngle() instead.

Parameters:

tanFOV - the y-FOV (default is -1, which means that its derived from the x-FOV)

See Also:

setFOVLimits(float,float)

setYFovAngle

public void setYFovAngle(float radians)

An alternative to setYFOV, which works directly with the angle.

Parameters:

radians - the fov angle (between 0 and PI/2)

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

adjustFovToNearPlane

public void adjustFovToNearPlane()

Adjusts the fov so that a changed near plane doesn't cause a zoom-in/zoom-out effect.

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. Make sure that these vectors are orthogonal.

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

transform

public SimpleVector transform(SimpleVector vertex,
                              SimpleVector toFill)

Transforms a vertex from world into camera space.

Parameters:

vertex - the vertex in world space

toFill - the vertex to fill with the result. This will be returned as well.

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

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

getProjectionMatrix

public Matrix getProjectionMatrix(FrameBuffer buffer)

Returns the projection matrix.

Parameters:

buffer - the framebuffer

Returns:

the projection matrix

getProjectionMatrix

public Matrix getProjectionMatrix(FrameBuffer buffer,
                                  float nearPlane,
                                  float farPlane)

Returns the projection matrix with arbitrary values for near and far clipping plane.

Parameters:

buffer - the framebuffer

nearPlane - the near plane

farPlane - the far plane

Returns:

the projection matrix.

setClippingPlanes

public void setClippingPlanes(float near,
                              float far)

If set, this overrides the settings in Config for the near and the far clipping plane for this world. If you don't touch this method, the settings in Config will be taken instead.

Parameters:

near - the near plane

far - the far plane

See Also:

Config.farPlane, Config.nearPlane

getNearClippingPlane

public float getNearClippingPlane()

Returns the near clipping plane. This can either be the value set by the setClippingPlanes()-method in this class, or (if that method hasn't been used), the one from Config.

Returns:

the near plane

getFarClippingPlane

public float getFarClippingPlane()

Returns the far clipping plane. This can either be the value set by the setClippingPlanes()-method in this class, or (if that method hasn't been used), the one from Config.

Returns:

the far plane

setBillBoardMatrix

public void setBillBoardMatrix(Matrix billBoardMatrix)

Sets a special matrix used for the bill board calculations. Usually, this isn't needed. It might be needed, if you fiddle around with the bill board matrix yourself.

Parameters:

billBoardMatrix - the new matrix, set it to null to erase it.

getBillBoardMatrix

public Matrix getBillBoardMatrix()

Returns the bill board matrix or null if none has been set.

Returns:

the matrix or null

setFrustumOffset

public void setFrustumOffset(float frustumOffsetX,
                             float frustumOffsetY)

Sets relative offsetss to view frustum in x and y-direction. Negative values will shift the frustum left/down and positive right/up. Default is 0,0, which means that the frustum will be centered.

Parameters:

frustumOffsetX - the new frustum offset in x-direction

frustumOffsetY - the new frustum offset in y-direction

getFrustumOffsetX

public float getFrustumOffsetX()

Returns the current frustum offset in x-direction.

Returns:

the offset

getFrustumOffsetY

public float getFrustumOffsetY()

Returns the current frustum offset in y-direction.

Returns:

the offset