/**
* Rotates this camera by a given amount. If <code>relative</code> is set to <code>true</code>
* then the rotation will be performed relative to this camera's current orientation. Otherwise,
* the rotation will be performed relative to the world coordinate system.
*
* <p>If this camera's focus is locked, then only rotation about the z axis (roll) will be
* performed.
*
* @param rotation The amount of rotation to be applied to this camera.
* @param relative A boolean flag stating whether the rotation performed should be relative to
* this camera's current orientation.
*/
public void rotate(Rotation rotation, boolean relative) {
// store current focus point
Vector3D focusPoint = getFocusPoint();
// perform rotation
if (relative) super.setOrientation(getOrientation().append(rotation));
else super.setOrientation(rotation.append(getOrientation()));
// if focus is locked, look at the point of focus
if (focusLocked) lookAt(focusPoint);
}
/**
* Sets this object's orientation to that described by a given <code>Rotation</code> object,
* relative to the object's default orientation.
*
* @param orientation A <code>Rotation</code> object defining the desired orientation, relative to
* the object's default orientation.
* @throws IllegalArgumentException If <code>orientation</code> is <code>null</code>.
*/
public void setOrientation(Rotation orientation) {
// null given?
if (orientation == null) throw new IllegalArgumentException("Cannot set null orientation.");
// if focus is locked, we can only alter the
// orientation of the local up (y-axis) vector
if (focusLocked) lookAt(getFocusPoint(), Vector3D.Y_AXIS.rotate(orientation));
else super.setOrientation(orientation);
}
/**
* Sets this camera's position to a given point.
*
* @param position A <code>Vector3D</code> describing the position at which to set the camera.
* @throws IllegalArgumentException If <code>position</code> is <code>null</code>.
*/
public void setPosition(Vector3D position) {
// store current focus point
Vector3D focusPoint = getFocusPoint();
// set position
super.setPosition(position);
// if focus is locked, look at original focus point
if (focusLocked()) lookAt(focusPoint);
}
/**
* Rotates this camera to focus on a given point with the local y-axis (up vector) set to a given
* vector. The resulting local y-axis may be altered as needed to make it perpendicular to the
* focus vector formed between this Camera's position and the given point.
*
* @param point A <code>Vector3D</code> describing the point on which this camera will focus.
* @param up A <code>Vector3D</code> describing the desired local y axis (up vector).
*/
public void lookAt(Vector3D point, Vector3D up) {
// find focus vector and distance from point
Vector3D focusVector = point.subtract(getPosition());
// set focus depth
setFocusDepth(focusVector.magnitude());
// set orientation (using inverse of focus vector for +z-axis
super.setOrientation(new Rotation(up, focusVector.inverse()));
}
/**
* Rotates this camera by a given amount around a given point. The rotation will be performed
* relative to the world coordinate system. If the <cod>reorient</code> flag is set to <code>true
* </code>, then the rotation will be applied as a standard rotational transformation would;
* altering this camera's orientation. If set to <code>false</code>, this camera's orientation
* will remain unchanged as the rotation is performed.
*
* <p>Note that the camera will maintain focus if the camera's focus is locked.
*
* @param rotation The amount of rotation to be applied to this camera.
* @param point The point, in the world coordinate system, about which the rotation will occur.
* @param reorient A flag stating whether or not to alter this camera's orientation as with the
* applied rotation.
*/
public void rotate(Rotation rotation, Vector3D point, boolean reorient) {
// store current focus point
Vector3D focusPoint = getFocusPoint();
// find vector between given point and camera, in local coordinates
Vector3D vect = getPosition().subtract(point);
// move camera to given point
super.setPosition(point);
// rotate camera for standard rotation
if (reorient) super.setOrientation(rotation.append(getOrientation()));
// rotate vector
vect = vect.rotate(rotation);
// move back to proper position
super.setPosition(getPosition().add(vect));
// if focus is locked, look at original focus point
if (focusLocked) lookAt(focusPoint);
}
/**
* Rotates and moves the camera in order to follow a given point from a given distance. This
* method is similar to the <code>lookAt()</code> method, except it also adjusts position. When
* needed, the camera will be moved such that the distance between the camera and <code>point
* </code> is less than or equal to <code>distance</code>.
*
* @param point The point to look at / follow.
* @param distance The maximum allowed distance between the camera and the given point.
* @param up A vector describing the orientation of the desired local y-axis.
*/
public void follow(Vector3D point, double distance, Vector3D up) {
// look at the given point
lookAt(point, up);
// further than allowed follow distance?
if (focusDepth > distance) {
// fix position
Vector3D delta = new Vector3D(getFocusVector(), focusDepth - distance);
super.setPosition(getPosition().add(delta));
// set focus depth
setFocusDepth(distance);
}
}