com.jme.input
Class ChaseCamera

java.lang.Object
  extended by com.jme.input.InputHandler
      extended by com.jme.input.ChaseCamera

public class ChaseCamera
extends InputHandler

Camera handler that will smoothly follow a set scene element, allowing for rotation about and zoom on that element.

see the javadoc for update(float time) for information on how positioning works.

Version:
$Revision: 4371 $
Author:
Joshua Slack

Field Summary
protected  Camera cam
           
protected  Vector3f compVect
           
protected  float dampingK
           
static float DEFAULT_DAMPINGK
           
static boolean DEFAULT_ENABLESPRING
           
static boolean DEFAULT_MAINTAINAZIMUTH
           
static float DEFAULT_MAXDISTANCE
           
static float DEFAULT_MINDISTANCE
           
static float DEFAULT_SPRINGK
           
static boolean DEFAULT_STAYBEHINDTARGET
           
static Vector3f DEFAULT_WORLDUPVECTOR
           
protected  Vector3f dirVec
           
protected  boolean enableSpring
           
protected  boolean forceAzimuthUpdate
           
protected  Vector3f idealPosition
           
protected  Vector3f idealSphereCoords
           
protected  Vector3f leftVec
           
protected  boolean looking
           
protected  boolean maintainAzimuth
           
protected  float maxDistance
           
protected  float minDistance
           
protected  ThirdPersonMouseLook mouseLook
          The ThirdPersonMouseLook action, kept as a field to allow easy access to setting speeds and y axis flipping.
protected  Vector3f oldCameraDir
           
static java.lang.String PROP_DAMPINGK
           
static java.lang.String PROP_ENABLESPRING
           
static java.lang.String PROP_INITIALSPHERECOORDS
           
static java.lang.String PROP_MAINTAINAZIMUTH
           
static java.lang.String PROP_MAXDISTANCE
           
static java.lang.String PROP_MINDISTANCE
           
static java.lang.String PROP_SPRINGK
           
static java.lang.String PROP_STAYBEHINDTARGET
           
static java.lang.String PROP_TARGETOFFSET
           
static java.lang.String PROP_WORLDUPVECTOR
           
protected  float speed
           
protected  float springK
           
protected  boolean stayBehindTarget
           
protected  Spatial target
           
protected  Vector3f targetOffset
           
protected  Vector3f targetPos
           
protected  Vector3f upVec
           
protected  Vector3f velocity
           
protected  Vector3f worldUpVec
           
 
Fields inherited from class com.jme.input.InputHandler
activeTriggers, allTriggers, AXIS_ALL, AXIS_NONE, BUTTON_ALL, BUTTON_NONE, DEVICE_ALL, DEVICE_KEYBOARD, DEVICE_MOUSE, event, mouse
 
Constructor Summary
ChaseCamera(Camera cam, Spatial target)
          Simple constructor that accepts a Camera and a target and sets all properties to their defaults.
ChaseCamera(Camera cam, Spatial target, java.util.Map<java.lang.String,java.lang.Object> props)
          More involved constructor allowing the setting of all member fields in ChaseCamera and its associated ThirdPersonMouseLook object via a Map of properties.
 
Method Summary
protected  void convertIdealSphereToCartesian()
           
protected  void enforceMinMaxDistance(Vector3f camPos)
           
 Camera getCamera()
           
 float getDampingK()
           
 Vector3f getIdealPosition()
           
 Vector3f getIdealSphereCoords()
           
 float getMaxDistance()
           
 float getMinDistance()
           
 ThirdPersonMouseLook getMouseLook()
           
 float getSpeed()
           
 float getSpringK()
           
 Spatial getTarget()
           
 Vector3f getTargetOffset()
           
 boolean isEnableSpring()
           
 boolean isForceAzimuthUpdate()
           
 boolean isLooking()
           
 boolean isMaintainAzimuth()
           
 boolean isStayBehindTarget()
           
 void setActionSpeed(float speed)
          Sets the speed of all actions currently registered with this handler to the given value.
 void setCamera(Camera cam)
           
 void setDampingK(float dampingK)
           
 void setEnableSpring(boolean disableSpring)
           
 void setForceAzimuthUpdate(boolean forceAzimuthUpdate)
           
 void setIdealSphereCoords(Vector3f idealSphereCoords)
           
 void setLooking(boolean b)
           
 void setMaintainAzimuth(boolean b)
           
 void setMaxDistance(float maxDistance)
           
 void setMinDistance(float distance)
           
 void setSpringK(float springK)
           
 void setStayBehindTarget(boolean stayBehind)
           
 void setTarget(Spatial target)
           
 void setTargetOffset(Vector3f targetOffset)
           
protected  void setupMouse()
          Set up a relative mouse and the ThirdPersonMouseLook used in this camera's control.
 void setWorldUpVec(Vector3f worldUpVec)
           
 void update(float time)
           update repositions the camera based on the current position and an ideal position using spherical coordinates.
protected  void updateCameraPosition(float time, Vector3f camPos)
           
protected  void updateIdealAzimuth(float time, Vector3f camPos)
           
 void updateProperties(java.util.Map<java.lang.String,java.lang.Object> props)
          updateProperties allows you to update all properties of this chase camera and its related mouse look class.
protected  void updateTargetPosition(Vector3f camPos)
           
 
Methods inherited from class com.jme.input.InputHandler
addAction, addAction, addAction, addAction, addAction, addAction, addDevice, addToAttachedHandlers, clearActions, getBooleanProp, getDevices, getFloatProp, getFromAttachedHandlers, getIntProp, getObjectProp, getParent, isEnabled, processTriggers, removeAction, removeAction, removeAllActions, removeAllFromAttachedHandlers, removeFromAttachedHandlers, setActionSpeed, setEnabled, setEnabledOfAttachedHandlers, setParent, sizeOfAttachedHandlers, updateAttachedHandlers
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROP_INITIALSPHERECOORDS

public static final java.lang.String PROP_INITIALSPHERECOORDS
See Also:
Constant Field Values

PROP_DAMPINGK

public static final java.lang.String PROP_DAMPINGK
See Also:
Constant Field Values

PROP_SPRINGK

public static final java.lang.String PROP_SPRINGK
See Also:
Constant Field Values

PROP_TARGETOFFSET

public static final java.lang.String PROP_TARGETOFFSET
See Also:
Constant Field Values

PROP_WORLDUPVECTOR

public static final java.lang.String PROP_WORLDUPVECTOR
See Also:
Constant Field Values

PROP_ENABLESPRING

public static final java.lang.String PROP_ENABLESPRING
See Also:
Constant Field Values

PROP_STAYBEHINDTARGET

public static final java.lang.String PROP_STAYBEHINDTARGET
See Also:
Constant Field Values

PROP_MAINTAINAZIMUTH

public static final java.lang.String PROP_MAINTAINAZIMUTH
See Also:
Constant Field Values

PROP_MAXDISTANCE

public static final java.lang.String PROP_MAXDISTANCE
See Also:
Constant Field Values

PROP_MINDISTANCE

public static final java.lang.String PROP_MINDISTANCE
See Also:
Constant Field Values

DEFAULT_DAMPINGK

public static final float DEFAULT_DAMPINGK
See Also:
Constant Field Values

DEFAULT_SPRINGK

public static final float DEFAULT_SPRINGK
See Also:
Constant Field Values

DEFAULT_MAXDISTANCE

public static final float DEFAULT_MAXDISTANCE
See Also:
Constant Field Values

DEFAULT_MINDISTANCE

public static final float DEFAULT_MINDISTANCE
See Also:
Constant Field Values

DEFAULT_ENABLESPRING

public static final boolean DEFAULT_ENABLESPRING
See Also:
Constant Field Values

DEFAULT_STAYBEHINDTARGET

public static final boolean DEFAULT_STAYBEHINDTARGET
See Also:
Constant Field Values

DEFAULT_MAINTAINAZIMUTH

public static final boolean DEFAULT_MAINTAINAZIMUTH
See Also:
Constant Field Values

DEFAULT_WORLDUPVECTOR

public static final Vector3f DEFAULT_WORLDUPVECTOR

idealSphereCoords

protected Vector3f idealSphereCoords

idealPosition

protected Vector3f idealPosition

cam

protected Camera cam

velocity

protected Vector3f velocity

target

protected Spatial target

dampingK

protected float dampingK

springK

protected float springK

maxDistance

protected float maxDistance

minDistance

protected float minDistance

enableSpring

protected boolean enableSpring

stayBehindTarget

protected boolean stayBehindTarget

looking

protected boolean looking

maintainAzimuth

protected boolean maintainAzimuth

forceAzimuthUpdate

protected boolean forceAzimuthUpdate

dirVec

protected Vector3f dirVec

worldUpVec

protected Vector3f worldUpVec

upVec

protected Vector3f upVec

leftVec

protected Vector3f leftVec

targetOffset

protected Vector3f targetOffset

targetPos

protected Vector3f targetPos

oldCameraDir

protected Vector3f oldCameraDir

compVect

protected Vector3f compVect

mouseLook

protected ThirdPersonMouseLook mouseLook
The ThirdPersonMouseLook action, kept as a field to allow easy access to setting speeds and y axis flipping.


speed

protected float speed
Constructor Detail

ChaseCamera

public ChaseCamera(Camera cam,
                   Spatial target)
Simple constructor that accepts a Camera and a target and sets all properties to their defaults.

Parameters:
cam - Camera to control
target - the target node to chase

ChaseCamera

public ChaseCamera(Camera cam,
                   Spatial target,
                   java.util.Map<java.lang.String,java.lang.Object> props)
More involved constructor allowing the setting of all member fields in ChaseCamera and its associated ThirdPersonMouseLook object via a Map of properties.

Parameters:
cam - Camera to control
target - the target node to chase
props - a hashmap of properties to set this camera up with. keys are from the statics ChaseCamera.PROP_XXXX and ThirdPersonMouseLook.PROP_XXXX
Method Detail

setupMouse

protected void setupMouse()
Set up a relative mouse and the ThirdPersonMouseLook used in this camera's control.


updateProperties

public void updateProperties(java.util.Map<java.lang.String,java.lang.Object> props)
updateProperties allows you to update all properties of this chase camera and its related mouse look class.

Parameters:
props -

setCamera

public void setCamera(Camera cam)

getCamera

public Camera getCamera()

update

public void update(float time)

update repositions the camera based on the current position and an ideal position using spherical coordinates.

The new position is determined by checking where the target has moved to and getting an offset in relation to the XZ plane. Using this, the ideal spherical coordiantes for the camera are updated for the angle around the up axis (azimuth). Thus, ideal height and distance from the target are still the same regardless of how far the target has moved.

Next, we using a spring system to move from the camera's current position to the calculated "ideal position". This is done by accelerating towards the ideal position using the amount of that distance and the springK factor. This acceleration is damped by the dampingK factor amplified by the magnitude of the current velocity of the camera.

The springK and dampingK factors can be expressed as a damping ratio:

 ratio = dampingK / (2 * sqrt(springK))
 

Typically you want the ratio to come out equal to 1. Values less than 1 will ocillate before coming to rest. Values over 1 will take longer than necessary to come to equilibrium.

Note that if disableSpring is true, the currentPosition is always set to the idealPosition.

See Game programming Gems #4 pgs 303-307 for more in-depth information on the technique.

Overrides:
update in class InputHandler
Parameters:
time - amount of time since last update (in seconds)
See Also:
InputHandler.update(float)

updateCameraPosition

protected void updateCameraPosition(float time,
                                    Vector3f camPos)

updateTargetPosition

protected void updateTargetPosition(Vector3f camPos)

enforceMinMaxDistance

protected void enforceMinMaxDistance(Vector3f camPos)

convertIdealSphereToCartesian

protected void convertIdealSphereToCartesian()

updateIdealAzimuth

protected void updateIdealAzimuth(float time,
                                  Vector3f camPos)

getIdealSphereCoords

public Vector3f getIdealSphereCoords()

getIdealPosition

public Vector3f getIdealPosition()

getMaxDistance

public float getMaxDistance()
Returns:
Returns the maxDistance - the maximum amount the camera is allowed to be away from the target in terms of direct distance.

setMaxDistance

public void setMaxDistance(float maxDistance)
Parameters:
maxDistance - The maxDistance to set. If <= 0 (default is 0) then maxDistance is ignored.

getMinDistance

public float getMinDistance()
Returns:
Returns the minDistance - the minimum amount the camera is allowed to be away from the target in terms of direct distance.

setMinDistance

public void setMinDistance(float distance)
Parameters:
distance - The minDistance to set. If <= 0 (default is 0) then minDistance is ignored.

getDampingK

public float getDampingK()
Returns:
Returns the dampingK.

setDampingK

public void setDampingK(float dampingK)
Parameters:
dampingK - The dampingK to set.

getSpringK

public float getSpringK()
Returns:
Returns the springK.

setSpringK

public void setSpringK(float springK)
Parameters:
springK - The springK to set.

getTarget

public Spatial getTarget()
Returns:
Returns the target.

setTarget

public void setTarget(Spatial target)
Parameters:
target - The target to set

getTargetOffset

public Vector3f getTargetOffset()
Returns:
Returns the targetOffset.

setTargetOffset

public void setTargetOffset(Vector3f targetOffset)
Parameters:
targetOffset - The targetOffset to set (as copy)

setWorldUpVec

public void setWorldUpVec(Vector3f worldUpVec)
Parameters:
worldUpVec - The worldUpVec to set (as copy)

getMouseLook

public ThirdPersonMouseLook getMouseLook()
Returns:
Returns the mouseLook.

isEnableSpring

public boolean isEnableSpring()
Returns:
Returns the disableSpring.

setEnableSpring

public void setEnableSpring(boolean disableSpring)
Parameters:
disableSpring - The disableSpring to set.

isStayBehindTarget

public boolean isStayBehindTarget()
Returns:
the current value of stayBehindTarget

setStayBehindTarget

public void setStayBehindTarget(boolean stayBehind)
Parameters:
stayBehind - true if we want the camera to stay behind the target

setActionSpeed

public void setActionSpeed(float speed)
Description copied from class: InputHandler
Sets the speed of all actions currently registered with this handler to the given value.

Overrides:
setActionSpeed in class InputHandler
Parameters:
speed - The new speed for all currently registered actions.
See Also:
InputAction.setSpeed(float)

getSpeed

public float getSpeed()

setLooking

public void setLooking(boolean b)

isLooking

public boolean isLooking()

setMaintainAzimuth

public void setMaintainAzimuth(boolean b)

isMaintainAzimuth

public boolean isMaintainAzimuth()

isForceAzimuthUpdate

public boolean isForceAzimuthUpdate()

setForceAzimuthUpdate

public void setForceAzimuthUpdate(boolean forceAzimuthUpdate)

setIdealSphereCoords

public void setIdealSphereCoords(Vector3f idealSphereCoords)