Class: TSweep3D

Declaration: Sweep3D.h

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.

Member Function: TSweep3D::TSweep3D

  1. TSweep3D ()
  2. TSweep3D (const TSweep3D & source)
  3. TSweep3D (const TGCurve & contour, const TGCurve3D & trajectory, const TGPoint3D & initialContourXOrientation, const TGCurve & scaling =GetEmptySweepCurve (), const TGCurve & twist =GetEmptySweepCurve (), TGrafBundle3D * adoptedBundle =NIL)
  4. 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:

  1. Default constructor.
  2. Copy constructor.
  3. Creates a TSweep3D from the specified parameters.
  4. Creates a TSweep3D from the specified parameters, but a curve list is used instead of a contour TGCurve.

Calling Context:

  1. Called by the stream-in operators and directly.
  2. Called to copy an object.
  3. Call this function directly.
  4. 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::~TSweep3D

~ 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

  1. virtual void SetContour (const TGCurve & contour)
  2. virtual void SetContour (const TCurveList & curveList)

Interface Category:

API.

Purpose:

  1. Sets this TSweep3D's contour to the specified TGCurve.
  2. Sets this TSweep3D's contour to the specified list of TGCurves.

Calling Context:

  1. Call this function directly.
  2. Call this function directly.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.