Class ReferenceMaker

3DS Max Plug-In SDK

class ReferenceMaker : public Animatable

Description:

Any entity that makes references must be derived from this class. A reference creates a record of the dependency between a ReferenceMaker and a ReferenceTarget. 3ds max uses a messaging system to notify dependent entities about changes. This class has a method that receives the notifications its dependents send when they change. It has methods that return the number of references if has, and methods to get and set these references. Also, there are methods for creating, replacing and deleting the references. File input/output is handled via methods of this class (Load() and Save()).

See the Advanced Topics section on References for an overview of the 3ds max reference architecture.

Method Groups:

The hyperlinks below jump to the start of groups of related methods within the class:

Dependent Notification

Reference Access (Num/Get/Set)

Making / Replacing / Deleting References

Finding/Checking Reference Targets

Loading / Saving Methods

Methods:

Dependent Notification

Prototype:

virtual RefResult NotifyRefChanged(Interval changeInt, RefTargetHandle hTarget, PartID& partID,RefMessage message)=0;

Remarks:

Implemented by the Plug-In.

A plug-in which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged().

The plug-in developer usually implements this method as a switch statement where each case is one of the messages the plug-in needs to respond to.

Note: 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:

Interval changeInt

This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.

RefTargetHandle 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& 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.

RefMessage message

The message parameters passed into this method is the specific message which needs to be handled. See List of Reference Messages.

Return Value:

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.

Reference Access

3ds max manages the access to an items references by using a virtual array. If the plug-in makes references, it must implement these three methods handle access to its references: NumRefs(), GetReference(i), SetReference(i).

Prototype:

virtual int NumRefs();

Remarks:

Implemented by the Plug-In.

The plug-in implements this method to return the number of references it makes. NumRefs() indicates valid values for 'i' when doing a GetReference(i) or SetReference(i). An item may return different values at different times if the number of references is changing.

Return Value:

The number of references made by the plug-in.

Default Implementation:

{ return 0;}

Prototype:

virtual RefTargetHandle GetReference(int i);

Remarks:

Implemented by the Plug-In.

The plug-in 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. When the system calls this method, the plug-in returns its 'i th' reference.

Parameters:

int i

The virtual array index of the reference to get.

Return Value:

The reference handle of the 'i-th' reference.

Default Implementation:

{ return NULL; }

Prototype:

virtual void SetReference(int i, RefTargetHandle rtarg);

Remarks:

Implemented by the Plug-In.

The plug-in implements this method to store the reference handle passed into its 'i-th' reference. The plug-in simply keeps track of its references using an integer index for each one. When the system calls this method, the plug-in stores its 'i-th' reference.

Parameters:

int i

The virtual array index of the reference to store.

RefTargetHandle rtarg

The reference handle to store.

Default Implementation:

{}

Making / Replacing / Deleting References

Prototype:

RefResult MakeRefByID(Interval refInterval,int which, RefTargetHandle htarget)

Remarks:

Implemented by the System.

This method creates a reference between the object which calls the method, and the ReferenceTarget specified by the htarget parameter.

Note that this method calls SetReference() after the reference is made to initialize it.

Parameters:

refInterval

Currently, all plug-ins must use FOREVER for this interval.

Indicates the interval of time over which this reference is active. Outside this interval, the reference is not considered to be a dependency. This allows the plug-in to have dependent relationship over only portions of an entire animation time range. If a plug-in has a dependency over the entire animation it may use the pre-defined interval FOREVER for this parameter.

which

Indicates which virtual array index this newly created reference is assigned to. The system uses a virtual array mechanism to access the references an item has. The developer simply assigns an integer index to each reference.

hTarget

This parameter is the handle of the item we are making a reference to.

Return Value:

The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the reference was created and is registered by the reference target; otherwise REF_FAIL.

Prototype:

RefResult ReplaceReference(int which, RefTargetHandle newtarg, BOOL delOld=TRUE);

Remarks:

Implemented by the System.

This method is used to replace a reference, for example when cloning reference makers, to delete an old reference and make a new one.

Parameters:

int which

The virtual array index of the reference to replace.

RefTargetHandle newtarg

The new reference target

BOOL delOld=TRUE

If TRUE, the old reference is deleted.

Return Value:

This is usually REF_SUCCEED indicating the reference was replaced; otherwise REF_FAIL.

Prototype:

RefResult DeleteAllRefsFromMe();

Remarks:

Implemented by the System.

Deletes all references from this ReferenceMaker.

Return Value:

This is always REF_SUCCEED indicating the references were deleted.

Prototype:

virtual RefResult DeleteAllRefsToMe()

Remarks:

Implemented by the System.

This method deletes all the references to this reference maker/reference target. This also sends the REFMSG_TARGET_DELETED message to all dependents.

Return Value:

This is REF_SUCCEED if the references were deleted; otherwise it is REF_FAIL.

Prototype:

RefResult DeleteAllRefs();

Remarks:

Implemented by the System.

Deletes all references both to and from this item.

Return Value:

This is REF_SUCCEED if the references were deleted; otherwise it is REF_FAIL.

Prototype:

void DeleteMe();

Remarks:

Implemented by the System.

This deletes all reference to and from the item, sends REFMSG_TARGET_DELETED messages, handles UNDO, and deletes the object.

Prototype:

RefResult DeleteReference(int i);

Remarks:

Implemented by the System.

This method deletes the reference whose virtual array index is passed. The other reference indices are not affected, i.e. the number of references is not reduced nor are they re-ordered in any way. Note the system calls SetReference(i, NULL) to set that reference to NULL. Also, if this is the last reference to the item, the item itself is deleted by calling its DeleteThis() method.

Parameters:

int i

The virtual array index of the reference to delete.

Return Value:

This is REF_SUCCEED if the reference was deleted; otherwise it is REF_FAIL.

Prototype:

virtual BOOL CanTransferReference(int i)

Remarks:

This method is used internally. It is used by certain system objects that have references. A reference maker can choose not to let TransferReferences() affect it. Note that plug-ins probably should not use this.

Default Implementation:

{return TRUE;}

Finding/Checking Reference Targets

Prototype:

int FindRef(RefTargetHandle rtarg)

Remarks:

Implemented by the System.

This method returns the virtual array index of the reference target passed.

Parameters:

RefTargetHandle rtarg

The reference target to find the index of.

Return Value:

The virtual array index of the reference target to find. If the reference target is not found, -1 is returned.

Prototype:

virtual BOOL IsRefTarget();

Remarks:

This function differentiates things subclassed from ReferenceMaker from subclasses of ReferenceTarget. The implementation of this method (in ReferenceMaker) returns FALSE and its implementation in ReferenceTarget returns TRUE. This can be useful when tracing back up the reference hierarchy, to know when you run into something that was subclassed directly off of ReferenceMaker, and hence to stop the traversal at that point.

Default Implementation:

{ return FALSE; };

Prototype:

virtual BOOL IsRealDependency(ReferenceTarget *rtarg)

Remarks:

When a reference target's last "real" reference is deleted the target is deleted. Any leftover "non-real" reference makers will receive a REFMSG_TARGET_DELETED notification. This method returns TRUE if the reference dependency is "real". Otherwise it returns FALSE.

Certain references are not considered "real" dependencies. For instance, internally there are certain reference makers such as the object that handles editing key info in the motion branch. This object implements this method to return FALSE because it is not a "real" reference dependency. It's just needed while the editing is taking place. Plug-in developers dont' need to concern themselves with this method because it is used internally.

Parameters:

ReferenceTarget *rtarg

A pointer to the reference target.

Default Implementation:

{return TRUE;}

Loading / Saving Methods

Prototype:

virtual IOResult Save(ISave *isave);

Remarks:

Implemented by the Plug-In.

Called by the system to allow the plug-in to save its data.

Parameters:

ISave *isave

This pointer may be used to call methods to write data to disk. See the Advanced Topics section on Loading and Saving more an overview of the load/save process.

Return Value:

IO_OK

The result was acceptable - no errors.

IO_ERROR

This should be returned if an error occurred.

Default Implementation:

{ return IO_OK; }

Prototype:

virtual IOResult Load(ILoad *iload);

Remarks:

Implemented by the Plug-In.

Called by the system to allow the plug-in to load its data. See the Advanced Topics section on Loading and Saving more an overview of the load/save process.

Parameters:

ILoad *iload

This interface pointer may be used to call methods to read data from disk.

Return Value:

IO_OK

The result was acceptable - no errors.

IO_ERROR

This should be returned if an error occurred.

Default Implementation:

{ return IO_OK; }

Prototype:

virtual int RemapRefOnLoad(int iref)

Remarks:

This method is used when you have modified a ReferenceMaker to add or delete references, and are loading old files. It gets called during the reference mapping process, after the Load() method is called. You determine what version is loading in the Load(), and store the version in a variable which you can look at in RemapRefOnLoad() to determine how to remap references. The default implementation of this method just returns the same value it is passed, so you don't need to implement it unless you have added or deleted references from your class. This method makes it a lot easier to load old files when the reference topology has changed.

Parameters:

int iref

The input index of the reference.

Return Value:

The output index of the reference.

Default Implementation:

{ return iref; };

Prototype:

virtual void RescaleWorldUnits(float f);

Remarks:

This method is available in release 2.0 and later only.

This may be implemented to rescale the size of all world units in reference hierarchy. Developers must call

if (TestAFlag(A_WORK1))

return;

SetAFlag(A_WORK1);

before doing this on a reference hierarchy.

See the sub-section 'Scaling Parameter Values' in Updating MAX 1.0 Plug-Ins to work with MAX 2.0 for additional details.

Parameters:

float f

The scale factor.

Prototype:

virtual void SaveEnum(SaveEnumProc& sep, BOOL isNodeCall=0);

Remarks: