Class: TGPoint3D

Declaration: Geometry3D.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

The TGPoint3D class represents a point in a 3-D space. The point is defined by x-, y-, and z-coordinates, which (for efficiency) are public member variables. A TGPoint3D can also be interpreted as a vector from the origin (0,0,0) to the point (x,y,z). Like the 2-D class TGPoint, TGPoint3D is a primitive type, and is not intended to have derived classes. TGPoint3D is used as a basic building block for most of the 3-D geometric primitives, and as a computational type for performing many sorts of geometric calculations. TGPoint3Ds are treated much like numbers, having the typical operators +, -, *, and / for vector arithmetic, as well as +=, -=, *=, /=, ==, !=, and []. For example, given three TGPoint3Ds a, b, and c, the statement c = a + b; is equivalent to: c.fX =a.fX + b.fX; c.fY =a.fY + b.fY; c.fZ =a.fZ + b.fZ; The [] operator indexes the components. In other words, for a TGPoint3D object called p, p[0] returns p.fX, p[1] returns p.fY, and p[2] returns p.fZ.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Don't derive any classes from TGPoint3D: All TGPoint3D's data is public, and its destructor is not virtual.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGPoint3D::TGPoint3D

TGPoint3D ()
TGPoint3D (GCoordinate x, GCoordinate y, GCoordinate z)
TGPoint3D (const TGPoint3D &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a point with the three specified coordinates.
Copy constructor.

Calling Context:

Called by the stream-in operators. You can also call it directly. (Because the member variables are public, you can call the default constructor and later assign values to the coordinates.)
Call this directly.
Called to copy an object.

Parameters:

Takes no parameters.
GCoordinate x -The x-coordinate of the new point.
GCoordinate y -The y-coordinate of the new point.
GCoordinate z -The z-coordinate of the new point.
const TGPoint3D & -The point to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

These are inline functions.

Member Function: TGPoint3D::operator-

TGPoint3D operator -() const

Interface Category:

API.

Purpose:

Creates the additive inverse of this point (its reflection across all three axes).

Calling Context:

Called when a minus sign precedes a TGPoint3D in an expression.

Parameters:

Takes no parameters.

Return Value:

Returns a new point at (-fX,-fY,-fZ).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator+=

const TGPoint3D & operator += (const TGPoint3D & Src)

Interface Category:

API.

Purpose:

Increments a point by a vector.

Calling Context:

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

Parameters:

const TGPoint3D & Src -The vector to be added to this point.

Return Value:

Returns this point, after the vector has been added to it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator-=

const TGPoint3D & operator -=(const TGPoint3D & Src)

Interface Category:

API.

Purpose:

Decrements a point by a vector.

Calling Context:

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

Parameters:

const TGPoint3D & Src -The vector to be subtracted from this point.

Return Value:

Returns this point, after the vector has been subtracted from it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator*=

const TGPoint3D & operator *= (const TGPoint3D & Src)
const TGPoint3D & operator *= (const GCoordinate Src)

Interface Category:

API.

Purpose:

Multiplies each of the point's three coordinates by the corresponding coordinates of the TGPoint3D parameter.
Multiplies each of the point's three coordinates by the scalar parameter.

Calling Context:

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

Parameters:

const TGPoint3D & Src -The vector by which this point is multiplied.
const GCoordinate Src -The scalar by which this point is multiplied.

Return Value:

Returns this point, after it has been multiplied by the vector or scalar.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator/=

const TGPoint3D & operator /= (const TGPoint3D & Src)
const TGPoint3D & operator /= (const GCoordinate Src)

Interface Category:

API.

Purpose:

Divides each of the point's three coordinates by the corresponding coordinates of the TGPoint3D parameter.
Divides each of the point's three coordinates by the scalar parameter.

Calling Context:

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

Parameters:

const TGPoint3D & Src -The vector by which this point is divided.
const GCoordinate Src -The scalar by which this point is divided.

Return Value:

Returns this point, after it has been divided by the vector or scalar.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator[]

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

Interface Category:

API.

Purpose:

Returns one of the coordinates of the point (fX, fY, or fZ).
Returns one of the coordinates of the point (fX, fY, or fZ).

Calling Context:

Call this function by using the operator in an expression.
Call this function by using the operator in an expression.

Parameters:

unsigned long index -0 for fX, 1 for fY, and 2 for fZ.
unsigned long index -0 for fX, 1 for fY, and 2 for fZ.

Return Value:

Returns the x-, y-, or z-coordinate.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator==

bool operator ==(const TGPoint3D & Src) const

Interface Category:

API.

Purpose:

Tests two points for equality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGPoint3D & Src -The point to be compared to this point.

Return Value:

Returns true if all three coordinates of one point are equal to the corresponding coordinates of the other point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is an inline function.

Member Function: TGPoint3D::operator!=

bool operator != (const TGPoint3D & Src) const

Interface Category:

API.

Purpose:

Tests two points for inequality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGPoint3D & Src -The point to be compared to this point.

Return Value:

Returns true if any coordinate of one point is different from the corresponding coordinate of the other point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is an inline function.

Member Function: TGPoint3D::DotProduct

GCoordinate DotProduct (const TGPoint3D & vector2) const

Interface Category:

API.

Purpose:

Computes the dot product of two vectors. The dot product is x1*x2 + y1*y2 + z1*z2 (where 1 and 2 represent subscripts indicating whether the subscripted coordinate belongs to the first vector or the second vector).

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & vector2 -The vector whose dot product with this TGPoint3D is to be calculated.

Return Value:

Returns the dot product.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::CrossProduct

TGPoint3D CrossProduct (const TGPoint3D & vector2) const

Interface Category:

API.

Purpose:

Computes the cross product of two vectors. The cross product is a vector whose x-coordinate is y1*z2 -y2*z1, whose y-coordinate is x2*z1 -x1*z2, and whose z-coordinate is x1*y2 -x1*y2 -x2*y1 (where 1 and 2 represent subscripts indicating whether the subscripted coordinate belongs to the first vector or the second vector).

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & vector2 -The vector whose cross product with this TGPoint3D is to be calculated.

Return Value:

Returns the cross product.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::Normalize

GCoordinate Normalize ()

Interface Category:

API.

Purpose:

Makes the vector length 1.0, preserving the vector's angle with respect to each axis. However, if the vector length is zero, the vector is not changed.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the length of the vector before normalization.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::VectorLength

GCoordinate VectorLength () const

Interface Category:

API.

Purpose:

Returns the distance of the point from the origin.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the length of the vector.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::SetVectorLength

void SetVectorLength (GCoordinate length)

Interface Category:

API.

Purpose:

Sets the distance of the point from the origin, without changing the angle between the vector and any axis.

Calling Context:

Call this function directly.

Parameters:

GCoordinate length -The new vector length.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGPoint3D::operator<<=

TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream from which the object's data is streamed 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: TGPoint3D::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's data is streamed out.

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.