Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MDrawable
Inherited By:
TCone3D
TCurve3D
TCylinder3D
TExtrusion3D
TGraphicHierarchy3D
TLine3D
TPolyline3D
TRevolution3D
TRoundedBox3D
TRoundedCylinder3D
TSphere3D
TSurface3D
TSweep3D
TTorus3D
Purpose:
MGraphic3D is an abstract base class derived from MDrawable. MDrawable provides the protocol for drawing a 2-D or 3-D graphic, and MGraphic3D provides the protocols for constructing and deleting a 3-D graphic, obtaining attribute information, transforming the graphic, finding the bounds of the graphic, and detecting whether the graphic has been selected by the user (hit detection).
The properties that determine how a 3-D graphic is drawn--such as color, shader, texture map, and frame pen--are called attributes. Attributes are encapsulated in the MGraphic3D's bundle, an object of the TGrafBundle3D class. Bundles are created and passed to a graphic to define the attributes for that graphic. If a graphic does not have a bundle, the default graphic state of the drawing port defines the graphic's attributes.
There are a number of MGraphic3D derived classes that are named for corresponding 3-D Geometry classes, to which they add attribute and transformation information. For example, the MGraphic3D derived class TCurve3D corresponds to the 3-D Geometry class TGCurve3D. Each graphics class is a wrapper for the corresponding geometry class; a TCurve3D has a TGCurve3D, but TCurve3D is not derived from TGCurve3D.
MGraphic3D maintains a private time stamp that gets updated every time an operation causes the graphic to change. GetTimeStamp retrieves the current time stamp, so that you can determine whether the object has changed. This approach uses lazy evaluation.
Instantiation:
Abstract class; do not allocate.
Deriving Classes:
Provided classes include TLine3D, TPolyline3D, TCurve3D, TSurface3D, TGraphicHierarchy3D, TCone3D, TCylinder3D, TExtrusion3D, TSphere3D, TTorus3D, TRevolution3D, TRoundedCylinder3D, and TBox3D. You can also create your own derived classes. Derived classes should override the pure virtual member functions: Draw, GetGeometricBounds, GetLooseFitBounds, and TransformBy. The default implementations of TranslateBy, ScaleBy, and RotateBy just call the TransformBy virtual member function, which is not the most efficient means of accomplishing simple transformations. Override these member functions if you want to achieve better performance.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ MGraphic3D ()
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: MGraphic3D::Draw
virtual void Draw (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws this MGraphic3D to the specified grafport.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.
Parameters:
- TGrafPort & port -The grafport 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:
This is a pure virtual function.
Member Function: MGraphic3D::GetGeometricBounds
virtual TGBox3D GetGeometricBounds () const
Interface Category:
API.
Purpose:
Returns this MGraphic3D's bounding box, without considering any volume added by the bundle.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.
Parameters:
Return Value:
Returns the bounding box of the graphic's geometry.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a pure virtual function.
Member Function: MGraphic3D::GetLooseFitBounds
virtual TGBox3D GetLooseFitBounds (const TGrafPort * port =NIL) const
Interface Category:
API.
Purpose:
Returns this MGraphic3D's bounding box, taking into account volume added by the bundle information.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.
Parameters:
- const TGrafPort * port =NIL -The graphics port whose bounds are to be computed.
Return Value:
Returns a bounding box.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::TransformBy
virtual void TransformBy (const TGrafMatrix3D & matrix)
Interface Category:
API.
Purpose:
Transforms this MGraphic3D's shape and position by applying the specified transformation matrix.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.
Parameters:
- const TGrafMatrix3D & matrix -The transformation matrix by which the graphic's points are multiplied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a pure virtual function.
Member Function: MGraphic3D::TranslateBy
virtual void TranslateBy (const TGPoint3D & delta)
Interface Category:
API.
Purpose:
Moves this MGraphic3D's position by the specified vector relative to its current position.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- const TGPoint3D & delta -The vector whose x-, y-, and z-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:
None.
Member Function: MGraphic3D::ScaleBy
virtual void ScaleBy (const TGPoint3D & scaleFactor, const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin)
Interface Category:
API.
Purpose:
Changes the size of this MGraphic3D by multiplying the coordinates by the specified scaling factor. It scales the graphic about the specified center of scale. The factor parameter is a vector of type TGPoint3D that allows non-uniform scaling using x-, y-, and z-coordinates of different values. For uniform scaling, the x-, y-, and z-coordinates should be the same.
The effect of negative scaling factors is the same as mirroring. (For example, scaling by -1.0 in the x-coordinate is like mirroring about the Y-Z plane.)
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- const TGPoint3D & scaleFactor -A vector of three values that determines the amount each coordinate is to be scaled.
- const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin -The center of the scaling.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::RotateBy
- virtual void RotateBy (GDegrees angle, TGrafMatrix3D :: EAxis axis)
- virtual void RotateBy (GDegrees angle, const TGLine3D & ray)
Interface Category:
API.
Purpose:
- Rotates this MGraphic3D counterclockwise around the specified axis by the specified angle. The right-handed coordinate system determines the orientation. That is, when you look from the positive axis towards the 3-D origin, a 90 degree counterclockwise rotation transforms one positive axis into the other.
- Rotates this MGraphic3D around the specified (arbitrary) axis by the specified angle. The direction of the vector (the axis parameter) determines the orientation of the rotation. The first point of the TGLine3D parameter is the origin; the second point determines the direction of the vector. The orientation of the rotation is counterclockwise around the vector.
Calling Context:
- Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
- Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- GDegrees angle -The degree of the specified rotation.
- TGrafMatrix3D :: EAxis axis -Determines which axis the specified rotation is to take place about. There are three enumerated types: kAboutXAxis, kAboutYAxis, or kAboutZAxis.
- GDegrees angle -The specified angle of rotation.
- const TGLine3D & ray -The arbitrary axis of rotation.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::AdoptBundle
virtual void AdoptBundle (TGrafBundle3D * adoptedBundle)
Interface Category:
API.
Purpose:
Adopts the specified bundle to determine this MGraphic3D's attributes.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::OrphanBundle
virtual TGrafBundle3D * OrphanBundle ()
Interface Category:
API.
Purpose:
Relinquishes knowledge of, and responsibility for, this MGraphic3D's bundle, returning it to the caller.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
Return Value:
Returns the orphaned bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::GetBundle
virtual const TGrafBundle3D * GetBundle () const
Interface Category:
API.
Purpose:
Returns a reference to the bundle, keeping it available to this MGraphic3D.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
Return Value:
Returns a constant pointer to the bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::operator==
bool operator ==(const MGraphic3D & source) const
Interface Category:
API.
Purpose:
Tests two MGraphic3Ds for equality. The base class tests whether the two bundles have equal contents and whether the time stamps are equal.
Calling Context:
Call this operator directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- const MGraphic3D & source -The graphic to be compared with this one.
Return Value:
Returns true if this MGraphic3D and the argument have equal bundles and time stamps.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes can override this function to add other tests. In particular, classes that encapsulate geometries check that the two geometries are equal.
Member Function: MGraphic3D::operator!=
bool operator != (const MGraphic3D & source) const
Interface Category:
API.
Purpose:
Tests two MGraphic3Ds for inequality. The base class tests whether the two bundles have unequal contents and whether the time stamps are unequal.
Calling Context:
Call this operator directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- const MGraphic3D & source -The graphic to be compared with this one.
Return Value:
Returns true if the bundles or time stamps of this MGraphic3d and the argument are not equal.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes can override this function to add other tests. In particular, classes that encapsulate geometries check that the two geometries are not equal.
Member Function: MGraphic3D::GetTimeStamp
TPseudoTimeStamp GetTimeStamp () const
Interface Category:
API.
Purpose:
Returns the object's time stamp. Time stamps are a quick and efficient way to determine whether two objects are equal. If the time stamps of the two objects are equal, then the objects are equal. However, if the time stamps are not equal, the objects might or might not be equal. Time stamps optimize the process of comparing two graphic hierarchies.
Calling Context:
Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
Return Value:
Returns the time stamp for this graphic.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::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: MGraphic3D::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.
- MGraphic3D ()
- MGraphic3D (TGrafBundle3D * adoptBundle)
- MGraphic3D (const MGraphic3D & copy)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a MGraphic3D with the specified attribute bundle.
- Copy constructor.
Calling Context:
- Called by the stream-in operators and directly. Note that this applies only to concrete derived classes because this class is abstract.
- Call this function directly. Note that this applies only to concrete derived classes because this class is abstract.
- Called to copy an object. Note that this applies only to concrete derived classes because this class is abstract.
Parameters:
- Takes no parameters.
- TGrafBundle3D * adoptBundle -The bundle to be adopted.
- const MGraphic3D & copy -The object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::operator=
MGraphic3D & operator =(const MGraphic3D & source)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const MGraphic3D & 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: MGraphic3D::UpdateTimeStamp
void UpdateTimeStamp ()
Interface Category:
API.
Purpose:
Updates the object's time stamp. Time stamps are a quick and efficient way to determine whether two objects are equal. If the time stamps of the two objects are equal, then the objects are equal. However, if the time stamps are not equal, the objects might or might not be equal. Time stamps optimize the process of comparing two graphic hierarchies.
Calling Context:
Called by the Graphics system (typically, by derived classes) when the object changes in any way. When implementing your own derived class, call this function directly whenever you change the object's data.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::ResetTimeStamp
void ResetTimeStamp ()
Interface Category:
API.
Purpose:
Sets the time stamp to zero.
Calling Context:
Called by the Graphics system.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::SetTimeStamp
void SetTimeStamp (const TPseudoTimeStamp & newTimeStamp)
Interface Category:
API.
Purpose:
Sets the time stamp to the specified value.
Calling Context:
Called by the Graphics system.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::GetAttributeState
virtual const TAttribute3DState * GetAttributeState () const
Interface Category:
API.
Purpose:
Gets the attribute bundle for this graphic.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the attribute bundle for this graphic.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::OrphanAttributeState
virtual TAttribute3DState * OrphanAttributeState ()
Interface Category:
API.
Purpose:
Orphans the attribute bundle for this graphic object.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the newly-orphaned attribute bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MGraphic3D::AdoptAttributeState
virtual void AdoptAttributeState (TAttribute3DState * state)
Interface Category:
API.
Purpose:
Causes this graphic object to adopt a given attribute bundle.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
If this graphic object already has an associated attribute bundle, that bundle is discarded and replaced with the new bundle.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.