Class: TLoop

Declaration: Graphics.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

TLoop provides a wrapper for the TGLoop geometry class, to which it adds the facilities inherited from MGraphic: an attribute bundle, matrix transformations, and hit detection. TLoop has a, not is a, TGLoop. TLoop can be used for such shapes as rounded rectangles, ellipses with control points, and more elaborate closed paths.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLoop::TLoop

TLoop ()
TLoop (const TLoop &)
TLoop (const TGLoop &, TGrafBundle * adoptedBundle =NIL)
TLoop (const TGCurve &, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TLoop (unsigned long order, unsigned long numberPoints, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TLoop (unsigned long order, unsigned long numberPoints, const TRawArray < GParametric > & knots, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TLoop (unsigned long order, const TGRPointArray & points, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TLoop (unsigned long order, const TGRPointArray & points, const TRawArray < GParametric > & knots, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TLoop (const TGEllipse & e, TGrafBundle * adoptBundle =NIL)
TLoop (const TGPolygon & polyline, TGrafBundle * adoptBundle =NIL)
TLoop (const TGRect & rect, TGrafBundle * adoptBundle =NIL)
TLoop (const TGRect & roundRect, const TGPoint & aspect, TGrafBundle * adoptBundle =NIL)
TLoop (const TGGlyphRun &, TGrafBundle * adoptBundle =NIL)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Constructs a TLoop that has the given geometry and bundle.
Constructs a TLoop from a curve geometry.
Constructs a TLoop of the given order and number of points.
Constructs a TLoop from a knot vector.
Constructs a TLoop from an array of rational points.
Constructs a TLoop from an array of rational points and a knot vector.
Constructs a TLoop from an elliptical geometry.
Constructs a TLoop from a polygon.
Constructs a TLoop with a rectangular shape.
Constructs a TLoop with a rounded rectangular shape. The rounded rectangle has sixteen control points--four at the corners, four at the midpoints of the sides, and two on either side of each corner. The aspect parameter controls how far the latter points are from each corner.
Constructs a TLoop from a TGGlyphRun.

Calling Context:

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

Parameters:

Takes no parameters.
const TLoop & -The object to be copied.
const TGLoop & -The geometry to be copied into the new TLoop.
TGrafBundle * adoptedBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGCurve & -The curve geometry to be copied into the new TLoop.
bool EOFill =true -The filling algorithm for the curve. True means an even-odd rule is used for determining what area is filled, and false means a nonzero winding rule is used.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
unsigned long order -The order of the curve (for example, 4 for cubic curves).
unsigned long numberPoints -The number of control points for the curve.
bool EOFill =true -The filling algorithm for the curve. True means an even-odd rule is used for determining what area is filled, and false means a nonzero winding rule is used.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
unsigned long order -The order of the curve (for example, 4 for cubic curves).
unsigned long numberPoints -The number of control points for the curve.
const TRawArray < GParametric > & knots -The curve's knot vector.
bool EOFill =true -The filling algorithm for the curve. True means an even-odd rule is used for determining what area is filled, and false means a nonzero winding rule is used.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
unsigned long order -The order of the curve (for example, 4 for cubic curves).
const TGRPointArray & points -The array of control points for the curve.
bool EOFill =true -The filling algorithm for the curve. True means an even-odd rule is used for determining what area is filled, and false means a nonzero winding rule is used.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
unsigned long order -The order of the curve (for example, 4 for cubic curves).
const TGRPointArray & points -The array of control points for the curve.
const TRawArray < GParametric > & knots -The curve's knot vector.
bool EOFill =true -The filling algorithm for the curve. True means an even-odd rule is used for determining what area is filled, and false means a nonzero winding rule is used.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGEllipse & e -The geometry to be copied into the new TLoop.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGPolygon & polyline -The geometry to be copied into the new TLoop.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGRect & rect -The geometry to be copied into the new TLoop.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGRect & roundRect -The geometry to be copied into the new TLoop.
const TGPoint & aspect -A pair of coordinates that control how rounded the rectangle is. The value (0,0) generates a normal, non-rounded rectangle. Larger coordinates cause more rounded corners. For each corner of the rectangle, a control point is placed on the top or bottom side of the rectangle at the distance aspect.fX away from the corner. Similarly, another control point is placed on the left or right side of the rectangle at the distance aspect.fY from the corner. You should generally use a value of aspect where fX is less than half of the rectangle's width, and fY is less than half of the height. Larger values are permitted, but are clipped, which might give unexpected results.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop.
const TGGlyphRun & -The geometry to be copied into the new TLoop.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted by the new TLoop. new TLoop.

Return Value:

None.

Exceptions:

Throws no exceptions within TLoop, passes all exceptions through. The constructor parameter called order should be 2 or greater, the parameter called numberPoints should be greater than the order, and the number of knots in the knot vector should equal the number of points, plus the order. Otherwise, a parameter assertion occurs in TGCurve.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::~TLoop

virtual ~ TLoop ()

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

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the graphic to the specific TGrafPort. Attributes in the graphic's bundle override those already provided in the port (if any).

Calling Context:

Call this function directly.

Parameters:

TGrafPort & port -The port to which drawing should go. The port in turn invokes rendering on a particular TGrafDevice.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Gets the bounding rectangle of the geometry, without considering any area added by the bundle. (For example, the pen is a bundled attribute that can increase the area of the graphic by adding a border that extends beyond the bounds of the geometry.)

Calling Context:

Called during hit detection. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounding rectangle, which is the smallest axis-aligned rectangle that encloses the geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort* =NIL) const

Interface Category:

API.

Purpose:

Gets the entire graphic's bounding rectangle, taking into account the bundle information. (For example, the pen is a bundled attribute that can increase the area of the graphic by adding a border that extends beyond the bounds of the geometry.)

Calling Context:

Called during hit detection. You can also call this function directly.

Parameters:

const TGrafPort * =NIL -The graphics port used for accessing hierarchical bundles.

Return Value:

Returns the bounding rectangle, which is the smallest axis-aligned rectangle that encloses the entire graphic, including any area added by the pen.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

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

Calling Context:

Called by the Graphics system. You can also call this function directly.

Parameters:

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

Return Value:

None.

Exceptions:

Determined by derived classes.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::ScaleBy

virtual void ScaleBy (const TGPoint &, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Changes the graphic's size according to the specified horizontal and vertical scalars (the coordinates of the first parameter). Because there are two independent scalars, the graphic's shape can change. The second parameter defines the center of scale. Every point is mapped to a new position by applying the scalars to the point's horizontal and vertical displacements from the center of scale. Thus, the scaled graphic does not stay centered at the same point unless the second argument is the old center of the graphic.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -A vector whose x-coordinate is the horizontal scalar, and whose y-coordinate is the vertical scalar.
const TGPoint & =TGPoint :: kOrigin -The point from which to measure the horizontal and vertical displacement of each point to be scaled. To create the resulting geometry, the displacements are multiplied by the horizontal and vertical scalars, respectively. The default center of scale is the origin (0,0).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TLoop implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: TLoop::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the graphic's position by the specified vector.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The vector whose x- and y-coordinates are to be added to those of each point in the geometry.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TLoop implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: TLoop::RotateBy

virtual void RotateBy (GDegrees, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Rotates the graphic by the given number of degrees, using the specified center of rotation. This does not change the size or shape of the graphic, only its orientation.

Calling Context:

Call this function directly.

Parameters:

GDegrees -The number of degrees to rotate the graphic.
const TGPoint & =TGPoint :: kOrigin -The point around which the graphic is rotated.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TLoop implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: TLoop::GetEOFill

bool GetEOFill () const

Interface Category:

API.

Purpose:

Returns a Boolean indicating which one of two possible algorithms is used to fill the curve.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if an even-odd rule is used for determining what area is filled, and false if a nonzero winding rule is used.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::Concatenate

void Concatenate (const TGLoop & p, bool glue =true)

Interface Category:

API.

Purpose:

Appends the given loop to this loop. The beginning control point of the added loop is joined to the end control point of the original loop, and similarly for their knot vectors. If the beginning point of the added loop is at the same location as the endpoint of the original loop, you have the option of specifying whether there should be only one control point and knot there, or two.

Calling Context:

Call this function directly.

Parameters:

const TGLoop & p -The loop to be joined to this one.
bool glue =true -Determines whether to delete one of the connected points, if the appended loop's begin point is the same as the original loop's endpoint. This parameter is ignored if these two control points differ. True (the default) means to delete one of the identical points; false means to leave both points even though they are redundant. Note that this affects the knot vector as well: if glue is true, the appended loop's first knot replaces the original loop's last knot.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::Evaluate

TGPoint Evaluate (GParametric u) const
TGPoint Evaluate (GParametric u, TGPoint & tangent) const
TGPoint Evaluate (GParametric u, TGPoint & tangent, TGPoint & deriv2) const
TGPoint Evaluate (GParametric u, TGPoint & tangent, TGPoint & deriv2, GCoordinate & curvature) const

Interface Category:

API.

Purpose:

Returns the point on the loop at the specified parametric value.
Returns the point on the loop at the specified parametric value; also computes the tangent at this point.
Returns the point on the loop at the specified parametric value; also computes the tangent and second derivative at this point.
Returns the point on the loop at the specified parametric value; also computes the tangent, second derivative, and curvature at this point.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

GParametric u -The parametric value at which to evaluate the loop. The value passed in should not be outside the range defined by GetMinParameter and GetMaxParameter.
GParametric u -The parametric value at which to evaluate the loop. The value passed in should not be outside the range defined by GetMinParameter and GetMaxParameter.
TGPoint & tangent -A vector representing the tangent of the curve at this point; computed by this function.
GParametric u -The parametric value at which to evaluate the loop. The value passed in should not be outside the range defined by GetMinParameter and GetMaxParameter.
TGPoint & tangent -A vector representing the tangent of the curve at this point; computed by this function.
TGPoint & deriv2 -The second derivative of the curve at this point; computed by this function.
GParametric u -The parametric value at which to evaluate the loop. The value passed in should not be outside the range defined by GetMinParameter and GetMaxParameter.
TGPoint & tangent -A vector representing the tangent of the curve at this point; computed by this function.
TGPoint & deriv2 -The second derivative of the curve at this point; computed by this function.
GCoordinate & curvature -The curvature at this point; computed by this function.

Return Value:

Returns the point on the loop that corresponds to the specified parametric value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetOrder

unsigned long GetOrder () const

Interface Category:

API.

Purpose:

Gets the order of the curve (for example, 4 for cubic curves).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the order of the curve.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the order has not yet been set.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::ArcLength

GCoordinate ArcLength (GParametric uFrom, GParametric uTo) const
GCoordinate ArcLength () const

Interface Category:

API.

Purpose:

Returns the length along the loop between two specified parameters.
Returns the length along the entire loop, from its beginning point to its endpoint.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

GParametric uFrom -The parametric value of one endpoint of the section to be measured. It should not be less than the value returned by GetMinParameter.
GParametric uTo -The parametric value of the other endpoint of the section to be measured. It should not be greater than the value returned by GetMaxParameter.
Takes no parameters.

Return Value:

Returns the length of the curve along the specified portion of the loop.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The current implementation is likely to have accuracy problems with curves whose order is greater than 5.

Member Function: TLoop::ApproximateParameterFromArcLength

GParametric ApproximateParameterFromArcLength (GCoordinate length, GCoordinate tolerance =1.0e-5) const

Interface Category:

API.

Purpose:

Approximates the parameter of the point at a particular arc length along the loop.

Calling Context:

Call this function directly.

Parameters:

GCoordinate length -The distance, along the loop, of the point from the beginning of the loop.
GCoordinate tolerance =1.0e-5 -The accuracy of the root finder used internally to compute the result. Leave this parameter at the default value for most screen-sized data.

Return Value:

Returns the approximate parametric value of the point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines whether the loop geometry is empty (which it is when the TLoop is created with the default constructor).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the order of the curve is zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetNumberOfPoints

unsigned long GetNumberOfPoints () const

Interface Category:

API.

Purpose:

Gets the number of control points in the loop.

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. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetPoint

TGRPoint GetPoint (unsigned long i) const

Interface Category:

API.

Purpose:

Gets a specific control point.

Calling Context:

Call this function directly.

Parameters:

unsigned long i -The index into the array of control points. Zero returns the first point.

Return Value:

Returns the control point.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetPoints

void GetPoints (TGRPointArray & pts) const

Interface Category:

API.

Purpose:

Returns, in its argument, the complete array of control points.

Calling Context:

Call this function directly.

Parameters:

TGRPointArray & pts -The loop's control points, returned by reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetControlPolyline

void GetControlPolyline (TGPolyline &) const

Interface Category:

API.

Purpose:

Returns, in its parameter, the set of control points as a polyline.

Calling Context:

Call this function directly.

Parameters:

TGPolyline & -The loop's control points, returned by reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetMinParameter

GParametric GetMinParameter () const

Interface Category:

API.

Purpose:

Gets the parametric value that has been associated with the loop's beginning point. (This is not necessarily zero; it can be any value.)

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the minimum parametric value of the loop.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetMaxParameter

GParametric GetMaxParameter () const

Interface Category:

API.

Purpose:

Gets the parametric value that has been associated with the loop's endpoint.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the maximum parametric value of the loop.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetNumberOfKnots

unsigned long GetNumberOfKnots () const

Interface Category:

API.

Purpose:

Gets the number of knots in the knot vector. This is equal to the number of control points, plus the order of the curve.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the maximum parametric value of the loop.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::IsPinned

bool IsPinned () const

Interface Category:

API.

Purpose:

Returns true if the knot vector is pinned, meaning that the first and last control points are on the loop itself.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the knot vector is pinned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::IsBezier

bool IsBezier () const

Interface Category:

API.

Purpose:

Returns true if the loop represents a piecewise Bezier curve.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the knot vector defines a piecewise Bezier curve.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetNextDiscontinuity

unsigned long GetNextDiscontinuity (unsigned long startIndex, unsigned long discontinuity =0) const

Interface Category:

API.

Purpose:

Returns the knot vector index of the next discontinuity following the specified knot. The default is the next C0 discontinuity (a break in the loop), but you can specify discontinuities of a higher order. GetNextDiscontinuity returns the index of the first knot in a sequence of identical knots. (The order of the discontinuity determines how many identical knots are required.) Call GetKnot on the returned value to find the parameter of the curve at the discontinuity. Note that for a C0 break in the curve, the value returned by GetKnot(GetNextDiscontinuity()) is the start of the section of the curve after the break. Subtracting any amount from that parameter jumps to the section before the break. To find the control point associated with a C1 discontinuity, subtract 1 from the value returned by GetNextDiscontinuity. For a C0 discontinuity, GetNextDiscontinuity()-1 is the point before the break, and the following point is after the break. To skip from one discontinuity to the next, you can pass the value returned from the last call as the startIndex parameter.

Calling Context:

Call this function directly.

Parameters:

unsigned long startIndex -The index, into the knot vector, of the knot that precedes the discontinuity to be found.
unsigned long discontinuity =0 -The order of the discontinuity to be found. The value should be less than the order of the loop.

Return Value:

Returns the index (into the knot vector) of the next discontinuity. If no more discontinuities are found, the return value is the index of the last knot (in other words, GetNumberOfKnots()-1).

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized or the second parameter's value is greater than the order of the loop.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetKnot

GParametric GetKnot (unsigned long i) const

Interface Category:

API.

Purpose:

Gets the parametric value corresponding to the specified knot.

Calling Context:

Call this function directly.

Parameters:

unsigned long i -The index (into the knot vector) of the desired knot.

Return Value:

Returns the parametric value corresponding to the specified knot.

Exceptions:

Throws no exceptions, passes all exceptions through. However, an assertion fails in TGCurve if the loop is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetKnots

void GetKnots (TRawArray < GParametric > & knots) const

Interface Category:

API.

Purpose:

Returns, by reference in its parameter, the knot vector.

Calling Context:

Call this function directly.

Parameters:

TRawArray < GParametric > & knots -The array in which the function returns the knot vector.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::NearestParametric

GParametric NearestParametric (const TGPoint & test) const

Interface Category:

API.

Purpose:

Gets the parametric value of the point on the loop that is nearest to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & test -The point (on or off the loop) whose corresponding parameter is to be determined by the function.

Return Value:

Returns the parametric value closest to the specified point.

Exceptions:

Throws no exceptions in TLoop. The order must be initialized or an initialized assert occurs in TGCurve.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::GetSectionOfCurve

void GetSectionOfCurve (GParametric from, GParametric to, TGLoop & section) const

Interface Category:

API.

Purpose:

Gets the section of the loop between the two specified parametric values.

Calling Context:

Call this function directly.

Parameters:

GParametric from -The parametric value of the initial point of the section.
GParametric to -The parametric value of the endpoint of the section.
TGLoop & section -The section of loop to be returned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::DragPosition

void DragPosition (GParametric u, const TGPoint & toPoint, GParametric segmentMinimum =0.2, GParametric segmentMaximum =0.8)

Interface Category:

API.

Purpose:

Changes the loop shape so that at the specified parameter, it passes through the given point. Parts of the loop that lie outside the parametric range from segmentMinimum to segmentMaximum are not affected.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The parametric position which should be dragged to the new location.
const TGPoint & toPoint -The new location.
GParametric segmentMinimum =0.2 -The parametric value below which a point on the loop is not moved. Non-expert users are advised to use the default unless it is greater than u.
GParametric segmentMaximum =0.8 -The parametric value above which a point on the loop is not moved. Non-expert users are advised to use the default unless it is less than u.

Return Value:

None.

Exceptions:

An initialized assertion occurs in TGCurve if the order is uninitialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::DragTangent

void DragTangent (GParametric u, const TGPoint & toTangent, GParametric segmentMinimum =0.2, GParametric segmentMaximum =0.8)

Interface Category:

API.

Purpose:

Changes the loop shape so that at the specified parameter, the loop has the specified tangent. This function can simulate the rocker arm curve adjuster used in a well-known illustration application, with the added advantage that the adjustment can be made anywhere along the curve.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The parametric position which should be dragged so that the curve has the specified tangent at this point.
const TGPoint & toTangent -The new tangent at the specified parametric position.
GParametric segmentMinimum =0.2 -The parametric value below which a point on the loop is not moved. Non-expert users are advised to use the default unless it is greater than u.
GParametric segmentMaximum =0.8 -The parametric value above which a point on the loop is not moved. Non-expert users are advised to use the default unless it is less than u.

Return Value:

None.

Exceptions:

In TGCurve, an initialized assertion occurs if the order is uninitialized, and a parameter assertion occurs if the order is less than 2.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::ReverseDirection

void ReverseDirection ()

Interface Category:

API.

Purpose:

Flips the orientation of the loop's parameterization, by reversing the numbering of the control points and the intervals in the knot vector. In other words, the minimum parameter becomes the maximum parameter and vice versa.

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: TLoop::SetOrder

void SetOrder (unsigned long order)

Interface Category:

API.

Purpose:

Sets the order of the loop (for example, 4 for cubic curves). This changes the shape, but leaves the number of points intact.

Calling Context:

Call this function directly.

Parameters:

unsigned long order -The new order of the loop.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. The order must be initialized to be between 2 and the number of points, inclusive, or an assertion occurs in TGCurve.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::RaiseOrder

void RaiseOrder (unsigned long newOrder)

Interface Category:

API.

Purpose:

Raises the degree of the curve to the specified order. This does not change the shape, but increases the number of control points and knots.

Calling Context:

Call this function directly.

Parameters:

unsigned long newOrder -The degree to which the curve should be raised. If the value is less than the current order, the function does nothing.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This procedure generates spurious control points for splines that do not have closed end conditions (k-fold knots at each end).

Member Function: TLoop::ApproximateLowerOrder

void ApproximateLowerOrder (unsigned long newOrder, GCoordinate tolerance =0.2)

Interface Category:

API.

Purpose:

Approximate the loop with a lower-order one. Control points are added to the lower-order curve until the approximation falls within the specified tolerance. The curve in question is first made a Bezier curve.

Calling Context:

Call this function directly. It is also called by TModelDeformer::Deform.

Parameters:

unsigned long newOrder -The order of the new curve; must be greater than 2 but not greater than the current order.
GCoordinate tolerance =0.2 -The tolerance, specified in absolute coordinates (not relative to the size of the curve).

Return Value:

None.

Exceptions:

A parameter assertion in TGCurve ensures that newOrder is within range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::SetPoint

void SetPoint (unsigned long i, const TGRPoint & p)

Interface Category:

API.

Purpose:

Replaces control point number i with the specified point.

Calling Context:

Call this function directly.

Parameters:

unsigned long i -The index, into the array of control points, of the point to be replaced.
const TGRPoint & p -The new control point.

Return Value:

None.

Exceptions:

An initialized assertion in TGCurve checks whether the loop's order is initialized.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::SetPoints

void SetPoints (const TGRPointArray & controlPoints)

Interface Category:

API.

Purpose:

Replaces the control points with the specified ones. If the passed-in array does not have the same number of points as the existing curve, the knot vector is reset. Also, if the new number of points is less than the existing order of the curve, the order is lowered to the new number of points.

Calling Context:

Call this function directly.

Parameters:

const TGRPointArray & controlPoints -The new set of control points. There must be at least two points in the array.

Return Value:

None.

Exceptions:

An initialized assertion in TGCurve fails if there are fewer than two control points in the passed-in array.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::SetKnotScheme

void SetKnotScheme (TGCurve :: EndConditions theType =TGCurve :: kPinned)

Interface Category:

API.

Purpose:

Sets the knot vector to one of three standard schemes (pinned, floating, or Bezier), without doing any refinement. This function usually changes the shape of the curve.

Calling Context:

Call this function directly.

Parameters:

TGCurve :: EndConditions theType =TGCurve :: kPinned -The knot scheme. The default, kPinned, specifies knots at each end of the parametric range that have a multiplicity equal to the order. This means the first and last control points are on the loop, and it forces the curve to interpolate the first and last control points. The value kFloating causes uniform knot spacing, with the curve not reaching the first and last control points. The third option, kBezier, creates a piecewise Bezier knot vector.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::SetKnots

void SetKnots (const TRawArray < GParametric > & knots)

Interface Category:

API.

Purpose:

Resets the knot vector to the specified array. The data is copied into the curve, and must have the same number of knots as the curve's existing knot vector. No refinement or consistency checking is performed on this knot vector.

Calling Context:

Call this function directly.

Parameters:

const TRawArray < GParametric > & knots -The array to be copied into the knot vector.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::MoveKnot

void MoveKnot (unsigned long index, GParametric u)

Interface Category:

API.

Purpose:

Moves the specified knot to the point that has the specified parametric value. If u < knot[index -1] or u >knot[index + 1], the knot vector is sorted to accommodate the new value. This changes the shape of the curve.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index, into the knot vector, of the knot to be moved.
GParametric u -The parametric location to which the knot should be moved.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::InsertKnot

void InsertKnot (GParametric u)

Interface Category:

API.

Purpose:

Inserts a single new knot (and the corresponding control point) at the specified parametric location.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The parametric value of the point at which the knot is inserted. It must be greater than the parametric value of the loop's start point and less than the parametric value of the end point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::RefineUniform

void RefineUniform ()

Interface Category:

API.

Purpose:

Adds a new knot at the midpoint of each nonzero interval in the knot vector. No knots are inserted between the first n or the last n knots in the vector, where n is the order of the curve. This function does not change the shape of the curve, nor does it change the multiplicity of the knots.

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: TLoop::RefineToBeziers

void RefineToBeziers ()

Interface Category:

API.

Purpose:

Inserts additional knots so that all interior knots have a multiplicity equal to the order, minus 1. ( Interior knots exclude the first n and the last n knots in the vector, where n is the order of the curve.) This function turns the curve into a piecewise Bezier curve, but does not change shape of the curve.

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: TLoop::Refine

void Refine (const TRawArray < GParametric > & knots)

Interface Category:

API.

Purpose:

Inserts the given knots into the curve, adding new control points without modifying the curve's shape. This increases the flexibility of a curve.

Calling Context:

Call this function directly.

Parameters:

const TRawArray < GParametric > & knots -The parametric values of the locations at which the new knots are to be inserted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::RefineToPinned

void RefineToPinned ()

Interface Category:

API.

Purpose:

Adds knots to the beginning and end of the knot vector so that the control polygon is pinned to the ends of the curve (in other words, so that the curve intersects the first and last control points). This function is only applicable to curves with floating end conditions. The shape of the curve is not changed.

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: TLoop::IsConsistent

bool IsConsistent ()

Interface Category:

API.

Purpose:

Checks the curve for invalid knot vectors, nonpositive values of w, excessive values for the order of the curve, and too many or too few control points. If any offending condition is encountered, an error message is printed and the function returns false. Duplicate successive points cause a warning to be printed, but do not cause the function to return false.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if no offending condition is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::SetEOFill

void SetEOFill (bool EOFill)

Interface Category:

API.

Purpose:

Determines which one of two possible algorithms is used to fill the loop.

Calling Context:

Call this function directly.

Parameters:

bool EOFill -true if an even-odd rule should be used for determining what area is filled, and false if a nonzero winding rule should be used.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::operator=

TLoop & operator =(const TLoop & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TLoop & source -The object 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: TLoop::operator==

bool operator ==(const TLoop & source) const

Interface Category:

API.

Purpose:

Tests two TLoops for equality, by seeing whether their geometries and bundles are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TLoop & source -The loop to be compared with this one.

Return Value:

Returns true if this TLoop and the argument have equal geometries and bundles.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::operator!=

bool operator != (const TLoop &) const

Interface Category:

API.

Purpose:

Tests two TLoops for inequality, by seeing whether their geometries and bundles are different.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TLoop & source -The loop to be compared with this one.

Return Value:

Returns true if the geometries and bundles of this TLoop and the argument are not equal. or bundles.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLoop::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object 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.

Member Function: TLoop::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object 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: TLoop::Validate

void Validate ()

Interface Category:

API.

Purpose:

Makes sure that the graphic's bounds are up-to-date.

Calling Context:

Called by the Graphics system before returning bounds to the user. You should not need to call it directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function if their bounds behave differently from the base class.

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