Class: TLinkableCamera

Declaration: Cameras.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TCamera

Inherited By:

TParallelCamera TPerspectiveCamera

Purpose:

TLinkableCamera is an abstract base class, derived from TCamera. Like TCamera, most of its member functions are pure virtual. To the TCamera features, TLinkableCamera adds protocol for linking the camera to a TMatrixState and a TClipState. Linking creates a hierarchy of children and parents. The two concrete descendants of TCamera--TPerspectiveCamera and TParallelCamera--are derived from TLinkableCamera.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLinkableCamera::~TLinkableCamera

virtual ~ TLinkableCamera ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetPosition

virtual TGPoint3D GetPosition () const

Interface Category:

API.

Purpose:

Returns a TGPoint3D indicating the position of the camera. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint3D object indicating the position of the camera.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetReferencePoint

virtual TGPoint3D GetReferencePoint () const

Interface Category:

API.

Purpose:

Returns the point that is aimed at by the camera. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint3D object that is the point aimed at by the camera.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetUpVector

virtual TGPoint3D GetUpVector () const

Interface Category:

API.

Purpose:

Returns the up vector that defines the orientation of the camera. This vector is defined relative to the y-axis of the world coordinate system. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint3D object that is the up vector orientation of the camera.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetTwistAngle

virtual GDegrees GetTwistAngle () const

Interface Category:

API.

Purpose:

Returns the twist angle, which is measured counterclockwise about the z-axis. The twist angle also defines the orientation of the camera. However, if the camera is looking at the scene along a direction parallel to the y-axis, the twist angle is undefined, in which case you should use the up vector instead. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a GDegrees object that contains the twist angle of the camera.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetCropWindow

virtual TGRect GetCropWindow () const

Interface Category:

API.

Purpose:

Returns the area of interest within the viewfinder. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGRect object that specifies the area of interest within the viewfinder rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetProjectionPoint

virtual TGPoint GetProjectionPoint () const

Interface Category:

API.

Purpose:

Returns the 2-D point on the projection plane where the 3-D origins map to. The default is the center of the projection plane. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint object that represents the 3-D origin on the projection plane.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetViewDistance

virtual GCoordinate GetViewDistance () const

Interface Category:

API.

Purpose:

Returns the distance from the camera to the projection plane. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a GCoordinate object that represents the distance from the camera to the projection plane in world units.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetNearPlaneDistance

virtual GCoordinate GetNearPlaneDistance () const

Interface Category:

API.

Purpose:

Returns the distance of the front clipping plane from the camera. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a GCoordinate object that represents the distance of the front clipping plane from the camera in world units.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetFarPlaneDistance

virtual GCoordinate GetFarPlaneDistance () const

Interface Category:

API.

Purpose:

Returns the distance of the far clipping plane from the camera. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a GCoordinate object that represents the distance of the far clipping plane from the camera in world units.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::IsFrontSurface

virtual bool IsFrontSurface (const TGPoint3D & surfacePoint0, const TGPoint3D & surfacePoint1, const TGPoint3D & surfacePoint2, const TGPoint3D & pointOnSurface) const
virtual bool IsFrontSurface (const TGPoint3D & surfaceEquation, const TGPoint3D & pointOnSurface) const

Interface Category:

API.

Purpose:

Returns true if the triangle specified by the three TGPoints and the point on the triangle's surface faces the camera. This is a pure virtual function that must be overridden in derived classes.
Returns true if the triangle specified by the surface equation and the point on the triangle's surface faces the camera. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.
Do not call this function directly.

Parameters:

const TGPoint3D & surfacePoint0 -The first point of a triangle.
const TGPoint3D & surfacePoint1 -The second point of a triangle.
const TGPoint3D & surfacePoint2 -The third point of a triangle.
const TGPoint3D & pointOnSurface -A point on the surface of the triangle.
const TGPoint3D & surfaceEquation -The surface equation for the triangle, specified in a TGPoint3D object.
const TGPoint3D & pointOnSurface -A point on the surface of the triangle.

Return Value:

Returns true if the specified triangle faces the camera.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The surfacePoints (0, 1, 2) of the triangle are specified in a counterclockwise direction.

Member Function: TLinkableCamera::GetViewMatrix

virtual const TGrafMatrix3D * GetViewMatrix () const

Interface Category:

API.

Purpose:

Returns the matrix that transforms from modeling coordinates into the coordinate system that has its origin at the eye point and its z-axis running from the eye point to the center of interest. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to a TGrafMatrix3D object that transforms the modeling coordinates into the viewer's coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetClipMatrix

virtual const TGrafMatrix3D * GetClipMatrix () const

Interface Category:

API.

Purpose:

Returns the matrix that transforms the viewing pyramid defined by the clipping planes into a unit cube for the rendering pipeline. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to a TGrafMatrix3D object that transforms the clipping plane pyramid into a unit cube for the rendering pipeline.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::Project

virtual void Project (const TGRPoint3D & point3D, TGPoint & point) const
virtual void Project (const TGRPoint3D & point3D, TGRPoint & point) const

Interface Category:

API.

Purpose:

Projects the given 3-D rational point onto the projection plane, returning the projected 2-D point in the TGPoint argument. This is a pure virtual function that must be overridden in derived classes.
Projects the given 3-D rational point onto the projection plane, returning the projected 2-D rational point in the TGRPoint argument. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.
Do not call this function directly.

Parameters:

const TGRPoint3D & point3D -The 3-D rational point to use.
TGPoint & point -The resulting 2-D point on the projection plane.
const TGRPoint3D & point3D -The 3-D rational point to use.
TGRPoint & point -The resulting 2-D rational point on the projection plane.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::TLinkableCamera

TLinkableCamera ()
TLinkableCamera (const TLinkableCamera & camera)

Interface Category:

API.

Purpose:

Default constructor. This is a protected constructor that must be overridden by derived classes.
Copy constructor. This is a protected constructor that must be overridden by derived classes.

Calling Context:

Called by the stream-in operators. Do not call this function directly.
Called to copy an object. Do not call this function directly, except from a derived class' copy constructor function.

Parameters:

Takes no parameters.
const TLinkableCamera & camera -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::operator=

TLinkableCamera & operator =(const TLinkableCamera & src)

Interface Category:

API.

Purpose:

Assignment operator. This is a protected function that must be overridden by derived classes.

Calling Context:

Do not call this function directly, except from a derived class' operator =function.

Parameters:

const TLinkableCamera & src -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator. This is a protected member function that must be overridden by derived classes.

Calling Context:

Called to stream out data. Do not call this function directly, except from a derived class' stream-out operator. Developers should treat as protected.

Parameters:

TStream & -The stream that the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator. This is a protected member function that must be overridden by derived classes.

Calling Context:

Called to stream in data. Do not call this function directly, except from a derived class' stream-in operator. Developers should treat as protected.

Parameters:

TStream & -The stream that the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableCamera::GetRay

virtual void GetRay (const TGPoint & screenPoint, TGPoint3D & origin, TGPoint3D & direction) const

Interface Category:

API.

Purpose:

Returns the vector from the eye point to the specified TGPoint on the 2-D projection plane. This is a pure virtual function that must be overridden in derived classes.

Calling Context:

Do not call this function directly.

Parameters:

const TGPoint & screenPoint -The point of interest on the screen.
TGPoint3D & origin -The camera position is returned in this object.
TGPoint3D & direction -The direction vector from the camera to the point of interest on the screen is returned in this object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.