Encapsulates
creation, deletion and manipulation of perspective cameras.
Synopsis
#include <AlPerspectiveCamera.h> class AlPerspectiveCamera : public AlCamera , public AlSettable , public AlPickable , public AlAnimatable enum AlCameraWindowFitType { kFillFit, kHorizontalFit, kVerticalFit }; AlPerspectiveCamera(); virtual ~AlPerspectiveCamera(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create(); virtual AlObjectType type() const; AlCameraNode* eye() const; AlCameraNode* view() const; AlCameraNode* up() const; statusCode worldEye( double&, double&, double& ) const; statusCode worldView( double&, double&, double& ) const; statusCode worldUp( double&, double&, double& ) const; statusCode worldEyeViewUp( double&, double&, double&, double&, double&, double&, double&, double&, double& ) const; statusCode setWorldEye( double, double, double); statusCode setWorldView( double, double, double ); statusCode setWorldUp( double, double, double ); statusCode setWorldEyeViewUp( double, double, double, double, double, double, double, double, double ); double twistAngle() const; statusCode setTwistAngle( double ); statusCode changeTwistAngleBy( double ); statusCode filmBack(double&, double&) const; statusCode filmOffset(double&, double&) const; statusCode setFilmBack(double, double); statusCode setFilmOffset(double, double); double focalLength() const; statusCode setFocalLength(double); double angleOfView() const; statusCode setAngleOfView( double ); statusCode depthOfField(boolean&, double&, double&) const; statusCode setDepthOfField(boolean, double, double); int placementFitCode() const; double placementShift() const; statusCode setPlacementFitCode( AlCameraWindowFitType ); statusCode setPlacementShift( double ); statusCode autoFocus( boolean &enabled ) const; statusCode setAutoFocus( boolean enabled );Description
This class encapsulates
all the functionality for creating, deleting and manipulating a
perspective camera. The user cannot create, delete or manipulate
orthographic cameras.
A camera is made of 4
parts - an AlPerspectiveCamera object and 3 attached AlCameraNodes
that represent eye, view and up position of the camera. These camera
nodes are members of the universe’s DAG structure.
The view direction vector
is the vector between the eye position and the view position. The
up direction vector is the vector between the eye position and the
up position. There are methods to get these positions and to access
the attached camera nodes.
To create a perspective
camera, the user must instantiate and call the create method on
an AlPerspectiveCamera object. This creates the necessary eye, view
and up AlCameraNodes, groups them under an AlGroupNode and inserts
the group into the universe’s DAG structure. The user cannot instantiate
an AlCameraNode directly.
When a camera is created,
if the coordinate system is specified as kZUp (when initializing the
universe) the camera’s default eye, view and up positions are respectively
(0.0, -12.0, 0.0), (0.0, 0.0, 0.0), (0.0, -12.0, 1.0). If the coordinate
system is specified as kYUp, then eye, view and up positions are
(0.0, 0.0, 12.0), (0.0, 0.0, 0.0), (0.0, 1.0, 12.0).
There are two ways to
delete a camera object. When the deleteObject() method of an AlPerspectiveCamera
object is called, its three camera nodes are deleted. Alternatively,
when a camera node is deleted, its associated camera (and other
camera nodes) are deleted. The group node that originally grouped
the eye, view and up nodes is not deleted.
AlPerspectiveCamera::AlPerspectiveCamera()
Description
Constructs
an AlPerspectiveCamera wrapper object.
AlPerspectiveCamera::~AlPerspectiveCamera()
Description
Deletes
an AlPerspectiveCamera wrapper object.
AlObject *AlPerspectiveCamera::copyWrapper()
const
Description
Creates a copy of the AlPerspectiveCamera.
The returned AlPerspectiveCamera will reference the same data as
the original.
statusCode AlPerspectiveCamera::deleteObject()
Description
Removes all parts of the camera from
the DAG and deletes them. This includes detaching and deleting the
’eye’, ’view’, and ’up’ DAG nodes.
Return Codes
sSuccess - the camera
data was successfully deleted
sInvalidObject - the
camera was not valid (already deleted?)
statusCode AlPerspectiveCamera::create()
Description
Creates
a camera and all associated eye, view, and up camera nodes and attaches
them to the camera. The camera is given default parameters for
a perspective camera.
Return Codes
sSuccess - everything
was created
sInsufficientMemory -
not enough memory
sFailure - not created
AlObjectType AlPerspectiveCamera::type()
const
Description
Returns the class identifier ’kPerspectiveCameraType’.
AlPerspectiveCamera* AlPerspectiveCamera::asPerspectiveCameraPtr()
Description
This virtual function returns
a non-null pointer to itself, indicating that it is safe to cast
to an object of this class.
AlCameraNode* AlPerspectiveCamera::eye()
const
Description
Returns a pointer to this camera’s eye node.
If the eye node does not exist or is of the wrong type, then this
method returns NULL.
AlCameraNode* AlPerspectiveCamera::view()
const
Description
Returns a pointer to this camera’s view
node. If the view node does not exist or is of the wrong type, then
this method returns NULL.
AlCameraNode* AlPerspectiveCamera::up()
const
Description
Returns a pointer to this camera’s up node.
If the up node does not exist or is of the wrong type, then this
method returns NULL.
statusCode AlPerspectiveCamera::worldEye(
double &x, double &y, double &z ) const
Description
Returns
the camera’s world eye position in x,y, & z in world space.
Arguments
> double &x -
the position along the x axis
> double &y -
the position along the y axis
> double &z -
the position along the z axis
Return Codes
sSuccess - the position
was successfully returned
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::worldView(
double &x, double &y, double &z ) const
Description
Returns
the camera’s view position in x,y, & z in world space. The
view direction vector (the direction the camera is pointing in)
is the vector between the eye position and the view position.
Arguments
> double &x -
the position along the x axis
> double &y -
the position along the y axis
> double &z -
the position along the z axis
Return Codes
sSuccess - the position
was successfully returned
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::worldUp(
double &x, double &y, double &z ) const
Description
Returns
the camera’s up position in x,y, & z in world space. The ’up’
vector (the direction that indicates the camera’s up direction)
is the vector between the eye position and the up position.
Arguments
> double &x -
the position along the x axis
> double &y -
the position along the y axis
> double &z -
the position along the z axis
Return Codes
sSuccess - the position
was successfully returned
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::worldEyeViewUp(
double &ex, double &ey, double &ez,double &vx, double
&vy, double &vz,double &ux, double &uy, double &uz)
const
Description
Returns the world eye, view and
up positions in ex, ey, ez, vx, vy, vz, ux, uy & uz in world space.
Note that the view direction vector is the vector between the eye
and view positions and that the up direction vector is the vector
between the eye and up positions.
Arguments
> double &ex -
the eye position along the x axis
> double &ey -
the eye position along the y axis
> double &ez -
the eye position along the z axis
> double &vx -
the view position along the x axis
> double &vy -
the view position along the y axis
> double &vz -
the view position along the z axis
> double &ux -
the up position along the x axis
> double &uy -
the up position along the y axis
> double &uz -
the up position along the z axis
Return Codes
sSuccess - the position
was successfully returned
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setWorldEye(
double x, double y, double z )
Description
Sets the
camera’s world eye position to be x,y, & z in world space. To
do this, the camera’s eye, view and up nodes may be changed.
Arguments
< double x - the new
world eye position along the x axis
< double y - the new
world eye position along the y axis
< double z - the new
world eye position along the z axis
Return Codes
sSuccess - the position
was successfully set
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setWorldView(
double x, double y, double z)
Description
Sets the
camera’s world view position to be x,y, & z in world space.
To do this, the camera’s eye, view and up nodes may be changed.
Arguments
< double x - the new
world view position along the x axis
< double y - the new
world view position along the y axis
< double z - the new
world view position along the z axis
Return Codes
sSuccess - the position
was successfully set
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setWorldUp(
double x, double y, double z )
Description
Sets the
camera’s world up position to be x,y, & z in world space. To
do this, the camera’s eye, view and up nodes may be changed.
Arguments
< double x - the new
world up position along the x axis
< double y - the new
world up position along the y axis
< double z - the new
world up position along the z axis
Return Codes
sSuccess - the position
was successfully set
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setWorldEyeViewUp(
double ex, double ey, double ez,double vx, double vy, double vz,double
ux, double uy, double uz )
Description
Sets
the camera’s world eye,view and up positions to be ex, ey, ez,
vx, vy, vz, ux, uy, uz in world space. To do this, the camera’s
eye, view and up nodes may be changed.
Arguments
< double ex - the
eye position along the x axis
< double ey - the
eye position along the y axis
< double ez - the
eye position along the z axis
< double vx - the
view position along the x axis
< double vy - the
view position along the y axis
< double vz - the
view position along the z axis
< double ux - the
up position along the x axis
< double uy - the
up position along the y axis
< double uz - the
up position along the z axis
Return Codes
sSuccess - the position
was successfully set
sInvalidObject - the
camera is not valid
double AlPerspectiveCamera::twistAngle()
const
Description
Returns the camera’s twist angle
in degrees. Angle can be either positive or negative. Zero will
be returned if the camera is not valid.
statusCode AlPerspectiveCamera::setTwistAngle(
double twistAngle)
Description
Sets the camera’s
twist angle to the given twistAngle. Angle is in degrees and can
be either positive or negative.
Arguments
< double twistAngle
- the new twist angle
Return Codes
sSuccess - the twist
angle was successfully set
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::changeTwistAngleBy(
double deltaTwistAngle)
Description
Changes
the twist angle by the given deltaTwistAngle. Angle is in degrees
and can be either positive or negative.
Arguments
< deltaTwistAngle
- the change in twist angle to apply to the camera
Return Codes
sSuccess - the twist
angle was successfully changed
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::filmBack(double&
filmXSize, double& filmYSize) const
Description
Returns
the film back size in the X and Y directions.
Arguments
> double& filmXSize
- the film back size (in inches) in the X direction
> double& filmYSize
- the film back size (in inches) in the Y direction
Return Codes
sSuccess - operation
was successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::filmOffset(double&
filmXOffset, double& filmYOffset) const
Description
Returns
the film offset in the X and Y directions.
Arguments
> double& filmXOffset
- the film offset (in inches) in the X direction
> double& filmYOffset
- the film offset (in inches) in the Y direction
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setFilmBack(double
filmXSize, double filmYSize)
Description
Sets
the film back size in the X and Y directions.
Arguments
< double filmXSize
- the film back size (in inches) in the X direction
< double filmYSize
- the film back size (in inches) in the Y direction
Return Codes
sSuccess - the operation
successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setFilmOffset(double filmXOffset,
double filmYOffset)
Description
Sets
the film offset in the X and Y directions.
Arguments
< double filmXOffset
- the film offset (in inches) in the X direction
< double filmYOffset
- the film offset (in inches) in the Y direction
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
double AlPerspectiveCamera::focalLength()
const
Description
Returns the camera’s focal length.
-1 is returned if the camera is not valid.
statusCode AlPerspectiveCamera::setFocalLength(
double focalLength)
Description
Sets the camera’s
focal length.
Arguments
< double focalLength
- the new focal length
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
sInvalidArgument - the
focalLength is less than or equal to zero
double AlPerspectiveCamera::angleOfView()
const
Description
Returns the camera’s angle of view.
Valid range is from 2.0 to 179.0 degrees. -1 is returned if the
camera is not valid.
statusCode AlPerspectiveCamera::setAngleOfView(
double angleOfView)
Description
Sets the camera’s
angle of view. Valid range is from 2.0 to 179.0 degrees.
Arguments
< double angleOfView
- the new angle of view
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
sInvalidArgument - if
angleOfView is not in the valid range
statusCode AlPerspectiveCamera::depthOfField(boolean& dofEnabled,
double& fStop, double& focalDistance) const
Description
Returns the camera’s depth of field
information.
Arguments
> boolean& dofEnabled
- TRUE if depth of field is enabled, FALSE if not
> double& fStop
- camera’s f-Stop
> double& focalDistance
- distance from eye point to plane in focus
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setDepthOfField(boolean dofEnabled,
double fStop, double focalDistance)
Description
Sets
the camera’s depth of field information.
Arguments
< boolean dofEnabled
- TRUE to enable depth of field, FALSE to disable it
< double fStop - camera’s
f-Stop
< double focalDistance
- distance from eye point to plane in focus
Return Codes
sSuccess -the operation
was successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::autoFocus(boolean&
enabled) const
Description
Returns the camera’s
auto focus information.
Arguments
> boolean& enabled
- TRUE if auto focus enabled, FALSE if not
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
statusCode AlPerspectiveCamera::setAutoFocus(
boolean enabled )
Description
Sets the camera’s auto
focus information.
Arguments
< boolean enabled
- TRUE to enable auto focus, FALSE to disable it
Return Codes
sSuccess - the operation
was successful
sInvalidObject - the
camera is not valid
double AlPerspectiveCamera::placementShift()
const
Description
Returns the placement_shift of
the camera. 0 is returned if the camera is not valid.
int AlPerspectiveCamera::placementFitCode()
const
Description
Returns the placement_fit_code
of the camera.
Return values
-1 is returned if the
camera is not valid.
0 - FILL_FIT
1 - HORIZONTAL_FIT
2 - VERTICAL_FIT
statusCode AlPerspectiveCamera::setPlacementShift(
double placementShift )
Description
Sets the placement shift of the camera.
Arguments
< placementShift -
value to set the placement shift to.
Return Codes
sSuccess - if successful
sInvalidObject - if the
camera is not valid
statusCode AlPerspectiveCamera::setPlacementFitCode( AlCameraWindowFitType
fitCode )
Description
Sets the placement fit type of the
camera.
Arguments
< fitCode - value
to set the placement fit code to.
Return Codes
sSuccess - if successful
sInvalidObject - if the
camera is not valid
