Encapsulates creation, deletion and manipulation of perspective cameras.
#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 );
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.
Constructs an AlPerspectiveCamera wrapper object.
Deletes an AlPerspectiveCamera wrapper object.
Creates a copy of the AlPerspectiveCamera. The returned AlPerspectiveCamera will reference the same data as the original.
Removes all parts of the camera from the DAG and deletes them. This includes detaching and deleting the ’eye’, ’view’, and ’up’ DAG nodes.
sSuccess - the camera data was successfully deleted
sInvalidObject - the camera was not valid (already deleted?)
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.
sSuccess - everything was created
sInsufficientMemory - not enough memory
sFailure - not created
Returns the class identifier ’kPerspectiveCameraType’.
This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.
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.
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.
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.
Returns the camera’s world eye position in x,y, & z in world space.
> double &x - the position along the x axis
> double &y - the position along the y axis
> double &z - the position along the z axis
sSuccess - the position was successfully returned
sInvalidObject - the camera is not valid
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.
> double &x - the position along the x axis
> double &y - the position along the y axis
> double &z - the position along the z axis
sSuccess - the position was successfully returned
sInvalidObject - the camera is not valid
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.
> double &x - the position along the x axis
> double &y - the position along the y axis
> double &z - the position along the z axis
sSuccess - the position was successfully returned
sInvalidObject - the camera is not valid
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.
> 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
sSuccess - the position was successfully returned
sInvalidObject - the camera is not valid
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.
< 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
sSuccess - the position was successfully set
sInvalidObject - the camera is not valid
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.
< 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
sSuccess - the position was successfully set
sInvalidObject - the camera is not valid
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.
< 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
sSuccess - the position was successfully set
sInvalidObject - the camera is not valid
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.
< 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
sSuccess - the position was successfully set
sInvalidObject - the camera is not valid
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.
Sets the camera’s twist angle to the given twistAngle. Angle is in degrees and can be either positive or negative.
< double twistAngle - the new twist angle
sSuccess - the twist angle was successfully set
sInvalidObject - the camera is not valid
Changes the twist angle by the given deltaTwistAngle. Angle is in degrees and can be either positive or negative.
< deltaTwistAngle - the change in twist angle to apply to the camera
sSuccess - the twist angle was successfully changed
sInvalidObject - the camera is not valid
Returns the film back size in the X and Y directions.
> double& filmXSize - the film back size (in inches) in the X direction
> double& filmYSize - the film back size (in inches) in the Y direction
sSuccess - operation was successful
sInvalidObject - the camera is not valid
Returns the film offset in the X and Y directions.
> double& filmXOffset - the film offset (in inches) in the X direction
> double& filmYOffset - the film offset (in inches) in the Y direction
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
Sets the film back size in the X and Y directions.
< double filmXSize - the film back size (in inches) in the X direction
< double filmYSize - the film back size (in inches) in the Y direction
sSuccess - the operation successful
sInvalidObject - the camera is not valid
Sets the film offset in the X and Y directions.
< double filmXOffset - the film offset (in inches) in the X direction
< double filmYOffset - the film offset (in inches) in the Y direction
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
Returns the camera’s focal length. -1 is returned if the camera is not valid.
Sets the camera’s focal length.
< double focalLength - the new focal length
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
sInvalidArgument - the focalLength is less than or equal to zero
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.
Sets the camera’s angle of view. Valid range is from 2.0 to 179.0 degrees.
< double angleOfView - the new angle of view
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
sInvalidArgument - if angleOfView is not in the valid range
Returns the camera’s depth of field information.
> 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
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
Sets the camera’s depth of field information.
< 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
sSuccess -the operation was successful
sInvalidObject - the camera is not valid
Returns the camera’s auto focus information.
> boolean& enabled - TRUE if auto focus enabled, FALSE if not
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
Sets the camera’s auto focus information.
< boolean enabled - TRUE to enable auto focus, FALSE to disable it
sSuccess - the operation was successful
sInvalidObject - the camera is not valid
Returns the placement_shift of the camera. 0 is returned if the camera is not valid.
Returns the placement_fit_code of the camera.
-1 is returned if the camera is not valid.
0 - FILL_FIT
1 - HORIZONTAL_FIT
2 - VERTICAL_FIT
Sets the placement shift of the camera.
< placementShift - value to set the placement shift to.
sSuccess - if successful
sInvalidObject - if the camera is not valid
Sets the placement fit type of the camera.
< fitCode - value to set the placement fit code to.
sSuccess - if successful
sInvalidObject - if the camera is not valid