AlPerspectiveCamera

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