Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MGraphic3D
Inherited By:
None.
Purpose:
TSweep3D derives from MGraphic3D and allows you to easily construct 3-D shapes by using sweeps. A sweep is a 3-D surface formed by moving a contour (a 2-D curve) along a trajectory in space (a TGCurve3D). A great variety of useful 3-D shapes can be constructed from these primitives. For example, a circle can be moved along a linear trajectory to generate a cylinder; along a circular trajectory to generate a torus; or along a helical trajectory to generate a corkscrew shape. At each point along the trajectory, the contour is placed in a plane perpendicular to the trajectory.
The contour can be any TGCurve; it can be piecewise linear and even discontinuous. Although a TGCurve is always mathematically open (not a loop), you can simulate the appearance of a closed loop such as a circle by placing the curve's endpoints at the same location. A scaling function can be applied to the contour, to change its size as it moves along the trajectory. For example, if a triangle's size is scaled from zero to some larger number, and its trajectory is a line, the resulting sweep defines the surface of a tetrahedron. Similarly, a twist function can be applied to rotate the contour as it moves along the trajectory. You can even use multiple contours, specifying where each occurs along the trajectory; the sweep linearly interpolates the contours.
Note that the contour is a 2-D TGCurve, and in the 2-D coordinate system the y-axis points down, whereas in 3-D it points up. Thus, the contour appears upside down in the sweep as compared to its 2-D representation.
TSweep3D is a wrapper for TSurface3D that handles creating the shape without you understanding parametric space, NURB curves, knot vectors, or other related topics. However, TSweep3D::GetSurface lets you access the TSurface3D if you need greater control. Like TGSurface3D, a TSweep3D is parameterized with u and v parameters. In the case of TSweep3D, the u-direction corresponds to the contour, and the v-direction corresponds to the trajectory.
To predict how a sweep will look using inside and outside shaders, you need to know which side of the sweep is the interior and which is the exterior. The interior and exterior of a sweep are determined by the ant rule. Imagine the contour drawn on the ground. An ant walks along the contour curve from its first (lowest numbered) point to its last (highest numbered) point. The exterior of the sweep is the side to the left of the ant, and the interior is to the right. create the same basic shapes.
The TSweep3D member functions allow a great deal of versatility in creating shapes. Because the constructors for 2-D curves take all 2-D geometries, and the constructors for 3-D curves take a 3-D line, a 3-D polyline, or a 2-D curve, you can use TSweep3D to create surfaces that are based on any basic 2-D or 3-D geometric shape available in the Graphics system. However, TSweep3D is designed to be a base class, so you can extend it if needed. A number of protected member functions are designed to be overridden so that you can manipulate the contour and trajectory or create caps at either end of the trajectory.
There are other MGraphic3D derived classes for creating basic sweep shapes such as spheres, cones, rounded boxes, tori, revolutions, and extrusions. These convenience classes are not derived from TSweep3D, in order to prevent the flexible TSweep3D functions from warping the ostensible geometry into an unrecognizable or inconsistent state. Of course, you can also use TSweep3D to create these same basic shapes.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
None. Deriving classes can override any of the protected member functions ModifyTrajectory, ModifySweepingFrame, ModifyContour2D, ModifyContour3D, CreateCaps, and CreateInternalCaps.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TSweep3D ()
- TSweep3D (const TSweep3D & source)
- TSweep3D (const TGCurve & contour, const TGCurve3D & trajectory, const TGPoint3D & initialContourXOrientation, const TGCurve & scaling =GetEmptySweepCurve (), const TGCurve & twist =GetEmptySweepCurve (), TGrafBundle3D * adoptedBundle =NIL)
- TSweep3D (const TCurveList & curveList, const TGCurve3D & trajectory, const TGPoint3D & initialContourXOrientation, const TGCurve & scaling =GetEmptySweepCurve (), const TGCurve & twist =GetEmptySweepCurve (), TGrafBundle3D * adoptedBundle =NIL)
Interface Category:
API.
Purpose:
- Default constructor.
- Copy constructor.
- Creates a TSweep3D from the specified parameters.
- Creates a TSweep3D from the specified parameters, but a curve list is used instead of a contour TGCurve.
Calling Context:
- Called by the stream-in operators and directly.
- Called to copy an object.
- Call this function directly.
- Call this function directly.
Parameters:
- Takes no parameters.
- const TSweep3D & source -The sweep to be copied.
- const TGCurve & contour -The 2-D curve (which does not have to be closed or continuous) that is moved along the trajectory to define the surface of the sweep in the parametric u direction.
- const TGCurve3D & trajectory -The 3-D curve (which does not have to be closed or continuous) along which the contour is moved to define the surface of the sweep in the parametric v direction.
- const TGPoint3D & initialContourXOrientation -This vector is projected into the initial trajectory plane and (whatever its orientation) the projected vector becomes the contour's x-coordinate. The y-coordinate is perpendicular to that. This function is not currently used.
- const TGCurve & scaling =GetEmptySweepCurve () -Determines how to scale the contour along the trajectory. If empty (the default), a scaling factor of 1.0 is assumed. The y-coordinates should be greater than or equal to 0.0, and negative values are mirrored to positive ones internally. This must be a unique, continuous function.
- const TGCurve & twist =GetEmptySweepCurve () -Determines how to rotate or twist the contour along the trajectory. The contour is rotated in its contour plane (that is, in a plane perpendicular to the trajectory). The angle is specified in degrees, so y-coordinate values of the twisting function should be between -180.0 and 180.0 for a complete turn (or more, if you want to twist more than a complete turn). This must be a unique, continuous function.
- TGrafBundle3D * adoptedBundle =NIL -The attribute bundle to be adopted.
- const TCurveList & curveList -This curve list contains a number of contours (as TGCurves).
- const TGCurve3D & trajectory -The 3-D curve (which does not have to be closed or continuous) along which the contour is moved to define the surface of the sweep in the parametric v direction.
- const TGPoint3D & initialContourXOrientation -This vector is projected into the initial trajectory plane and (whatever its orientation) the projected vector becomes the contour's x-coordinate. The y-coordinate is perpendicular to that. This function is not currently used.
- const TGCurve & scaling =GetEmptySweepCurve () -Determines how to scale the contour along the trajectory. If empty (the default), a scaling factor of 1.0 is assumed. The y-coordinates should be greater than or equal to 0.0, and negative values are mirrored to positive ones internally. This must be a unique, continuous function.
- const TGCurve & twist =GetEmptySweepCurve () -Determines how to rotate or twist the contour along the trajectory. The contour is rotated in its contour plane (that is, in a plane perpendicular to the trajectory). The angle is specified in degrees, so y-coordinate values of the twisting function should be between -180.0 and 180.0 for a complete turn (or more, if you want to twist more than a complete turn). This must be a unique, continuous function.
- TGrafBundle3D * adoptedBundle =NIL -The attribute bundle to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
~ TSweep3D ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetEmptySweepCurve
static const TGCurve & GetEmptySweepCurve ()
Interface Category:
API.
Purpose:
Gets this Tsweep3D's empty sweep curve.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the value kSweepEmptyCurve.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::SetContour
- virtual void SetContour (const TGCurve & contour)
- virtual void SetContour (const TCurveList & curveList)
Interface Category:
API.
Purpose:
- Sets this TSweep3D's contour to the specified TGCurve.
- Sets this TSweep3D's contour to the specified list of TGCurves.
Calling Context:
- Call this function directly.
- Call this function directly.
Parameters:
- const TGCurve & contour -The new contour for the sweep.
- const TCurveList & curveList -The new list of contours for the sweep.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Before setting the contour(s), this function invalidates the sweep's surface.
Member Function: TSweep3D::SetTrajectory
virtual void SetTrajectory (const TGCurve3D & trajectory)
Interface Category:
API.
Purpose:
Sets this TSweep3D's trajectory to the specified TGCurve3D.
Calling Context:
Call this function directly.
Parameters:
- const TGCurve3D & trajectory -The new trajectory for the sweep.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Before setting the trajectory, this function invalidates the sweep's surface.
Member Function: TSweep3D::SetScalingCurve
virtual void SetScalingCurve (const TGCurve & scaling)
Interface Category:
API.
Purpose:
Sets this TSweep3D's scaling factor to the specified curve.
Calling Context:
Call this function directly.
Parameters:
- const TGCurve & scaling -The new scaling factor. This curve should represent a continuous, unique function.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Before setting the scaling factor, this function invalidates the sweep's surface.
Member Function: TSweep3D::SetTwistCurve
virtual void SetTwistCurve (const TGCurve & twist)
Interface Category:
API.
Purpose:
Sets this TSweep3D's rotation factor to the specified curve.
Calling Context:
Call this function directly.
Parameters:
- const TGCurve & twist -The new rotation (or twisting ) function. This curve should represent a continuous, unique function.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Before setting the twisting factor, this function invalidates the sweep's surface.
Member Function: TSweep3D::SetInitialContourXDirection
virtual void SetInitialContourXDirection (const TGPoint3D & direction)
Interface Category:
API.
Purpose:
Sets the orientation of this TSweep3D's contour with regards to the trajectory end plane.
Calling Context:
Call this function directly.
Parameters:
- const TGPoint3D & direction -The vector that is to be projected into the initial trajectory plane. The projected vector is the contour's x-coordinate. The y-coordinate is perpendicular to that.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetSurface
virtual const TGSurface3D * GetSurface () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's surface. If the value is NIL (after the surface is invalidated), the surface is reevaluated.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's surface.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetContourList
virtual const TCurveList * GetContourList () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's contour list.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's contour list.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetTrajectory
virtual const TGCurve3D * GetTrajectory () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's trajectory.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's trajectory.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetScalingCurve
virtual const TGCurve * GetScalingCurve () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's scaling curve.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's scaling curve.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetTwistCurve
virtual const TGCurve * GetTwistCurve () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's rotation (or twisting ) curve.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's twisting curve.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetInitialContourXDirection
virtual TGPoint3D GetInitialContourXDirection () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's initial contour x-direction vector.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's initial contour x-direction vector.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetMatrix
virtual const TGrafMatrix3D * GetMatrix () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's matrix, which is stored within the sweep as the sweep is transformed using the MGraphic transformations. This function might return a NIL pointer if there is no matrix stored.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the sweep's matrix.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::operator=
TSweep3D & operator =(const TSweep3D & Sweep)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TSweep3D & Sweep -The sweep 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: TSweep3D::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.
Member Function: TSweep3D::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: TSweep3D::GetGeometricBounds
virtual TGBox3D GetGeometricBounds () const
Interface Category:
API.
Purpose:
Gets this TSweep3D's bounding box, without considering any effect of the bundle attributes.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the bounding box of the sweep's geometry.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::TransformBy
virtual void TransformBy (const TGrafMatrix3D & matrix)
Interface Category:
API.
Purpose:
Transforms this TSweep3D's shape and position by applying the specified transformation matrix. (Note that TSweep3D inherits RotateBy, ScaleBy, and TranslateBy from MGraphic3D.)
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::Draw
virtual void Draw (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws this TSweep3D 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 grafport to draw the sweep to.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::ModifyTrajectory
virtual void ModifyTrajectory (TGCurve3D & trajectory) const
Interface Category:
API.
Purpose:
Modifies this TSweep3D's trajectory in a manner defined by the derived class. The standard preparation of a TSweep3D's trajectory can involve refining the trajectory curve and raising its order, so that the resulting surface can exhibit the same order of effect present in the scaling and twisting curves.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::ModifySweepingFrame
virtual void ModifySweepingFrame (GCoordinate u, TGPoint3D & tangent, TGPoint3D & normal, TGPoint3D & binormal, GCoordinate & curvature) const
Interface Category:
API.
Purpose:
Modifies the contour plane in a manner defined by the derived class. The sweeping frame is a set of three mutually orthogonal unit vectors that defines the contour plane and the orientation of the contour within that plane. The three vectors are the trajectory tangent, the trajectory normal, and the trajectory binormal. These vectors are relative to the u parametric value.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value on the curve for the tangent, normal, and binormal.
- TGPoint3D & tangent -The trajectory tangent that serves as the contour plane normal.
- TGPoint3D & normal -The trajectory normal that serves as the contour's coordinate system x-direction vector.
- TGPoint3D & binormal -The trajectory binormal that serves as the contour's coordinate system y-direction vector.
- GCoordinate & curvature
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::ModifyContour2D
virtual void ModifyContour2D (GCoordinate u, long numberPoints, TGRPoint * points) const
Interface Category:
API.
Purpose:
Modifies the contour in a manner defined by the derived class.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value.
- long numberPoints -The number of points in the contour.
- TGRPoint * points -The points in the contour.
Return Value:
None.
Exceptions:
Throws no exceptions, however an exception is thrown if you change the number of contour points in the point array.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::ModifyContour3D
virtual void ModifyContour3D (GCoordinate u, long numberPoints, TGRPoint3D * points, const TGPoint3D & tangent, const TGPoint3D & normal, const TGPoint3D & binormal, GCoordinate curvature) const
Interface Category:
API.
Purpose:
Modifies the contour in 3-D space, as defined by the derived class.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value on the curve for the tangent, normal, and binormal.
- long numberPoints -The number of points in the contour.
- TGRPoint3D * points -The points in the contour.
- const TGPoint3D & tangent -The trajectory tangent that serves as the contour plane normal.
- const TGPoint3D & normal -The trajectory normal that serves as the contour's coordinate system x-direction vector.
- const TGPoint3D & binormal -The trajectory binormal that serves as the contour's coordinate system y-direction vector.
- GCoordinate curvature -
Return Value:
None.
Exceptions:
Throws no exceptions, however an exception is thrown if you change the number of contour points in the point array.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::CreateCaps
virtual void CreateCaps (GCoordinate u, bool startCap, long numberPoints, const TGRPoint3D * points, const TGPoint3D & tangent, const TGPoint3D & normal, const TGPoint3D & binormal, GCoordinate curvature) const
Interface Category:
API.
Purpose:
Constructs a cap surface at either end of the trajectory, if implemented by the derived class. This function is called twice during each sweep evaluation: once at the start, with u set to 0.0 and startCap set to true, and then, with u set to whatever it should be at the end of the trajectory and startCap set to false. You can construct and cache cap surfaces here. (Note: the standard sweep does not provide caps.)
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value.
- bool startCap -
- long numberPoints -The number of points in the contour.
- const TGRPoint3D * points -The points in the contour.
- const TGPoint3D & tangent -The trajectory tangent at u.
- const TGPoint3D & normal -The trajectory normal at u.
- const TGPoint3D & binormal -The trajectory binormal at u.
- GCoordinate curvature -
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::CreateInternalCaps
virtual void CreateInternalCaps (GCoordinate u, long numberPoints, const TGRPoint3D * points, const TGPoint3D & tangent, const TGPoint3D & normal, const TGPoint3D & binormal, GCoordinate curvature) const
Interface Category:
API.
Purpose:
Constructs a cap surface at internal discontinuities in the trajectory curve, if implemented by the derived class. This function is called only if the trajectory is discontinuous. In that case, it is called twice for each discontinuity: once for the end of the previous trajectory segment and once for the beginning of the next trajectory segment.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value.
- long numberPoints -The number of points in the contour.
- const TGRPoint3D * points -The points in the contour.
- const TGPoint3D & tangent -The trajectory tangent at u.
- const TGPoint3D & normal -The trajectory normal at u.
- const TGPoint3D & binormal -The trajectory binormal at u.
- GCoordinate curvature -
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function does not do anything unless overridden.
Member Function: TSweep3D::GetTrajectoryArclength
virtual GCoordinate GetTrajectoryArclength (GCoordinate u) const
Interface Category:
API.
Purpose:
Computes the distance along the trajectory at a specified value of the u parameter.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate u -The parametric value at which the distance is to be computed.
Return Value:
Returns the distance along the trajectory at the parametric value.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::GetTrajectoryParametric
virtual GCoordinate GetTrajectoryParametric (GCoordinate arclength) const
Interface Category:
API.
Purpose:
Computes the parametric value at the specified distance along the trajectory.
Calling Context:
Call this function directly.
Parameters:
- GCoordinate arclength -The distance at which the parametric value is to be computed.
Return Value:
Returns the the parametric value at the specified distance.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::InvalidateSweep
void InvalidateSweep ()
Interface Category:
API.
Purpose:
Deletes this TSweep3D's current surface, forcing the surface to be generated anew the next time Draw or GetSurface is invoked.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSweep3D::EvaluateSweep
void EvaluateSweep ()
Interface Category:
API.
Purpose:
Generates this TSweep3D's surface.
Calling Context:
Called by the Graphics system when GetSurface or Draw is invoked.
Parameters:
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.
Copyright©1995 Taligent,Inc. All rights reserved.