List of Reference Messages and their PartID parameters

3DS Max Plug-In SDK

This section describes some of the common messages used by references and the meaning of the PartID parameter associated with these messages.

Some messages are sent by the system while others are sent by the plug-in. Each method may need to pass along additional information so the reference maker may process the message. This information is passed in the PartID parameter. The meaning of the information stored in the PartID is specific to the message sent along with it.

Note that not all messages use the PartID parameter (in fact most don't). In these cases the PartID will be set to 0. If the plug-in is sending the message, it should set the PartID to 0 if not used. In the cases where the PartID is used, it is documented below.

Developers who define their own reference messages should do so using a value greater than:

#define REFMSG_USER 0x00010000

The system uses numbers less than this value.

REFMSG_CHANGE

This is the most common message sent. Any time a reference target changes in a way that may affect items which reference it, this message should be sent.

Note the following for the partIDs that are sent during this message:

PART_HIDESTATE -- This is a special partID sent by visibility controllers when they change the hidden in viewport state.

PART_TM -- This is passed in partID when the reference is to a node in the scene and its transformation matrix has changed.

PART_OBJECT_TYPE -- This is sent if the object type changes.

Objects and Modifier set the PartID to the channel which changed. (See the section on the Geometric Pipeline for more information on channels). There are several specific PartID referring to channels. These are:

$image\bullet.gif$ PART_TOPO = TOPO_CHANNEL

$image\bullet.gif$ PART_GEOM = GEOM_CHANNEL

$image\bullet.gif$ PART_TEXMAP = TEXMAP_CHANNEL

$image\bullet.gif$ PART_MTL = MTL_CHANNEL

$image\bullet.gif$ PART_SELECT = SELECT_CHANNEL

$image\bullet.gif$ PART_SUBSEL_TYPE = SUBSEL_TYPE_CHANNEL

$image\bullet.gif$ PART_DISPLAY = DISP_ATTRIB_CHANNEL

$image\bullet.gif$ PART_VERTCOLOR = VERTCOLOR_CHANNEL

REFMSG_TARGET_DELETED

This message is sent when a reference target is deleted. This allows the reference maker to handle this condition if it depends on the deleted item. For example this is sent when the item you are referencing is actually deleted and you need to set your pointer to the item to NULL.

REFMSG_IS_OK_TO_CHANGE_TOPOLOGY

This message is sent to ask a reference maker if it is okay to change the topology of a node. If any dependents have made topology-dependent modifiers, they should return REF_FAIL. A return of REF_SUCCEED means that the answer is YES, it is okay to change the topology. A return of REF_FAIL means that the answer is NO, it is not okay to change the topology.

REFMSG_NODE_LINK

This message is sent by a node when it has a child linked to it or unlinked from it.

REFMSG_NODE_NAMECHANGE

This message is sent by a node when its name has been changed. For example, the path controller displays the name of the node in the scene which it follows. It responds to this message by changing the name displayed in the UI.

REFMSG_OBREF_CHANGE

This message is sent by a node (or derived object) when the object it references changes. Note: This message is no longer used. It is basically synonymous with REFMSG_SUBANIM_STRUCTURE_CHANGED.

REFMSG_MODIFIER_ADDED

This message is sent by a derived object when a modifier is a added or deleted.

REFMSG_CONTROLREF_CHANGE

This message is sent when an animatable switches controllers for one of its parameters.

REFMSG_GET_PARAM_NAME

A parameter block sends this message to its client when it needs the name of the i-th parameter. The PartID is set to a pointer to a GetParamName structure. See the Advanced Topics section on Parameter Blocks for more details.

REFMSG_GET_PARAM_DIM

A parameter block sends this message to its client when it needs to know the dimension type of the 'i-th' parameter. The PartID is set to a pointer to a GetParamDim structure. See the Advanced Topics section on Parameter Blocks for more details.

REFMSG_GET_CONTROL_DIM

A controller can send this to its client to get its parameters dimension. It should set PartID to a ParamDimension.

REFMSG_TM_CHANGE

This message is sent by a node when its transformation matrix has changed because it was evaluated at a different time. Normally this isn't necessary - anyone depending on the node's TM would have a validity interval that reflected the validity of the TM. The axis system doesn't store a validity interval so this message is needed for it.

REFMSG_RANGE_CHANGE

A node sends this message when its animation range changes.

REFMSG_LINEHEIGHT_CHANGE

This message is sent to the track view when an animatable's line height changes.

REFMSG_BECOMING_ANIMATED

A controller should send this message to the track view when it becomes animated. If the user has the animated only filter on then the track view will display this item.

REFMSG_SUBANIM_STRUCTURE_CHANGED

If a plug-in has a variable number of parameters this message may be used. This is intended mainly for the track view to tell it to re-generate the view below the message sender's level.

REFMSG_REF_DELETED

This message is sent when a target has had a reference deleted.

REFMSG_REF_ADDED

This message is sent when a target has had a reference added.

REFMSG_BRANCHED_HISTORY_CHANGED

This message is sent by an object that provides branching in the history to notify it that the structure of the branches has changed.

REFMSG_NODEINSELSET_CHANGED

The selection set sends this notification when it receives a REFMSG_CHANGE from an item in the selection set. The selection set doesn't propagate the REFMSG_CHANGE message.

REFMSG_TEST_DEPENDENCY

This method is used to see if this reference target depends on something. In 3ds max 2.0 and later, if the partID is nonzero, the dependency test will include child nodes. Otherwise, child nodes will not be considered dependents. See ReferenceTarget::BeginDependencyTest().

REFMSG_WANT_SHOWPARAMLEVEL

A Parameter block sends this to its client to ask if it should display a distinct "Parameters" level in the track view hierarchy. A pointer to a boolean is passed in for PartID: set this to the desired answer. The default is NO -- in this case the message doesn't need to be responded to.

REFMSG_BEFORE_PASTE

REFMSG_NOTIFY_PASTE

These messages are sent before and after a paste has been done. Sent as partID is a pointer to a data structure containing three RefTargetHandle's: the reference maker, the old target, and the new target. The message is sent to the reference maker initially.

REFMSG_UV_SYM_CHANGE

This message is sent when a UV Generator changes symmetry, so interactive texture display updates.

REFMSG_GET_NODE_NAME

The first node that gets this message will fill in the TSTR which partID points to with its name and stop the message from propagating.

REFMSG_SEL_NODES_DELETED

This message is sent by the selection set whenever it has just deleted nodes.

REFMSG_PRENOTIFY_PASTE

This message is sent before a reference target is pasted. It is sent by the target about to be replaced.

REFMSG_SHAPE_START_CHANGE

Sent when a shape enters a state where it'll be changing a lot and it would be a good idea for anybody using it for mesh generation to suppress updates.

REFMSG_SHAPE_END_CHANGE

Sent to terminate the above state.

REFMSG_TEXMAP_REMOVED

A texture map has been removed. This tells the Materials Editor to remove it from the viewport if it is active.

REFMSG_FLAG_NODES_WITH_SEL_DEPENDENTS

Sent by an unselected node to see if any selected nodes depend on it. The partID parameter points to a boolean. If a selected node receives this message it should set the boolean to true and return REF_STOP.

REFMSG_CONTAINED_SHAPE_POS_CHANGE

This messages is sent by objects which contain shapes when the position changes.

REFMSG_CONTAINED_SHAPE_SEL_CHANGE

This messages is sent by objects which contain shapes when the selection changes.

REFMSG_CONTAINED_SHAPE_GENERAL_CHANGE

This messages is sent by objects which contain shapes when the selection, or the position changes.

REFMSG_LOOPTEST

This tests for a cyclic reference. It will return REF_FAIL if there is a loop.

REFMSG_BEGIN_EDIT

This is used by modifiers to indicate when they are beginning an edit. For example in SimpleMod::BeginEditParams() this message is sent.

REFMSG_END_EDIT

This is used by modifiers to indicate when they are ending an edit. For example in SimpleMod::EndEditParams() this message is sent. Typically what a modifier will do while it is being edited it will have its LocalValidity() return NEVER so that a cache is built before it. This will ensure it is more interactive while it is being edited. When this message is sent to indicate the edit is finished the system can discard the cache.

REFMSG_MOD_DISPLAY_ON

This is used by modifiers to indicate that their apparatus (gizmo) is displayed. For example in SimpleMod::BeginEditParams() this message is sent.

REFMSG_MOD_DISPLAY_OFF

This is used by modifiers to indicate that their apparatus (gizmo) is no longer displayed.

REFMSG_MOD_EVAL

This is sent by a modifier to cause its ModApp to call Eval() on the modifier. If a modifier wants its ModifyObject() method to be called it can send this message.

The PartID should contain the bits that specify which channels are to be evaluated, for example PART_GEOM|PART_TOPO or ALL_CHANNELS. The interval passed should be set to Interval(t, t), where t is the time the to evaluate. Note that before NotifyDependents() returns, ModifyObject() will be called.

REFMSG_SELECT_BRANCH

This message is available in release 2.0 and later only.

When an object receives this message it should do whatever it needs to do (usually select the appropriate sub-object) to make the dependent object be the object returned from Object::GetPipeBranch(). The partID will point to an INode pointer that will be filled in by the first node to receive this message. Thus, when an object that supports branching in the history receives this message it selects the target that sent the message.

REFMSG_MOUSE_CYCLE_STARTED

This message is available in release 2.0 and later only.

This messages is sent to dependents of the transform controllers of selected objects when the user begins a mouse transformation in the viewports (move/rotate/scale).

REFMSG_MOUSE_CYCLE_COMPLETED

This message is available in release 2.0 and later only.

This message is sent to dependents of the transform controllers of selected objects when the user ends a mouse transformation in the viewports (move/rotate/scale).

REFMSG_CHECK_FOR_INVALID_BIND

This message is available in release 2.0 and later only.

Sent by a node to other nodes (which depend on that node) when the user attempts to link another node to a node. The partID parameter contains a pointer to the new parent node.

REFMSG_OBJECT_CACHE_DUMPED

This message is available in release 2.0 and later only.

Sent when a cache is dumped in the pipeline. A REFMSG_CHANGE message used to be sent, however that was misleading since the object itself didn't change even though any old object pointer has become invalid. For example, if a path controller depends on a spline object and that object dumps some caches in the pipeline, the path controller hasn't actually changed.

REFMSG_SFX_CHANGE

This message is available in release 3.0 and later only.

Sent by Atmospheric Effects or Render Effects when they make or delete a reference to a node. When Atmospherics or Effects add or delete a gizmo they should send this message via NotifyDependents().

REFMSG_OBJECT_REPLACED

This message is available in release 3.0 and later only.

Sent when objects are replaced from another scene (File->Replace). Other objects referencing the object that is replaced may want to perform some validity checking; this message is more specific than REFMSG_SUMANIM_STRUCTURE_CHANGED

REFMSG_NODE_WIRECOLOR_CHANGED

This message is available in release 4.0 and later only.

Sent when nodes wireframe color is changed.

REFMSG_NODE_WSCACHE_UPDATED

This message is sent from the node (without propagation) whenever the world state cache gets updated (e.g. when the pipeline gets reevaluated).

REFMSG_NODE_HANDLE_CHANGED

After merging nodes into the scene, all merged objects will receive this reference notification. The PartID will be a pointer to a merge manager interface that you can use to see if a specific handle was converted and convert between the old and the new handle; IMergeManager* pMergeManager = (IMergeManager*)partID;

REFMSG_NUM_SUBOBJECTTYPES_CHANGED

This message is available in release 4.0 and later only.

This message is sent to indicate that the sub-object types have changed and that the StackView should be updated.

REFMSG_NODE_MATERIAL_CHANGED

This message is sent from the node whenever the node material is replaced by a different material.

REFMSG_SUBANIM_NUMBER_CHANGED

This message is available in release 4.0 and later only.

This notification is sent to dependents when a subanim changes the ordering. It is used by things like scripted plugins and custom attributes to inform expression and wire controllers when the user redefines the ordering of parameters so these controllers can keep pointing at the correct parameter. The PartID is a Tab<DWORD>* in which each DWORD contains an old-to-new mapping with the LOWORD() = old subanim number and the HIWORD() = new subanim number A new subanim ID of -1 implies the subanim was removed. See MAXSDK\SAMPLES\CONTROLLERS\EXPRCTRL.CPP for example use.

REFMSG_TAB_ELEMENT_NULLED

This message is available in release 4.0 and later only.

Sent by a ParamBlock2 to its owner whenever a reftarg element in a Tab<> parameter is forcibly deleted and the reference set to NULL (typically for INODE_TABs when a scene node is deleted in the viewport).

REFMSG_GET_NODE_HANDLE

This message is available in release 4.0 and later only.

The first node that gets this message will fill in the ULONG which partID points to with its handle and stop the message from propogating.

REFMSG_END_MODIFY_PARAMS

This message is available in release 4.0 and later only.

This will cause Animatable::EndEditParams() to be called on the object displayed in the modify panel.

REFMSG_BEGIN_MODIFY_PARAMS

This message is available in release 4.0 and later only.

This will cause Animatable::BeginEditParams() to be called on the object displayed in the modify panel.

REFMSG_MODAPP_DELETING