Class SimpleShape
See Also: Class ShapeObject, Class IParamBlock, Class PolyShape, Class Interval, Working with Shapes and Splines.
class SimpleShape : public ShapeObject
Description:
This class defines a simple shape object to make procedural shape primitives easier to create. For example, the 3ds max Helix plug-in is derived from this class. There are a set of mandatory and optional methods to implement.
Revised for 3ds max 2.0 SimpleShape-based objects have a new 'General' rollup, which contains renderable shape options: Renderable checkbox, Thickness spinner, and a Mapping coords checkbox. These are supported automatically. To support the new features of the renderable splines, the derived class of SimpleShape needs to work with a few new methods -- see SimpleShapeClone() and ReadyGeneralParameters() below for details.
Data Members:
public:
IParamBlock *pblock;
The parameter block for managing the shape's parameters.
static IObjParam *ip;
This data member is available in release 2.0 and later only.
This is the interface pointer stored by the class.
static HWND hGenParams;
This data member is available in release 2.0 and later only.
The window handle to the 'General' rollup.
static BOOL dlgRenderable;
This data member is available in release 2.0 and later only.
The 'Renderable' flag in the 'General' rollup.
static float dlgThickness;
This data member is available in release 2.0 and later only.
The 'Thickness' setting in the 'General' rollup.
static BOOL dlgGenUVs;
This data member is available in release 2.0 and later only.
The 'Generate Mapping Coords' flag in the 'General' rollup.
PolyShape shape;
The shape cache.
Interval ivalid;
The validity interval for the shape cache.
BOOL suspendSnap;
A flag to suspend snapping used during the creation process.
static SimpleShape *editOb;
The shape that is currently being edited in the command panel.
static ISpinnerControl *thickSpin;
Points to the spinner control used for the thickness parameter.
Methods:
Prototype:
SimpleShape();
Remarks:
Constructor.
Prototype:
~SimpleShape();
Remarks:
Destructor.
Clients of SimpleShape need to implement these methods:
Prototype:
virtual void BuildShape(TimeValue t, PolyShape& ashape) = 0;
Remarks:
Implemented by the Plug-In.
This method is called to build the shape at the specified time and store the result into the PolyShape passed.
Parameters:
TimeValue t
The time to build the shape.
PolyShape& ashape
The built shape is stored here.
Prototype:
virtual BOOL ValidForDisplay(TimeValue t) = 0;
Remarks:
Implemented by the Plug-In.
This method indicates if the shape may be displayed at the time passed. At certain times, for certain shapes, the shape may not be in a displayable form. For example, the size of the shape may go to zero at a certain point and would be inappropriate to display.
Parameters:
TimeValue t
The time to check.
Return Value:
TRUE if the shape may be displayed at the specified time; otherwise FALSE.
Prototype:
virtual void InvalidateUI()
Remarks:
Implemented by the Plug-In.
This is called if the user interface parameters needs to be updated because the user moved to a new time. The UI controls must display values for the current time.
If the plug-in uses a parameter map for handling its UI, it may call a method of the parameter map to handle this: ipmapParam->Invalidate();
If the plug-in does not use parameter maps, it should call the SetValue() method on each of its controls that display a value, for example the spinner controls. This will cause to the control to update the value displayed. The code below shows how this may be done for a spinner control. Note that ip and pblock are assumed to be initialized interface and parameter block pointers
(IObjParam *ip, IParamBlock *pblock).
float newval;
Interval valid=FOREVER;
TimeValue t=ip->GetTime();
// Get the value from the parameter block at the current time.
pblock->GetValue( PB_ANGLE, t, newval, valid );
// Set the value. Note that the notify argument is passed as FALSE.
// This ensures no messages are sent when the value changes.
angleSpin->SetValue( newval, FALSE );
Default Implementation:
{}
Prototype:
virtual ParamDimension *GetParameterDim(int pbIndex)
Remarks:
Implemented by the Plug-In.
This method returns the parameter dimension of the parameter whose index is passed.
Parameters:
int pbIndex
The index of the parameter to return the dimension of.
Return Value:
Pointer to a ParamDimension. See Class ParamDimension.
Default Implementation:
{return defaultDim;}
Prototype:
virtual TSTR GetParameterName(int pbIndex)
Remarks:
Implemented by the Plug-In.
Returns the name of the parameter whose index is passed.
Parameters:
int pbIndex
The index into the parameter block of the parameter to return the name of.
Default Implementation:
{return TSTR(_T("Parameter"));}
For procedural shapes the following methods must be implemented:
Prototype:
virtual Point3 InterpCurve3D(TimeValue t, int curve, float param, int ptype = PARAM_SIMPLE) = 0;
Remarks:
Implemented by the Plug-In.
This method returns a point interpolated on the entire curve.
Parameters:
TimeValue t
The time to evaluate.
int curve
The index of the curve to evaluate.
float param
The 'distance' along the curve where 0 is the start and 1 is the end.
int ptype=PARAM_SIMPLE
The parameter type for spline interpolation. See List of Parameter Types for Shape Interpolation.
Return Value:
The interpolated point on the curve.
Prototype:
virtual Point3 TangentCurve3D(TimeValue t, int curve, float param, int ptype = PARAM_SIMPLE) = 0;
Remarks:
Implemented by the Plug-In.
This method returns a tangent vector interpolated on the entire curve.
Parameters:
TimeValue t
The time at which to evaluate the curve.
int curve
The index of the curve to evaluate.
float param
The 'distance' along the curve where 0.0 is the start and 1.0 is the end.
int ptype=PARAM_SIMPLE
The parameter type for spline interpolation. See List of Parameter Types for Shape Interpolation.
Return Value:
The tangent vector.
Prototype:
virtual float LengthOfCurve(TimeValue t, int curve) = 0;
Remarks:
Implemented by the Plug-In.
Returns the length of the specified curve.
Parameters:
TimeValue t
The time at which to compute the length.
int curve
The index of the curve.
The following methods are optional.
You should strongly consider implementing these, because the default implementations just do the bare-minimum job. It is often best to break up a curve into several smaller pieces than to have one single long curve. For example, the user may use a step setting of 10, and will expect to see a reasonable approximation of the shape using such a step setting. A curve that is too long will not be accurately represented by such a steps setting as it will be too course. Chopping your curve up into manageable pieces will make things look better.
Prototype:
virtual int NumberOfPieces(TimeValue t, int curve)
Remarks:
Implemented by the Plug-In.
Returns the number of sub-curves in a curve.
Parameters:
TimeValue t
The time at which to check.
int curve
The index of the curve.
Default Implementation:
{ return 1; }
Prototype:
virtual Point3 InterpPiece3D(TimeValue t, int curve, int piece,
float param, int ptype=PARAM_SIMPLE)
Remarks:
Implemented by the Plug-In.
This method returns the interpolated point along the specified sub-curve.
Parameters:
TimeValue t
The time to evaluate the sub-curve.
int curve
The curve to evaluate.
int piece
The sub-curve (segment) to evaluate.
float param
The position along the sub-curve to return where 0.0 is the start and 1.0 is the end.
int ptype=PARAM_SIMPLE
The parameter type for spline interpolation. See List of Parameter Types for Shape Interpolation.
Return Value:
The point in world space.
Default Implementation:
{ return InterpCurve3D(t, curve, param); }
Prototype:
virtual Point3 TangentPiece3D(TimeValue t, int curve,
int piece, float param, int ptype=PARAM_SIMPLE)
Remarks:
Implemented by the Plug-In.
Returns the tangent vector on a sub-curve at the specified 'distance' along the curve.
Parameters:
TimeValue t
The time to evaluate the sub-curve.
int curve
The curve to evaluate.
int piece
The sub-curve (segment) to evaluate.
float param
The position along the sub-curve to return where 0.0 is the start and 1.0 is the end.
int ptype=PARAM_SIMPLE
The parameter type for spline interpolation. See List of Parameter Types for Shape Interpolation.
Return Value:
The tangent vector.
Default Implementation:
{ return TangentCurve3D(t, curve, param, ptype); }
Prototype:
void ReadyGeneralParameters();
Remarks:
This method is available in release 2.0 and later only.
To support the new features of the renderable splines, in the derived class's constructor, call ReadyGeneralParameters(). This will set up the general parameters in the base class to the proper defaults. Failure to make this call will cause SimpleShape-based objects to be created with default general parameters rather than those of the previously-created object.
Prototype:
void SimpleShapeClone(SimpleShape *sshpSource);
Remarks:
This method is available in release 2.0 and later only.
To support the new features of the renderable splines, the derived class of SimpleShape needs to, in the Clone method, call this method. This will insure that the base class parameters are copied to the cloned object. Failure to make this call will cause cloned SimpleShape-based objects to revert to the default rendering parameters.
Parameters:
SimpleShape *sshpSource
The source shape for the clone.
Prototype:
virtual MtlID GetMatID(TimeValue t, int curve, int piece);
Remarks:
This method is available in release 3.0 and later only.
Returns the material ID of the specified segment of the specified curve or the shape.
Parameters:
TimeValue t
The time at which to return the material ID
int curve
The zero based index of the curve.
int piece
The zero based index of the segment of the curve.