Class: TCamera

Declaration: Cameras.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

MCollectible, TMatrix3DState

Inherited By:

TLinkableCamera

Purpose:

TCamera is an abstract base class that encapsulates viewing parameters for a 3-D scene. It is analogous to a camera or an eye in the real world. TCamera controls where the scene is viewed from, how large the image of the scene appears, whether the image is clipped, what its orientation is, and so forth.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Provided class: TLinkableCamera (from which TPerspectiveCamera and TParallelCamera are derived). ! Deriving classes must override all GetXxxx() functions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TCamera::~TCamera

virtual ~ TCamera ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCamera::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:

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: TCamera::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:

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: TCamera::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:

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: TCamera::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:

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: TCamera::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:

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: TCamera::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:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCamera::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:

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: TCamera::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:

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: TCamera::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:

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: TCamera::IsFrontSurface

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

Interface Category:

API.

Purpose:

  1. 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.
  2. 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:

  1. Do not call this function directly.
  2. Do not call this function directly.

Parameters:

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: TCamera::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:

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: TCamera::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:

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: TCamera::Project

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

Interface Category:

API.

Purpose:

  1. 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.
  2. 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:

  1. Do not call this function directly.
  2. Do not call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCamera::TCamera

  1. TCamera ()
  2. TCamera (const TCamera & camera)

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCamera::operator=

TCamera & operator =(const TCamera & 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:

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: TCamera::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.

Parameters:

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: TCamera::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:

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: TCamera::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:

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.
Copyright©1995 Taligent,Inc. All rights reserved.