Class: TPolyline3D

Declaration: Graphics3D.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic3D

Inherited By:

None.

Purpose:

TPolyline3D provides a wrapper for the TGPolyline3D geometry class, to which it adds the facilities inherited from MGraphic3D: an attribute bundle, matrix transformations, and hit detection. TPolyline3D has a, not is a, TGPolyline3D. A polyline is a collection of points in 3-D space that are connected with straight line segments. Polylines are parameterized, much like curves. Each of the TPolyline3D member functions is straightforward, either because it overrides the MGraphic3D function of the same name, or because it simply invokes the TGPolyline3D function of the same name.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPolyline3D::TPolyline3D

TPolyline3D ()
TPolyline3D (const TGPoint3DArray & points, TGrafBundle3D * adoptBundle =NIL)
TPolyline3D (const TGPolyline3D & polyLine, TGrafBundle3D * adoptBundle =NIL)
TPolyline3D (const TPolyline3D & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a TPolyline3D from the specified array of points and with the specified attribute bundle.
Creates a TPolyline3D from the specified TGPolyline3D's geometry and with the specified attribute bundle.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly.
Call this function directly.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
const TGPoint3DArray & points -The array of points that are to be this polyline's control points.
TGrafBundle3D * adoptBundle =NIL -The bundle to be adopted.
const TGPolyline3D & polyLine -The polyline whose geometry is to be used.
TGrafBundle3D * adoptBundle =NIL -The bundle to be adopted.
const TPolyline3D & copy -The polyline to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::~TPolyline3D

virtual ~ TPolyline3D ()

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: TPolyline3D::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this TPolyline3D to the specified grafport.

Calling Context:

Call this function directly.

Parameters:

TGrafPort & port -The grafport to draw to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::GetGeometricBounds

virtual TGBox3D GetGeometricBounds () const

Interface Category:

API.

Purpose:

Returns the bounding box of the TPolyline3D's geometry, without considering any volume added by its bundle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounding box of the graphic's geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::TransformBy

virtual void TransformBy (const TGrafMatrix3D & matrix)

Interface Category:

API.

Purpose:

Transforms this TPolyline3D's shape and position by applying the specified transformation matrix.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix3D & matrix -The transformation matrix by which the graphic's points are multiplied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::TranslateBy

virtual void TranslateBy (const TGPoint3D & delta)

Interface Category:

API.

Purpose:

Moves the TLine3D's position by the specified vector.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & delta -The vector whose x-, y-, and z-coordinates are to be added to those of each point in the line's geometry.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::ScaleBy

virtual void ScaleBy (const TGPoint3D & scaleFactor, const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin)

Interface Category:

API.

Purpose:

Changes the size of this TPolyline3D by multiplying the coordinates by the specified scaling factor. It scales the graphic about the specified center of scale. The factor parameter is a vector of type TGPoint3D that allows non-uniform scaling using x-, y-, and z-coordinates of different values. For uniform scaling, the x-, y-, and z-coordinates should be the same. The effect of negative scaling factors is the same as mirroring. (For example, scaling by -1.0 in the x-coordinate is like mirroring about the Y-Z plane.)

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & scaleFactor -A vector of three values that determines the amount each coordinate is to be scaled.
const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin -The center of the scaling.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::RotateBy

virtual void RotateBy (GDegrees angle, TGrafMatrix3D :: EAxis axis)
virtual void RotateBy (GDegrees angle, const TGLine3D & ray)

Interface Category:

API.

Purpose:

Rotates this TPolyline3D counterclockwise around the specified axis by the specified angle. The right-handed coordinate system determines the orientation. That is, when you look from the positive axis towards the 3-D origin, a 90 degree counterclockwise rotation transforms one positive axis into the other.
Rotates this TPolyline3D around the specified (arbitrary) axis by the specified angle. The direction of the vector (the axis parameter) determines the orientation of the rotation. The first point of the TGLine3D parameter is the origin; the second point determines the direction of the vector. The orientation of the rotation is counterclockwise around the vector.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

GDegrees angle -The degree of the specified rotation.
TGrafMatrix3D :: EAxis axis -Determines which axis the specified rotation is to take place about. There are three enumerated types: kAboutXAxis, kAboutYAxis, or kAboutZAxis.
GDegrees angle -The degree of the specified rotation.
const TGLine3D & ray -The arbitrary axis of rotation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::GetNumberOfPoints

unsigned long GetNumberOfPoints () const

Interface Category:

API.

Purpose:

Gets the number of control points in this TPolyline3D.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the number of control points.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::GetPoint

TGPoint3D GetPoint (unsigned long index) const

Interface Category:

API.

Purpose:

Gets the control point at the specified index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).

Return Value:

Returns the point at the index.

Exceptions:

Throws no exceptions, but TGPolyline3D::GetPoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::GetPoints

void GetPoints (TGPoint3DArray & points) const

Interface Category:

API.

Purpose:

Copies the TPolyline3D's control points into the parameter.

Calling Context:

Call this function directly.

Parameters:

TGPoint3DArray & points -The point array that the polyline's control points are copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::SetPoint

void SetPoint (unsigned long index, const TGPoint3D & point)

Interface Category:

API.

Purpose:

Resets the control point at the specified index to the specified point.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).
const TGPoint3D & point -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, but TGPolyline3D::SetPoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::SetPoints

void SetPoints (const TGPoint3DArray & points)

Interface Category:

API.

Purpose:

Resets this TPolyline3D's control points. The number of points can be changed.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3DArray & points -The array of new control points.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::RemovePoint

void RemovePoint (unsigned long index)

Interface Category:

API.

Purpose:

Removes this TPolyline3D's control point at the specified index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).

Return Value:

None.

Exceptions:

Throws no exceptions, but TGPolyline3D::RemovePoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::ReverseDirection

void ReverseDirection ()

Interface Category:

API.

Purpose:

Reverses the direction of the TPolyline3D (that is, the order of the control points).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::AddBefore

void AddBefore (unsigned long index, const TGPoint3D & point)

Interface Category:

API.

Purpose:

Inserts the specified point at the specified index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).
const TGPoint3D & point -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. However, a parameter assertion in TGPolyline3D fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::Append

void Append (const TGPoint3D & point)

Interface Category:

API.

Purpose:

Appends the specified point to the end of this TPolyline3D.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & point -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::DragPosition

virtual void DragPosition (GParametric u, const TGPoint3D & toPt)

Interface Category:

API.

Purpose:

Changes the TPolyline3D so that it passes through the specified TGPoint3D at the specified parametric value. The two control points nearest to the parametric are moved so that the line segment passes through the specified point.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The parametric value.
const TGPoint3D & toPt -The new point that this polyline passes through.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::Evaluate

virtual TGPoint3D Evaluate (GParametric u) const

Interface Category:

API.

Purpose:

Returns a point corresponding to the specified parametric value on this TPolyline3D. A value of 0 corresponds to the start point and n to the endpoint (where n is one less than the number of control points in the polyline). Values outside this range return an extrapolated point.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The parametric position on the polyline.

Return Value:

Returns a point on the polyline at the specified parametric value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::NearestParametric

virtual GParametric NearestParametric (const TGPoint3D & p) const

Interface Category:

API.

Purpose:

Computes the parametric value of this TPolyline3D at the point on the polyline nearest to the specified TGPoint. Polylines are parameterized starting at 0 and incremented by 1 at each control point. For example, a three-point polyline has a parametric range between 0 and 2 (inclusively).

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & p -The point for which the parametric value is computed.

Return Value:

Returns the parametric value of the polyline corresponding to a point on the polyline nearest to the specified point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::operator==

bool operator ==(const TPolyline3D & source) const

Interface Category:

API.

Purpose:

Tests two TPolyline3Ds for equality.

Calling Context:

Call this operator by using it in an expression.

Parameters:

const TPolyline3D & source -The polyline to be compared to this polyline.

Return Value:

Returns true if all the control points are equal to the corresponding points of the source polyline, and if the bundles are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::operator!=

bool operator != (const TPolyline3D & source) const

Interface Category:

API.

Purpose:

Tests the two TPolyline3Ds for inequality.

Calling Context:

Call this operator by using it in an expression.

Parameters:

const TPolyline3D & source -The polyline to be compared to this polyline.

Return Value:

Returns true if any of the control points of the source polyline are not equal to this polyline's corresponding points, and if the bundles are unequal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline3D::operator=

TPolyline3D & operator =(const TPolyline3D & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPolyline3D & source -The polyline to be copied.

Return Value:

Returns a 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: TPolyline3D::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream that the object is streamed 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: TPolyline3D::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream that the object is streamed 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.

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