Class PolyShape
See Also: Class ShapeObject, Class PolyLine, Class ShapeVSel, Class ShapeSSel, Class ShapePSel, Class ShapeHierarchy.
class PolyShape
Description:
A multi-polygon shape class. This class is used in the caching of bezier shapes. This is used for doing a one time interpolation of a bezier shape into a form that is the same shape but doesn't require any further interpolation. In this way the system can do the complex calculations once, store the shape into this PolyShape representation, and not have to go through the cubic spline calculations to figure out where the points are in the future. This class maintains an array of PolyLines.
This is used for example in the Extrude modifier. The first thing it does is generate a PolyShape from the bezier shape it is extruding. This PolyShape is then used to generate the mesh.
Method Groups:
The following hyperlinks take you to the start of groups of related methods within the class:
Constructors / Destructor / Init() / GetMatID()
SetNumLines() / NewShape() / NewLine()
Append / Insert / Delete / Reverse()
Bounding Box / InvalidateGeomCache() / InvalidateCapCache()
Render / Select / Snap / Transform
Data Members:
public:
int numLines;
The number of lines in the polyshape.
PolyLine *lines;
The array of lines.
DWORD flags;
These are not currently used.
Box3 bdgBox;
Stores the bounding box surrounding each PolyLine in the shape.
ShapeVSel vertSel;
The selected vertices.
ShapeSSel segSel;
The selected segments.
ShapePSel polySel;
The selected polygons.
DWORD selLevel;
The selection level. One of the following values:
SHAPE_OBJECT - Object level selection.
SHAPE_SPLINE - Spline level selection.
SHAPE_SEGMENT - Segment level selection.
SHAPE_VERTEX - Vertex level selection.
DWORD dispFlags;
Display attribute flags.
DISP_VERTTICKS - Display vertices as ticks.
DISP_SELVERTS - Display selected vertices.
DISP_SELSEGMENTS - Display selected segments.
DISP_SELPOLYS - Display selected polygons.
The following capping and cache information is used internally:
MeshCapInfo morphCap;
The morph cap information.
BOOL morphCapCacheValid;
Determines if the morph cap is valid.
MeshCapInfo gridCap;
The grid cap information.
BOOL gridCapCacheValid;
Determines if the grid cap is valid.
PatchCapInfo patchCap;
The patch cap information.
BOOL patchCapCacheValid;
Determines if the patch cap is valid.
ShapeHierarchy cachedHier;
Hierarchy cache.
BOOL hierCacheValid;
Determines if the hierarchy cache is valid.
Methods:
Constructors / Destructor / Init() / GetMatID
Prototype:
PolyShape();
Remarks:
Constructor. The number of lines is set to 0, the lines array is set to NULL, the flags and display flags are set to 0, the selection level is set to SHAPE_OBJECT, the geometry cache is invalidated, and the masterObject is set to NULL.
Prototype:
PolyShape(PolyShape& from);
Remarks:
Constructor. The PolyShape is initialized from the specified PolyShape.
Prototype:
~PolyShape();
Remarks:
Destructor.
Prototype:
void Init();
Remarks:
PolyShape::Init() is a special version used by the constructors and should not be called by plug-in developers. If you need to clear out a PolyShape use NewShape() described below.
Prototype:
MtlID GetMatID(int poly, int piece);
Remarks:
This method is available in release 3.0 and later only.
Returns the material ID for the specified segment of the specified poly.
Parameters:
int poly
The zero based index of the poly.
int piece
The zero based index of the segment.
SetNumLines() / NewShape() / NewLine()
Prototype:
BOOL SetNumLines(int count, BOOL keep = TRUE);
Remarks:
Sets the number of polygons used by the poly shape.
Parameters:
int count
The number of lines.
BOOL keep = TRUE
If TRUE any old lines are copied to the new storage; otherwise they are freed.
Return Value:
TRUE if the number of lines were set; otherwise FALSE.
Prototype:
void NewShape();
Remarks:
This deletes all the lines from the PolyShape and clears the shape out. Use this method instead of Init() above.
Prototype:
PolyLine* NewLine();
Remarks:
Creates a new PolyLine and appends it to the end of the list of lines maintained by this PolyShape.
Return Value:
The address of the newly added line.
Append / Insert / Delete / Reverse()
Prototype:
void Append(PolyLine &l);
Remarks:
Appends the specified PolyLine to the end of the lines list.
Parameters:
PolyLine &l
The PolyLine to append.
Prototype:
void Insert(int where, PolyLine& l);
Remarks:
Inserts the specified PolyLine at the location passed.
Parameters:
int where
The index into the lines list specifying where to insert the PolyLine.
PolyLine& l
The PolyLine to insert.
Prototype:
void Delete(int where);
Remarks:
Deletes the specified PolyLine from the lines list.
Parameters:
int where
The index into the lines list specifying which line to delete.
Prototype:
void Reverse(int poly, BOOL keepZero=FALSE);
Remarks:
Reverses the PolyLine whose index is passed.
Parameters:
int poly
The spline to reverse.
BOOL keepZero=FALSE
This should normally be passed as TRUE. If TRUE, and the polyline is closed, this method will make sure that vertex zero is the same on the reversed version as on the non-reversed version. Otherwise if passed as FALSE the last vertex becomes the first vertex, and the first vertex becomes the last. This is an important distinction for the lofter because it always wants vertex zero to be in the same place.
Prototype:
void Reverse(BitArray &reverse, BOOL keepZero=FALSE);
Remarks:
Reverses the splines of this shape if the corresponding bit in reverse is set. The BitArray has one bit for each polyline.
Parameters:
BitArray &reverse
If the bit is set the spline is reversed; otherwise it is left alone.
BOOL keepZero=FALSE
This should normally be passed as TRUE. If TRUE, and the polyline is closed, this method will make sure that vertex zero is the same on the reversed version as on the non-reversed version. Otherwise if passed as FALSE the last vertex becomes the first vertex, and the first vertex becomes the last. This is an important distinction for the lofter because it always wants vertex zero to be in the same place.
Bounding Box / InvalidateGeomCache() / InvalidateCapCache()
Prototype:
void BuildBoundingBox();
Remarks:
Builds a bounding box surrounding every line in the lines list. The bounding box is returned through the bdgBox data member.
Prototype:
Box3 GetBoundingBox(Matrix3 *tm=NULL);
Remarks:
Returns the bounding box of the PolyLines in this PolyShape. The optional TM allows the box to be calculated in any space.
Parameters:
Matrix3 *tm=NULL
The points of the PolyLines in this PolyShape are transformed by this matrix prior to the bounding box computations.
Prototype:
void GetDeformBBox(TimeValue t, Box3& box, Matrix3 *tm, BOOL useSel);
Remarks:
Computes the bounding box of this PolyShape.
Parameters:
TimeValue t
The time at which to evaluate the bounding box.
Box3& box
The result is stored here.
Matrix3 *tm
The points of each PolyLine in this PolyShape are deformed using this matrix.
BOOL useSel
If TRUE the box is computed about the selected vertices only; otherwise all points.
Prototype:
void InvalidateGeomCache(BOOL unused);
Remarks:
Invalidates the cache of each line in the PolyShape. The bounding box is set to empty. This method also invalidates the capping caches.
Parameters:
BOOL unused
This parameter is not used.
Prototype:
void InvalidateCapCache();
Remarks:
Invalidates the morph, and grid cap caches.
Render / Select / Snap / Transform
Prototype:
void Render(GraphicsWindow *gw, Material *ma, RECT *rp, int compFlags);
Remarks:
This method is used internally.
Prototype:
BOOL Select(GraphicsWindow *gw, Material *ma, HitRegion *hr,
int abortOnHit = FALSE);
Remarks:
This method is used internally.
Prototype:
void Snap(GraphicsWindow *gw, SnapInfo *snap, IPoint2 *p, Matrix3 &tm);
Remarks:
This method is used internally.
Prototype:
void Snap(GraphicsWindow *gw, SnapInfo *snap, IPoint2 *p,
Matrix3 &tm, DWORD flags);
Remarks:
This method is used internally.
Prototype:
void Transform(Matrix3 &tm);
Remarks:
Transforms the vertices of each PolyLine in this PolyShape by the specified matrix.
Parameters:
Matrix3 &tm
The transformation matrix.
Prototype:
int MakeCap(TimeValue t, MeshCapInfo &capInfo, int capType);
Remarks:
This method may be called to fill in the MeshCapInfo passed with the appropriate capping information. See Working with Patches for more details on capping. This method is used for meshes. The method below is used for patches.
Parameters:
TimeValue t
This should be passed as the current time. You may retrieve this using Interface::GetTime(). See Class Interface.
MeshCapInfo &capInfo
This information is filled in by this method. See Class MeshCapInfo.
int capType
The cap type. See List of Shape Capping Types.
Return Value:
Nonzero if the cap info was set up successfully; otherwise zero.
Prototype:
int MakeCap(TimeValue t, PatchCapInfo &capInfo);
Remarks:
This method may be called to fill in the PatchCapInfo passed with the appropriate capping information. This method is used for patches. Note that it is generally not recommended to try to create patch caps from PolyShapes. The patch cap uses bezier information, so it is much better to use a BezierShape to make a patch cap. It is very inefficient to do this with a PolyShape.
Parameters:
TimeValue t
This should be passed as the current time. You may retrieve this using Interface::GetTime(). See Class Interface.
PatchCapInfo &capInfo
This information is filled in by this method. See Class PatchCapInfo.
Return Value:
Nonzero if the cap info was set up successfully; otherwise zero.
Prototype:
int Make3DSCap(MeshCapInfo &capInfo, DWORD options = 0);
Remarks:
This method is used internally.
Prototype:
int MakeGridCap(MeshCapInfo &capInfo);
Remarks:
This method is used internally.
Prototype:
void Dump(TCHAR *title = NULL);
Remarks:
This may be called to display information about the PolyShape to the debug window via DebugPrint(). See Debugging.
Parameters:
TCHAR *title = NULL
A string to be display before the PolyShape data is displayed.
Prototype:
IOResult Save(ISave *isave);
Remarks:
This method is used internally in saving to the MAX file.
Prototype:
IOResult Load(ILoad *iload);
Remarks:
This method is used internally in loading from the MAX file.
Prototype:
void UpdateCachedHierarchy();
Remarks:
This method is used internally.
Prototype:
ShapeHierarchy &OrganizeCurves(TimeValue t, ShapeHierarchy *hier = NULL);
Remarks:
This methods looks at the shape organization, and puts together a shape hierarchy. This provides information on how the shapes are nested. For example on a donut object with two circles, this method determines which circle is inside the other one.
Parameters:
TimeValue t
This parameter is not used.
ShapeHierarchy *hier = NULL
If non-NULL the result is store here (in addition to being returned). See Class ShapeHierarchy.
Return Value:
The result is store here.
Prototype:
BitArray VertexTempSel(int poly);
Remarks:
Constructs a vertex selection list based on the current selection level of the specified poly. For example if the selection level is at object level all the bits are set. If the selection level is at vertex level only the selected vertex bits are set. See Class BitArray.
Parameters:
int poly
The poly whose selection level is constructed.
Prototype:
void UpdateSels();
Remarks:
This is a very important call to make. Whenever you have changed the PolyShape, for example after you are done adding polygons to the shape or have changed the number of points in a shape, you should call this method. This method updates a set of embedded selection set data within the shape. This selection set data tells what polygons are selected, what segments are selected, and what control points are selected. This resets the sizes of the selection bit arrays for this shape.
Prototype:
void ShallowCopy(PolyShape *ashape, ULONG_PTR channels);
Remarks:
This method is used internally in data flow evaluation in the pipeline.
Prototype:
void DeepCopy(PolyShape *ashape, ULONG_PTR channels);
Remarks:
This method is used internally in data flow evaluation in the pipeline.
Prototype:
void NewAndCopyChannels(ULONG_PTR channels);
Remarks:
This method is used internally in data flow evaluation in the pipeline.
Prototype:
void FreeChannels(ULONG_PTR channels, int zeroOthers=1);
Remarks:
This method is used internally in data flow evaluation in the pipeline.
Prototype:
PolyShape& operator=(PolyShape& from);
Remarks:
Assignment operator.
Prototype:
PolyShape& operator=(BezierShape& from);
Remarks:
Assignment operator. Note that this operator does not offer as much control as calling the method on the BezierShape itself named MakePolyShape(). That version allows you to specify the number of steps and an optimize parameter. These options are not available on this simple assignment operator.