Class: TGRPoint

Declaration: BaseGeometry.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

The TGRPoint class represents a homogeneous (rational) point or vector on the 2-D coordinate plane. It defines a set of three coordinate values (x, y, and w). Homogeneous points provide two types of functionality: (1) They are used by the TGLoop and TGCurve classes to accurately represent conic sections such as circles, curves, arcs, ellipses, and so forth. TGLoop and TGCurve are Bezier curves that cannot represent true conic sections without homogeneous points. (2) They are used by the TGrafMatrix class to create a perspective effect in 2-D where the object appears to get smaller as it moves further from view. The fX and fY values (or kOrigin constant) supply the (x,y) coordinates, and the fW value is projected (divided out) just before the object is rendered to create the perspective effect. A TGPoint can be converted directly to a TGRPoint via the constructor; a w value of 1.0 is assumed. However, the conversion the other direction must be done explicitly with either a DivW or DropW operation. Note that arithmetic operators are deliberately not provided for TGRPoints, because their correct interpretation is too application specific.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive any classes from TGRPoint: All TGRPoint's data is public, and its destructor is not virtual.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGRPoint::TGRPoint

TGRPoint ()
TGRPoint (GCoordinate x, GCoordinate y, GCoordinate w =1.0)
TGRPoint (const TGRPoint &)
TGRPoint (const TGPoint & p)

Interface Category:

API.

Purpose:

Default constructor. No member variables are initialized.
Creates a homogeneous point with the given coordinates.
Copy constructor.
Creates a TGRPoint whose x- and y-coordinates equal those of the TGPoint argument, and whose w-coordinate is 1.0.

Calling Context:

Creates a TGRPoint without initializing the member variables.
Creates a point with the specified coordinates.
Called to copy an object.
Called to create a TGRPoint from a TGPoint.

Parameters:

Takes no parameters.
GCoordinate x -The x-coordinate.
GCoordinate y -The y-coordinate.
GCoordinate w =1.0 -The w-coordinate.
const TGRPoint & -The point to be copied.
const TGPoint & p -The normal 2-D point whose x- and y-coordinates are copied to the TGRPoint.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::~TGRPoint

~ TGRPoint ()

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

TGRPoint & operator =(const TGRPoint & Src)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object. Call this function directly.

Parameters:

const TGRPoint & Src -The point 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: TGRPoint::operator==

bool operator ==(const TGRPoint & Src) const

Interface Category:

API.

Purpose:

Tests whether the point's coordinates equal those of the argument.

Calling Context:

Called to test equivalence of two objects. Call this function directly.

Parameters:

const TGRPoint & Src -The object whose coordinates are compared to this object's coordinates.

Return Value:

Returns true if fX, fY, and fW are identical to Src's x-, y-, and w-coordinates, respectively.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::operator!=

bool operator != (const TGRPoint & Src) const

Interface Category:

API.

Purpose:

Tests whether the point's coordinates differ from those of the argument.

Calling Context:

Called to test equivalence of two objects. Call this function directly.

Parameters:

const TGRPoint & Src -The object whose coordinates are compared to this object's coordinates.

Return Value:

Returns true if any of Src's coordinates do not match the corresponding coordinate of this TGRPoint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::DivW

TGPoint DivW () const

Interface Category:

API.

Purpose:

Divides the coordinates by w to create a TGPoint. The TGRPoint is unchanged. This division by the homogeneous coordinate projects the rational point onto the coordinate plane.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The new TGPoint, whose x- and y-coordinates are those of this TGRPoint, divided by w.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::DropW

TGPoint DropW () const

Interface Category:

API.

Purpose:

Creates a TGPoint by ignoring the w-coordinate.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The new TGPoint, whose x- and y-coordinates equal those of this TGRPoint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::operator[]

GCoordinate & operator [] (unsigned long index)
const GCoordinate & operator [] (unsigned long index) const

Interface Category:

API.

Purpose:

Returns the x-, y-, or w-coordinate, depending on the index.
Returns the x-, y-, or w-coordinate of a const TGRPoint.

Calling Context:

Called to retrieve a coordinate of the TGRPoint preceding the [ symbol.
Called to retrieve a coordinate of the const TGRPoint preceding the [ symbol.

Parameters:

unsigned long index -0 for the x-coordinate, 1 for the y-coordinate, 2 for the w-coordinate.
unsigned long index -0 for the x-coordinate, 1 for the y-coordinate, 2 for the w-coordinate.

Return Value:

The specified coordinate.

Exceptions:

Calls a parameter assert if the index is not 0, 1, or 2.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRPoint::operator<<=

TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data. Call this function directly.

Parameters:

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

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream to which the object streams itself.

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.

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