This reference page is linked to from the following overview topics: Modifier Validity, World Space Modifier Plug-in Overview.
Detailed Description
- See also:
- Class
Modifier, Class IParamBlock, Class INode.
- Description:
- The SimpleWSMMod class supplies most
of the methods needed to implement a world space modifier.
To be a 'Simple' WSM modifier, the following assumptions are made:
The modifier only modifies the geometry channel.
The modifier uses an instance of a class derived from Deformer to do the modifying.
This class maintains a pointer to a parameter block. If the client of SimpleWSMMod uses a single parameter block then SimpleWSMMod can manage all the methods associated with SubAnims and References for the client.
If the client of SimpleWSMMod maintains several parameter blocks then the client must implement the methods NumSubs(), SubAnim(i), SubAnimName(i), NumRefs(), GetReference(i) and SetReference(i) and call the SimpleWSMMod methods when 'i' refers to the parameters maintained by SimpleWSMMod.
- Data Members:
- Clients of SimpleWSMMod should use the
following pointers when the references are created.
protected:
IParamBlock *pblock;
Pointer to a parameter block.
WSMObject *obRef;
Pointer to the world space modifier object referenced by the WSMModifier.
INode *nodeRef;
Pointer to the node in the scene referenced by the WSMModifier.
static IObjParam *ip;
Storage for the interface pointer.
static SimpleWSMMod *editMod;
Storage for the modifier currently being edited in the command panel.
Clients of SimpleWSMMod should use the following values as the reference indexes of the object, node and parameter block.
#define SIMPWSMMOD_OBREF 0
#define SIMPWSMMOD_NODEREF 1
#define SIMPWSMMOD_PBLOCKREF 2
#include <simpmod.h>
Public Member Functions |
|
| CoreExport | SimpleWSMMod () |
| virtual CoreExport | ~SimpleWSMMod () |
| ChannelMask | ChannelsUsed () |
| These are channels that the modifier needs
in order to perform its modification. |
|
| ChannelMask | ChannelsChanged () |
| These are the channels that the modifier
actually modifies. |
|
| CoreExport void | ModifyObject (TimeValue t, ModContext &mc, ObjectState *os, INode *node) |
| This is the method that actually modifies
the input object. |
|
| Class_ID | InputType () |
| This is the type of object that the modifier
knows how to modify. |
|
| CoreExport Interval | LocalValidity (TimeValue t) |
| This method returns the validity interval of
a modifier. |
|
| BOOL | ChangeTopology () |
| This method asks the question of an object
or modifier "Do you change topology"? An object or modifier returns
TRUE if it is capable of changing topology when its parameters are
being edited; otherwise FALSE. |
|
| CreateMouseCallBack * | GetCreateMouseCallBack () |
| This method allows the system to retrieve a
callback object used in creating an object in the 3D viewports.
|
|
| int | NumRefs () |
| Returns the total number of references this
ReferenceMaker can hold. |
|
| CoreExport RefTargetHandle | GetReference (int i) |
| Returns the 'i-th' reference. |
|
| int | NumSubs () |
| CoreExport Animatable * | SubAnim (int i) |
| CoreExport MSTR | SubAnimName (int i) |
| CoreExport RefResult | NotifyRefChanged (Interval changeInt, RefTargetHandle hTarget, PartID &partID, RefMessage message) |
| Receives and responds to messages. |
|
| CoreExport IParamArray * | GetParamBlock () |
| An object or modifier should implement this
method if it wishes to make its parameter block available for other
plug-ins to access it. |
|
| CoreExport int | GetParamBlockIndex (int id) |
| If a plug-in makes its parameter block
available (using
GetParamBlock()) then it will need to provide #defines for
indices into the parameter block. |
|
| CoreExport WSMObject * | GetWSMObject (TimeValue t) |
| CoreExport void | SimpleWSMModClone (SimpleWSMMod *smodSource) |
| CoreExport void | SimpleWSMModClone (SimpleWSMMod *smodSource, RemapDir &remap) |
| CoreExport void | BeginEditParams (IObjParam *ip, ULONG flags, Animatable *prev) |
| CoreExport void | EndEditParams (IObjParam *ip, ULONG flags, Animatable *next) |
| virtual Deformer & | GetDeformer (TimeValue t, ModContext &mc, Matrix3 &mat, Matrix3 &invmat)=0 |
| virtual void | InvalidateUI () |
| virtual Interval | GetValidity (TimeValue t) |
| virtual ParamDimension * | GetParameterDim (int pbIndex) |
| virtual MSTR | GetParameterName (int pbIndex) |
| virtual void | InvalidateParamMap () |
| CoreExport SvGraphNodeReference | SvTraverseAnimGraph (IGraphObjectManager *gom, Animatable *owner, int id, DWORD flags) |
Public Attributes |
|
| WSMObject * | obRef |
| INode * | nodeRef |
| IParamBlock * | pblock |
Static Public Attributes |
|
| static CoreExport IObjParam * | ip |
| static SimpleWSMMod * | editMod |
Protected Member Functions |
|
| virtual CoreExport void | SetReference (int i, RefTargetHandle rtarg) |
| Stores a
ReferenceTarget as its 'i-th' reference`. |
|
Constructor & Destructor Documentation
| CoreExport SimpleWSMMod | ( | ) |
| virtual CoreExport ~SimpleWSMMod | ( | ) | [virtual] |
Member Function Documentation
| ChannelMask ChannelsUsed | ( | ) | [inline, virtual] |
These are channels that the modifier needs in order to perform its modification.
This should at least include the channels specified in ChannelsChanged() but may include more. Note that ChannelsUsed() is called many times but the channels returned should not change on the fly.
- Returns:
- The channels required. See objectChannels.
- Sample Code:
-
{ return GEOM_CHANNEL|TOPO_CHANNEL; }
Implements Modifier.
| ChannelMask ChannelsChanged | ( | ) | [inline, virtual] |
These are the channels that the modifier actually modifies.
Note that ChannelsChanged() is called many times but the channels returned should not change on the fly.
- Returns:
- The channels that are changed. See objectChannels
Implements Modifier.
{ return PART_GEOM; }
| CoreExport void ModifyObject | ( | TimeValue | t, |
| ModContext & | mc, | ||
| ObjectState * | os, | ||
| INode * | node | ||
| ) | [virtual] |
This is the method that actually modifies the input object.
This method is responsible for altering the object and then updating the validity interval of the object to reflect the validity of the modifier.
- Parameters:
-
t The time at which the modification is being done. mc A reference to the ModContext. os The object state flowing through the pipeline. This contains a pointer to the object to modify. node The node the modifier is applied to. This parameter is always NULL for Object Space Modifiers and non-NULL for World Space Modifiers (Space Warps). This is because a given WSM is only applied to a single node at a time whereas an OSM may be applied to several nodes. This may be used for example by particle system space warps to get the transformation matrix of the node at various times.
- See also:
- The topic on Modifiers in the Programmers Guide.
Implements Modifier.
| Class_ID InputType | ( | ) | [inline, virtual] |
This is the type of object that the modifier knows how to modify.
Simple modifiers that just modify points of an object can operate on generic 'Deformable' objects. Deformable objects are any type of object that has points. A modifier could also work on a particular type of object such as a TriObject or PatchObject.
- Returns:
- The Class_ID of the item. You can request any Class_ID for your input type. For example, Class_ID(OMNI_LIGHT_CLASS_ID, 0). See List of Class_IDs.
Implements Modifier.
{return defObjectClassID;}
| CoreExport Interval LocalValidity | ( | TimeValue | t | ) | [virtual] |
This method returns the validity interval of a modifier.
It is simply the combination of the validity of all the modifier's parameters. It's used to determine when to cache in the pipeline, but is not directly responsible for determining when ModifyObject() is called. ModifyObject() is called when the pipeline needs to be evaluated either because someone sent a REFMSG_CHANGE message or the validity of the object does not include the current time.
- If a modifier is not animated it's OK to simply return FOREVER from
- this method. In the case where the modifier changes because a
user changes a non-animated control in the user interface (for
instance a check box), you can cause reevaluation by notifying your
dependents of the change, i.e.:
NotifyDependents(FOREVER, PART_ALL, REFMSG_CHANGE);
- Parameters:
-
t The time to calculate the Interval.
- See also:
- Advanced Topics on Intervals.
Reimplemented from Modifier.
| BOOL ChangeTopology | ( | ) | [inline, virtual] |
This method asks the question of an object or modifier "Do you change topology"? An object or modifier returns TRUE if it is capable of changing topology when its parameters are being edited; otherwise FALSE.
When an item is selected for editing, and there is a modifier in the pipeline that depends on topology, the system calls this method to see if it may potentially change the topology. If this method returns TRUE the system will put up a warning message indicating that a modifier exists in the stack that depends on topology.
Reimplemented from BaseObject.
{return FALSE;}
| CreateMouseCallBack* GetCreateMouseCallBack | ( | ) | [inline, virtual] |
This method allows the system to retrieve a callback object used in creating an object in the 3D viewports.
This method returns a pointer to an instance of a class derived from CreateMouseCallBack. This class has a method proc() which is where the programmer defines the user/mouse interaction during the object creation phase.
- Returns:
- A pointer to an instance of a class derived from CreateMouseCallBack.
Implements BaseObject.
{return NULL;}
| int NumRefs | ( | ) | [inline, virtual] |
Returns the total number of references this ReferenceMaker can hold.
The plugin implements this method to indicate the total number of of references it can make. This includes all references whether they are NULL (inactive) or non-NULL (active) at the time when this method is called. A plugin can hold a variable number of references, thus the return value of this method is not to be cached and reused by client code.
- Returns:
- The total number of references this plugin can hold. The default implementation is return 0.
Reimplemented from ReferenceMaker.
{return 3;}
| CoreExport RefTargetHandle GetReference | ( | int | i | ) | [virtual] |
Returns the 'i-th' reference.
The plugin implements this method to return its 'i-th' reference. The plug-in simply keeps track of its references using an integer index for each one. This method is normally called by the system.
- Parameters:
-
i - The index of the reference to retrieve. Valid values are from 0 to NumRefs()-1.
- Returns:
- The reference handle of the 'i-th' reference. Note that different calls to this method with the same 'i' value can result in different reference handles being retrieved, as the plugin changes the scene objects it references as its 'i-th' reference.
Reimplemented from ReferenceMaker.
Reimplemented in SimpleWSMMod2.
| virtual CoreExport void SetReference | ( | int | i, |
| RefTargetHandle | rtarg | ||
| ) | [protected, virtual] |
Stores a ReferenceTarget as its 'i-th' reference`.
The plugin implements this method to store the reference handle passed to it as its 'i-th' reference. In its implementation of this method, the plugin should simply assign the reference handle passed in as a parameter to the member variable that holds the 'i-th' reference. Other reference handling methods such as ReferenceMaker::DeleteReference(), or ReferenceMaker::ReplaceReference() should not be called from within this method. The plugin itself or other plugins should not call this method directly. The system will call this method when a new reference is created or an existing one is replaced by calling ReferenceMaker::ReplaceReference().
- Parameters:
-
i - The index of the reference to store. Valid values are from 0 to NumRefs()-1. rtarg - The reference handle to store.
Reimplemented from ReferenceMaker.
Reimplemented in SimpleWSMMod2.
| int NumSubs | ( | ) | [inline, virtual] |
- Remarks:
- The system uses a virtual array mechanism to access the sub-anims of a plug-in. This method returns the total number of sub-anims maintained by the plug-in. If a plug-in is using a parameter block to manage its parameters it should just return 1 for all the parameters directed by the parameter block.
- Returns:
- The number of sub-anims used by the plug-in.
- Default Implementation:
- { return 0; }
Reimplemented from Animatable.
{return 1;}
| CoreExport Animatable* SubAnim | ( | int | i | ) | [virtual] |
- Remarks:
- This method returns a pointer to the 'i-th' sub-anim. If a plug-in is using a parameter block to manage all its parameters it should just return a pointer to the parameter block itself from this method. This method may return NULL so developers need to check the return value before calling other sub anim methods (such as SubAnimName()).
- Parameters:
-
i This is the index of the sub-anim to return.
- Default Implementation:
- { return NULL };
Reimplemented from Animatable.
Reimplemented in SimpleWSMMod2.
| CoreExport MSTR SubAnimName | ( | int | i | ) | [virtual] |
- Remarks:
- This method returns the name of the 'i-th' sub-anim to appear in track view. The system has no idea what name to assign to the sub-anim (it only knows it by the virtual array index), so this method is called to retrieve the name to display. Developer need to make sure the 'i-th' SubAnim() is non-NULL or this method will fail.
- Parameters:
-
i The index of the parameter name to return
- Returns:
- The name of the 'i-th' parameter.
Reimplemented from Animatable.
| CoreExport RefResult NotifyRefChanged | ( | Interval | changeInt, |
| RefTargetHandle | hTarget, | ||
| PartID & | partID, | ||
| RefMessage | message | ||
| ) | [virtual] |
Receives and responds to messages.
A plugin which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged(). The plugin developer usually implements this method as a switch statement where each case is one of the messages the plugin needs to respond to. The Method StdNotifyRefChanged calls this, which can change the partID to new value. If it doesn't depend on the particular message& partID, it should return REF_DONTCARE.
- For developer that need to update a dialog box with data about an object you reference note the following related to this method: This method may be called many times. For instance, say you have a dialog box that displays data about an object you reference. This method will get called many time during the drag operations on that object. If you updated the display every time you'd wind up with a lot of 'flicker' in the dialog box. Rather than updating the dialog box each time, you should just invalidate the window in response to the NotifyRefChanged() call. Then, as the user drags the mouse your window will still receive paint messages. If the scene is complex the user may have to pause (but not let up on the mouse) to allow the paint message to go through since they have a low priority. This is the way many windows in 3ds Max work.
- Parameters:
-
changeInt - This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval. hTarget - This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message. partID - This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages. message - The message parameters passed into this method is the specific message which needs to be handled.
- Returns:
- The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.
Implements ReferenceMaker.
| CoreExport IParamArray* GetParamBlock | ( | ) | [virtual] |
An object or modifier should implement this method if it wishes to make its parameter block available for other plug-ins to access it.
The system itself doesn't actually call this method. This method is optional.
- Returns:
- A pointer to the item's parameter block. See Class IParamArray.
Reimplemented from BaseObject.
| CoreExport int GetParamBlockIndex | ( | int | id | ) | [virtual] |
If a plug-in makes its parameter block available (using GetParamBlock()) then it will need to provide #defines for indices into the parameter block.
These defines should not be directly used with the parameter block but instead converted by this function that the plug-in implements. This way if a parameter moves around in a future version of the plug-in the #define can be remapped. A return value of -1 indicates an invalid parameter id.
- Parameters:
-
id The parameter block id. See Parameter Block IDs.
- Returns:
- The parameter block index or -1 if it is invalid.
Reimplemented from BaseObject.
| CoreExport WSMObject* GetWSMObject | ( | TimeValue | t | ) |
- Remarks:
- Implemented by the System.
Evaluates the node reference and returns the WSM object. If you look in /MAXSDK/SAMPLES/HOWTO/MISC/SIMPMOD.CPP you'll see that all this method does is call EvalWorldState() on the Node reference.
- Parameters:
- TimeValue t
The time to get the WSMObject.
When clients of SimpleWSMMod are cloning themselves, they should call this method on the clone to copy SimpleWSMMod's data.
void SimpleWSMModClone(SimpleMod *smodSource);
Clients of SimpleWSMMod probably want to override these. If they do they should call these from within their methods.
void BeginEditParams(IObjParam *ip, ULONG flags,Animatable prev);
void EndEditParams(IObjParam *ip, ULONG flags,Animatable *next);
| CoreExport void SimpleWSMModClone | ( | SimpleWSMMod * | smodSource | ) |
| CoreExport void SimpleWSMModClone | ( | SimpleWSMMod * | smodSource, |
| RemapDir & | remap | ||
| ) |
| CoreExport void BeginEditParams | ( | IObjParam * | ip, |
| ULONG | flags, | ||
| Animatable * | prev | ||
| ) | [virtual] |
- Remarks:
- This method is called by the system when the user may edit the item's (object, modifier, controller, etc.) parameters.
- Parameters:
-
ip Interface pointer. The developer can use it to call methods such as AddRollupPage(). Note that this pointer is only valid between BeginEditParams() and EndEditParams(). It should not be used outside this interval. flags Describe which branch of the command panel or dialog the item is being edited in. The following are possible values:
BEGIN_EDIT_CREATE
Indicates an item is being edited in the create branch.
BEGIN_EDIT_MOTION
Indicates a controller is being edited in the motion branch.
BEGIN_EDIT_HIERARCHY
Indicates a controller is being edited in the Pivot subtask of the hierarchy branch.
BEGIN_EDIT_IK
Indicates a controller is being edited in the IK subtask of the hierarchy branch.
BEGIN_EDIT_LINKINFO
Indicates a controller is being edited in the Link Info subtask of the hierarchy branch.
prev Pointer to an Animatable object. This parameter may be used in the motion and hierarchy branches of the command panel. This pointer allows a plug-in to look at the ClassID of the previous item that was being edited, and if it is the same as this item, to not replace the entire UI in the command panel, but simply update the values displayed in the UI fields. This prevents the UI from 'flickering' when the current item begins its edit. For example, if you are in the motion branch and are looking at an item's PRS controller values, and then select another item that is displayed with a PRS controller, the UI will not change - only the values displayed in the fields will change. If however you selected a target camera that has a lookat controller (not a PRS controller) the UI will change because a different set of parameters need to be displayed. Note that for items that are edited in the modifier branch this field can be ignored.
Reimplemented from Animatable.
| CoreExport void EndEditParams | ( | IObjParam * | ip, |
| ULONG | flags, | ||
| Animatable * | next | ||
| ) | [virtual] |
- Remarks:
- This method is called when the user is finished editing an objects parameters. The system passes a flag into the EndEditParams() method to indicate if the rollup page should be removed. If this flag is TRUE, the plug-in must un-register the rollup page, and delete it from the panel.
- Parameters:
-
ip An interface pointer. The developer may use the interface pointer to call methods such as DeleteRollupPage().
flags The following flag may be set:
END_EDIT_REMOVEUI
If TRUE, the item's user interface should be removed.
next Animatable pointer. Can be used in the motion and hierarchy branches of the command panel. It allows a plug-in to look at the ClassID of the next item that was being edited, and if it is the same as this item, to not replace the entire UI in the command panel. Note that for items that are edited in the modifier branch this field can be ignored.
Reimplemented from Animatable.
| virtual Deformer& GetDeformer | ( | TimeValue | t, |
| ModContext & | mc, | ||
| Matrix3 & | mat, | ||
| Matrix3 & | invmat | ||
| ) | [pure virtual] |
- Remarks:
- This method is used to retrieve the callback object that will handle the deformation.
- Parameters:
- TimeValue t
Specifies the time the modification is being performed.
ModContext &mc
A reference to the ModContext.
Matrix3& mat
A reference to a matrix that describes the space the modification is supposed to happen in. This is computed from the ModContext matrix and the controllers controlling the gizmo and center of the modifier. The plug-in developers job is simply to transform each point to be deformed by this matrix before it performs its own deformation to the point. After the modifier applies its own deformation to the point, the developer transforms the point by the inverse of this matrix (passed below).
Matrix3& invmat
This is the inverse of the matrix above. See the comment above for how this is used.
- Returns:
- A C++ reference to the deformer callback object.
- See also:
- The Advanced Topics section on the Geometry Pipeline System.
Implemented in SimpleOSMToWSMMod, and SimpleOSMToWSMMod2.
| virtual void InvalidateUI | ( | ) | [inline, virtual] |
- Remarks:
- 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.
- Example:
- If the plug-in uses a parameter map for handling its UI, it may
call a method of the parameter map to handle this:
pmapParam->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
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 );
{}
| virtual Interval GetValidity | ( | TimeValue | t | ) | [inline, virtual] |
- Remarks:
- The SimpleWSMMod class calls this method to retrieve the validity interval of the modifier. The modifier provides this interval by starting an interval at FOREVER and intersecting it with each of its parameters validity intervals.
- Parameters:
- TimeValue t
The time to compute the validity interval.
- Default Implementation:
- {return FOREVER;}
- Returns:
- The validity interval of the modifier.
- See also:
- The Advanced Topics section on Intervals.
Reimplemented in SimpleOSMToWSMMod, and SimpleOSMToWSMMod2.
{return FOREVER;}
| virtual ParamDimension* GetParameterDim | ( | int | pbIndex | ) | [inline, virtual] |
- Remarks:
- Returns the dimension of the parameter whose index is passed.
- Parameters:
- int pbIndex
The index of the parameter.
- Default Implementation:
- {return defaultDim;}
- Returns:
- The dimension of the parameter.
- See also:
- Class ParamDimension.
{return defaultDim;}
| virtual MSTR GetParameterName | ( | int | pbIndex | ) | [inline, virtual] |
- Remarks:
- Returns the name of the parameter whose index is passed.
- Parameters:
- int pbIndex
Index of the parameter.
- Default Implementation:
- {return MSTR(_M("Parameter"));}
- Returns:
- The name of the parameter.
{return MSTR(_M("Parameter"));}
| virtual void InvalidateParamMap | ( | ) | [inline, virtual] |
| CoreExport SvGraphNodeReference SvTraverseAnimGraph | ( | IGraphObjectManager * | gom, |
| Animatable * | owner, | ||
| int | id, | ||
| DWORD | flags | ||
| ) | [virtual] |
- Remarks:
- This method is available in release 3.0 and later only.
This method traverses the graph of objects in the 3ds Max scene, adding desired objects to the schematic view. Developers can specialize this behaviour by overriding this method and adding whatever objects are interesting to the schematic view. Objects are added to the schematic view by calling IGraphObjectManager::AddAnimatable(...). Reference lines are added to the schematic view by calling IGraphObjectManager::AddReference(...). Implementers of this method should call it recursively to process other objects in the scene.
See Class IGraphObjectManager.
- Parameters:
-
gom Points to the schematic view window manager. owner The owning animatable. id This is usually the sub-anim number (but can actually be any value the developer chooses). flags See List of Schematic %View AddAnimatable Flags.
- Returns:
- A SvGraphNodeReference object.
Reimplemented from Modifier.
Member Data Documentation
SimpleWSMMod* editMod
[static] |
