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
