Class: TPerspectiveCamera

Declaration: Cameras.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLinkableCamera

Inherited By:

None.

Purpose:

TPerspectiveCamera is a concrete class derived from TLinkableCamera. A perspective camera necessarily has a center of projection, which is the point at which the projectors converge. (Projectors are straight lines connecting points in the scene with the corresponding points in the projection plane.) The size of the projected image depends on the relative distances between the camera, the projection plane, and the 3-D scene. This behavior corresponds to cameras in the real world. The other type of camera is a TParallelCamera, in which the projectors are parallel and the projected image size is always the same regardless of the distances involved. Additional functionality includes TPerspectiveCamera::Zoom, as well as a series of setters corresponding to the getters provided by the base class.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Not expected to be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPerspectiveCamera::TPerspectiveCamera

TPerspectiveCamera ()
TPerspectiveCamera (const TGPoint3D & cameraPosition, const TGPoint3D & referencePoint, const TGPoint3D & upVector, GCoordinate viewDistance, GCoordinate nearPlaneDistance, GCoordinate farPlaneDistance, const TGPoint & projectionPoint =TGPoint :: kOrigin, const TGRect & cropWindow =TGRect :: kInfiniteRect)
TPerspectiveCamera (const TGPoint3D & cameraPosition, const TGPoint3D & referencePoint, GDegrees twistAngle, GCoordinate viewDistance, GCoordinate nearPlaneDistance, GCoordinate farPlaneDistance, const TGPoint & projectionPoint =TGPoint :: kOrigin, const TGRect & cropWindow =TGRect :: kInfiniteRect)
TPerspectiveCamera (const TGPoint3D & cameraPosition, const TGBox3D & boundingBox)
TPerspectiveCamera (const TPerspectiveCamera & camera)

Interface Category:

API.

Purpose:

Default constructor. Initializes variables to their default values and updates the time stamp. The default values specify a camera in the upright position, centered on the z-axis, looking at a projection plane about 3 and 1/3 inches away. The near clipping plane is set at 0.1 world units from the camera and the far clipping plane is set at 1000 world units from the camera (about 13 inches).
Constructor that initializes the important variables with the values provided as arguments. This constructor uses the up vector object to provide the camera orientation.
Constructor that initializes the important variables with the values provided as arguments. This constructor uses the twist angle object to provide the camera orientation.
Constructor that gives a quick and easy way to see an object. By providing the constructor with the bounding box of the object you want to see, the values for the camera are set to look at the object. If the object falls outside of the near and far clipping windows (0.1 and 1000 units from the camera, respectively), then it is possible that some or all of the object will not be visible.
Copy constructor.

Calling Context:

Called by the stream-in operators. You can also call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Called to copy an object. Call this function directly.

Parameters:

Takes no parameters.
const TGPoint3D & cameraPosition -The position of the camera.
const TGPoint3D & referencePoint -The point that the camera is aimed at.
const TGPoint3D & upVector -The up vector, which specifies the camera orientation.
GCoordinate viewDistance -The distance between the camera and projection plane.
GCoordinate nearPlaneDistance -The distance between the camera and the near clipping plane.
GCoordinate farPlaneDistance -The distance between the camera and the far clipping plane.
const TGPoint & projectionPoint =TGPoint :: kInfinite -The 3-D origin projected onto the projection plane. This defaults to the center of the view area.
const TGRect & cropWindow =TGRect :: kInfiniteRect -The area of interest within the viewfinder. This defaults to the entire viewfinder window.
const TGPoint3D & cameraPosition -The position of the camera.
const TGPoint3D & referencePoint -The point that the camera is aimed at.
GDegrees twistAngle -The orientation of the camera, specified in degrees, from the z-axis.
GCoordinate viewDistance -The distance between the camera and the projection plane.
GCoordinate nearPlaneDistance -The distance between the camera and the near clipping plane.
GCoordinate farPlaneDistance -The distance between the camera and the far clipping plane.
const TGPoint & projectionPoint =TGPoint :: kOrigin -The 3-D origin projected onto the projection plane. This defaults to the center of the projection plane.
const TGRect & cropWindow =TGRect :: kInfiniteRect -The area of interest within the viewfinder. This defaults to the entire viewfinder window.
const TGPoint3D & cameraPosition -The position of the camera.
const TGBox3D & boundingBox -The bounding box of the object you want to look at with the camera.
const TPerspectiveCamera & camera -The object to be copied.

Return Value:

None.

Exceptions:

Throws a Parameter Assert exception if either of near or far plane distances specified in constructor 2 or 3 is less than zero; or if the bounding box specified in constructor 4 is a kZeroBox or a kInfiniteBox.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::~TPerspectiveCamera

virtual ~ TPerspectiveCamera ()

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: TPerspectiveCamera::GetPosition

virtual TGPoint3D GetPosition () const

Interface Category:

API.

Purpose:

Returns a TGPoint3D indicating the position of the camera.

Calling Context:

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: TPerspectiveCamera::GetReferencePoint

virtual TGPoint3D GetReferencePoint () const

Interface Category:

API.

Purpose:

Returns the point that is aimed at by the camera.

Calling Context:

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: TPerspectiveCamera::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. A value of (0., 1., 0.) is considered upright.

Calling Context:

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

Calling Context:

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: TPerspectiveCamera::GetCropWindow

virtual TGRect GetCropWindow () const

Interface Category:

API.

Purpose:

Returns the area of interest within the viewfinder.

Calling Context:

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: TPerspectiveCamera::GetProjectionPoint

virtual TGPoint GetProjectionPoint () const

Interface Category:

API.

Purpose:

Returns the 2-D point on the projection plane where the 3-D origin is mapped to. The default is the center of the projection plane.

Calling Context:

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: TPerspectiveCamera::GetViewDistance

virtual GCoordinate GetViewDistance () const

Interface Category:

API.

Purpose:

Returns the distance from the camera to the projection plane.

Calling Context:

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: TPerspectiveCamera::GetNearPlaneDistance

virtual GCoordinate GetNearPlaneDistance () const

Interface Category:

API.

Purpose:

Returns the distance of the front clipping plane from the camera.

Calling Context:

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: TPerspectiveCamera::GetFarPlaneDistance

virtual GCoordinate GetFarPlaneDistance () const

Interface Category:

API.

Purpose:

Returns the distance of the far clipping plane from the camera.

Calling Context:

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: TPerspectiveCamera::SetPosition

virtual void SetPosition (const TGPoint3D & cameraPosition)

Interface Category:

API.

Purpose:

Sets the camera position to the specified TGPoint3D.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & cameraPosition -The new camera position.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetReferencePoint

virtual void SetReferencePoint (const TGPoint3D & viewReferencePoint)

Interface Category:

API.

Purpose:

Sets the point that the camera aims at.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & viewReferencePoint -The new point that the camera aims at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetUpVector

virtual void SetUpVector (const TGPoint3D & upVector)

Interface Category:

API.

Purpose:

Sets the up vector, which defines the orientation of the camera. A value of (0., 1., 0.) is considered upright.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & upVector -The new up vector.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetTwistAngle

virtual void SetTwistAngle (GDegrees twistAngle)

Interface Category:

API.

Purpose:

Sets the twist angle, which defines the orientation of the camera.

Calling Context:

Call this function directly.

Parameters:

GDegrees twistAngle -The new twist angle, in degrees.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetCropWindow

virtual void SetCropWindow (const TGRect & cropWindow)

Interface Category:

API.

Purpose:

Sets the area of interest within the viewfinder.

Calling Context:

Call this function directly.

Parameters:

const TGRect & cropWindow -The new crop window.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetProjectionPoint

virtual void SetProjectionPoint (const TGPoint & origin)

Interface Category:

API.

Purpose:

Sets the 2-D origin of the image.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & origin -The new origin in the 2-D projection plane.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetViewDistance

virtual void SetViewDistance (GCoordinate viewDistance)

Interface Category:

API.

Purpose:

Sets the distance from the camera to the projection plane.

Calling Context:

Call this function directly.

Parameters:

GCoordinate viewDistance -The new distance between the camera and the projection plane.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetNearPlaneDistance

virtual void SetNearPlaneDistance (GCoordinate distance)

Interface Category:

API.

Purpose:

Sets the distance of the front clipping plane from the camera.

Calling Context:

Call this function directly.

Parameters:

GCoordinate distance -The new distance between the camera and the front clipping plane.

Return Value:

None.

Exceptions:

Throws a Parameter Assert exception if the distance specified is less than zero.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::SetFarPlaneDistance

virtual void SetFarPlaneDistance (GCoordinate distance)

Interface Category:

API.

Purpose:

Sets the distance of the far clipping plane from the camera.

Calling Context:

Call this function directly.

Parameters:

GCoordinate distance -The new distance between the camera and the far clipping plane.

Return Value:

None.

Exceptions:

Throws a Parameter Assert exception if the distance specified is less than zero.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::Zoom

virtual void Zoom (GCoordinate factor)

Interface Category:

API.

Purpose:

Scales the camera's distance from the projection plane by the specified scalar.

Calling Context:

Call this function directly.

Parameters:

GCoordinate factor -The scale factor to zoom in by.

Return Value:

None.

Exceptions:

Throws a Parameter Assert exception if the zoom factor is less than zero.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::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.
Returns true if the triangle specified by the surface equation and the point on the triangle's surface faces the camera.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

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

Return Value:

Returns true if the face of 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: TPerspectiveCamera::GetRay

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

Interface Category:

API.

Purpose:

Returns the vector from the eye point (camera) to the center of interest on the 2-D projection plane.

Calling Context:

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.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPerspectiveCamera::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.

Calling Context:

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

Calling Context:

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: TPerspectiveCamera::operator=

TPerspectiveCamera & operator =(const TPerspectiveCamera & src)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data. Only for internal use: Developers should treat this function 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: TPerspectiveCamera::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data. This is for internal use only. Developers should treat this function 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: TPerspectiveCamera::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.
Projects the given 3-D rational point onto the projection plane, returning the projected 2-D rational point in the TGRPoint argument.

Calling Context:

Call this function directly.
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.

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