Classes | Public Member Functions | Protected Member Functions | Friends

ReferenceTarget Class Reference

This reference page is linked to from the following overview topics: Lesson 3: the reference system, Lesson 4: Animation Controllers, Lesson 6: Parameter Blocks, Incremental Improvements, Plug-in Upgrade Guide, SuperClassID Cleanup, Reference System Best Practices, Parameter Types, Saving, Loading, and Deleting Parameter Blocks, Getting the Nodes that Reference an Object, Reference System, How Plug-ins Observe Reference Targets, Writing Reference Makers, Writing Reference Targets, Reference Messages, Node Monitors, Managing Variable Number of References, Reference Hierarchy Functions, Reference Object Lifetime Management, Counting Observers of a Reference Target, Cloning Reference Targets, Guidelines for Changing the Reference Structure, Editing Material and Texture Parameters, MAXScript Values, Instantiating Wrappers, Extracting Wrapped Objects, Referencing a Global Instance of a Non-plug-in Class, Creating Parameter Blocks, Implementing Clone in a Plug-in, Ring Array Classes.


Search for all occurrences

Detailed Description

A scene entity that is being owned and listened to by other scene entities.

ReferenceTarget is the base class for scene entities that allow to be referenced by instances of class ReferenceMaker. Most plugins are derived from this class.

This class exposes methods for sending notification messages to its dependent ReferenceMaker objects, enumerating their dependents, etc.

Note that RefTargetHandle is a typename for pointers to an object of type ReferenceTarget.

#include <ref.h>

Inheritance diagram for ReferenceTarget:
Inheritance graph
[legend]

List of all members.

Classes

class   RefList
  Stores the list of dependents for a ReferenceTargets, i.e. the list of references to a ReferenceTarget.
class   RefListItem
  Reference list link-node.

Public Member Functions

virtual CoreExport void  GetClassName (MSTR &s)
  Retrieves the name of the plugin class.
virtual CoreExport SClass_ID  SuperClassID ()
  Retrieves a constant representing the type of the plugin.
Testing for Class / Cyclic References/ Dependencies
virtual BOOL  IsRefTarget ()
  Checks if this is a ReferenceTarget.
CoreExport RefResult  TestForLoop (Interval refInterval, RefMakerHandle hmaker)
  Tests for a cyclical reference.
CoreExport BOOL  HasDependents ()
  Checks if a ReferenceTarget has references.
CoreExport BOOL  HasRealDependents ()
  Checks if this has Real (Strong) Dependents.
void  BeginDependencyTest ()
  Starts Dependency Test.
BOOL  EndDependencyTest ()
  Ends Dependency Test.
Adding / Deleting / Transferring References
virtual void  RefAdded (RefMakerHandle rm)
  Called after a reference is made to a target.
virtual void  RefAddedUndoRedo (RefMakerHandle rm)
  Called after a reference is made to a target because of undo or redo.
virtual void  RefDeleted ()
  Called after a references to this is deleted.
virtual void  RefDeletedUndoRedo ()
  Called after a references to this is deleted because of undo or redo.
CoreExport RefResult  DeleteAllRefsToMe ()
  Deletes all references to this ReferenceTarget.
CoreExport RefResult  TransferReferences (RefTargetHandle oldTarget, BOOL delOld=FALSE)
  Transfers all the references from oldTarget to this.
Dependent Enumeration
CoreExport int  DoEnumDependents (DependentEnumProc *dep)
  Begins an enumeration that searches back in the dependency network.
virtual CoreExport RefTargetHandle  Clone (RemapDir &remap)
  This method is used by 3ds Max to clone an object.
virtual CoreExport void  BaseClone (ReferenceTarget *from, ReferenceTarget *to, RemapDir &remap)
  This method copies base class data from an object to its clone.
Dependent Notification
virtual CoreExport RefResult  NotifyDependents (Interval changeInt, PartID partID, RefMessage message, SClass_ID sclass=NOTIFY_ALL, BOOL propagate=TRUE, RefTargetHandle hTarg=NULL)
  Notify all dependent RefMakers concerned with the message.
void  FlagDependents (TimeValue t, PartID which=PART_PUT_IN_FG)
  This sends the REFMSG_FLAGDEPENDENTS message up the pipeline.
virtual void  NotifyForeground (TimeValue t)
  This method is called to flag dependents into the FG.
virtual void  NotifyTarget (int message, ReferenceMaker *hMaker)
  Sends messages to ReferenceTargets.
Methods introduced in 3DS Max version 4.2
virtual CoreExport void *  GetInterface (ULONG id)
  Inherited from Animatable.
virtual CoreExport BaseInterface GetInterface (Interface_ID id)
  Inherited from Animatable.

Protected Member Functions

virtual CoreExport int  DoEnumDependentsImpl (DependentEnumProc *dep)
  Method to perform an enumeration on a ReferenceTarget.

Friends

class  DependentIterator
class  DeleteRefRestore
class  MakeRefRestore
class  ReferenceMaker

Construction, destruction of instances

virtual CoreExport  ~ReferenceTarget ()=0
  Destructor.
CoreExport  ReferenceTarget ()
  Constructor.
virtual CoreExport RefResult  AutoDelete ()
  Deletes the object when it has no more real dependents.
CoreExport RefResult  MaybeAutoDelete ()
  Deletes the object when it has no more real dependents.

Constructor & Destructor Documentation

virtual CoreExport ~ReferenceTarget ( ) [protected, pure virtual]

Destructor.

Instances of class ReferenceTarget and classes derived from it should be deleted by calling ReferenceTarget::MaybeAutoDelete() or ReferenceMaker::DeleteMe() on them, rather then calling the delete operator. This will ensure that the object drops all references made to it and the references it makes to other objects.

CoreExport ReferenceTarget ( )

Constructor.


Member Function Documentation

virtual CoreExport RefResult AutoDelete ( ) [virtual]

Deletes the object when it has no more real dependents.

This function is called by 3ds Max in order to delete a plugin object when its last real dependent has been deleted. It also allows derived classes to control the lifetime of their instances. The default implementation of this method will drop the references this object makes to other objects, and if the undo system is engaged (holding) it will ensure that the deletion is undo/redo-able. Override this method only if you don't want instances of your plugin to be automatically deleted when the last reference to them is deleted. Most subclasses of class ReferenceTarget will not need to override this method. Plugins should call ReferenceTarget::MaybeAutoDelete() or ReferenceMaker::DeleteMe() to delete instances of plugin objects. For more information on how 3ds Max deletes reference targets, see ReferenceTarget::MaybeAutoDelete()

Returns:
Default implementation always returns REF_SUCCEED. Overwrites should also always return REF_SUCCEED.
Note:
Classes that overwrite this method to prevent deletion of their instances, should be deleted by calling ReferenceMaker::DeleteMe() on them.

Reimplemented in MtlLib, MtlBaseLib, and NoteTrack.

CoreExport RefResult MaybeAutoDelete ( )

Deletes the object when it has no more real dependents.

The system calls this method to check if it can delete objects that had a reference to them deleted (dropped). If there are no more real dependents on this object, this function will ask the object to auto-delete itself. See ReferenceTarget::AutoDelete() for more information on this. Note that "weak" references will not prevent the deletion of the object. Plugins should also call this method when they need to delete plugin instances. See ReferenceTarget::AutoDelete() for more information on deleting plugin instances.

Returns:
REF_SUCCEED if this object was deleted successfully, or REF_FAIL if the object has outstanding real dependents to it and as a result it cannot be deleted.
Note:
Objects can prevent their own deletion by overwriting ReferenceTarget::AutoDelete(). Examples of objects that may want to do this are singletons such as class MtlLib.
virtual CoreExport void GetClassName ( MSTR s ) [virtual]
virtual CoreExport SClass_ID SuperClassID ( ) [virtual]
virtual BOOL IsRefTarget ( ) [inline, virtual]

Checks if this is a ReferenceTarget.

This function differentiates things subclassed from ReferenceMaker from subclasses of ReferenceTarget.

Returns:
Returns TRUE.

Reimplemented from ReferenceMaker.

{ return TRUE; }
CoreExport RefResult TestForLoop ( Interval  refInterval,
RefMakerHandle  hmaker 
)

Tests for a cyclical reference.

Implemented by the System. This method may be called to test for cyclical references.

Parameters:
refInterval - This interval is reserved for future use. Currently any plugin should specify FOREVER for this interval.
hmaker - The reference maker performing the loop test.
Returns:
REF_SUCCEED if a cyclic reference would be created; otherwise REF_FAIL.
CoreExport BOOL HasDependents ( )

Checks if a ReferenceTarget has references.

Implemented by the System.

Returns:
Returns 1 if the reference target has items that reference it, otherwise 0.
CoreExport BOOL HasRealDependents ( )

Checks if this has Real (Strong) Dependents.

This function goes through it's list of dependents or ReferenceMakers and queries the results of their IsRealDependency Functions.

Returns:
TRUE if any one of them are, FALSE otherwise.
void BeginDependencyTest ( ) [inline]

Starts Dependency Test.

To see if this reference target depends on something:

BOOL EndDependencyTest ( ) [inline]

Ends Dependency Test.

To see if this reference target depends on something:

virtual void RefAdded ( RefMakerHandle  rm ) [inline, virtual]

Called after a reference is made to a target.

This is called after a reference is made to this. If the target (this) needs to know that a reference to made to it, the target (this) can override this function.

Parameters:
rm - The ReferenceMaker creating the reference.

Reimplemented in Texmap, Mtl, MSPluginSimpleObject, MSPluginSimpleManipulator, MSPluginModifier, MSPluginSimpleMod, MSPluginTexmap, MSPluginMtl, MSPluginObject< ShapeObject >, MSPluginObject< HelperObject >, MSPluginObject< GeomObject >, MSPluginObject< GenCamera >, MSPluginObject< GenLight >, MSPluginSpecialFX< Effect8 >, and MSPluginSpecialFX< Atmospheric >.

{ UNUSED_PARAM(rm); }
virtual void RefAddedUndoRedo ( RefMakerHandle  rm ) [inline, virtual]

Called after a reference is made to a target because of undo or redo.

This method is available in release 2.0 and later only. Called when reference is added because of and undo or a redo. Otherwise it is similar to RefAdded.

Parameters:
rm - The ReferenceMaker creating the reference.
{ UNUSED_PARAM(rm); }
virtual void RefDeleted ( ) [inline, virtual]

Called after a references to this is deleted.

This is called after deleting a reference to a reference target, in the case that the target was not deleted. When the last strong reference to a ReferenceTarget is removed, the ReferenceTarget is deleted, the destructor is called, and the memory cleared.

Reimplemented in Mtl, MSCustAttrib, MSPluginSimpleObject, MSPluginSimpleManipulator, MSPluginModifier, MSPluginSimpleMod, MSPluginTexmap, MSPluginMtl, MSPluginObject< ShapeObject >, MSPluginObject< HelperObject >, MSPluginObject< GeomObject >, MSPluginObject< GenCamera >, MSPluginObject< GenLight >, MSPluginSpecialFX< Effect8 >, and MSPluginSpecialFX< Atmospheric >.

{}
virtual void RefDeletedUndoRedo ( ) [inline, virtual]

Called after a references to this is deleted because of undo or redo.

This is called after deleting a reference to a reference target, in the case that the target was not deleted. When the last strong reference to a ReferenceTarget is removed, the ReferenceTarget is deleted, the destructor is called, and the memory cleared.

{}
CoreExport RefResult DeleteAllRefsToMe ( ) [virtual]

Deletes all references to this ReferenceTarget.

implemented by the System. Deletes all references to this ReferenceTarget.

Returns:
always returns REF_SUCCEED.

Reimplemented from ReferenceMaker.

CoreExport RefResult TransferReferences ( RefTargetHandle  oldTarget,
BOOL  delOld = FALSE 
)

Transfers all the references from oldTarget to this.

Implemented by the System. This method is used to transfer all the references from oldTarget to this reference target.

Parameters:
oldTarget - The previous reference target.
delOld - If this is TRUE the previous reference target is deleted.
Returns:
Always returns REF_SUCCEED.
CoreExport int DoEnumDependents ( DependentEnumProc dep )

Begins an enumeration that searches back in the dependency network.

Implemented by the System. This method is called to initiate an enumeration of all the references to the ReferenceTarget. This method prepares the DependentEnumProc for enumeration, and calls DoEnumDependentsImpl on the ReferenceTarget. To enumerate the down the reference hierarchy, see EnumRefHierarchy.

Parameters:
dep - The callback object called for each dependent.
Returns:
Return 1 to stop the enumeration and 0 to continue.
See also:
EnumRefHierarchy

Reimplemented from ReferenceMaker.

virtual CoreExport RefTargetHandle Clone ( RemapDir remap ) [virtual]

This method is used by 3ds Max to clone an object.

See also:
CloneRefHierarchy(), class RemapDir This method is called by 3ds Max to have the plugin clone itself. The plug-in's implementation of this method should copy both the data structure and all the data residing in the data structure of this reference target. The plugin should clone all its references as well. Also, the plug-in's implementation of this method must call BaseClone(). In order for classes derived from this class to clone cleanly, the Clone method should just create the new instance, and then call an implementation of BaseClone that clones the references and copies any other necessary data. For example:
            class MyDerivedPlugin
                : public MyBasePlugin
            {
                const int MY_REFERENCE = 1;

                ReferenceTarget* Clone(RemapDir& remap)
                {
                    ReferenceTarget* result = new MyDerivedPlugin();
                    BaseClone(this, result, remap);
                    return result;
                }

                void BaseClone(ReferenceTarget* from, ReferenceTarget* to, RemapDir& remap)
                {
                    if (!to || !from || from == to)
                        return;    
                    MyBasePlugin::BaseClone(from, to, remap);
                    to->ReplaceReference(MY_REFERENCE, remap->CloneRef(from->GetReference(MY_REFERENCE)));
                }
            };

This method should not be directly called by plug-ins. Instead, either RemapDir::CloneRef() or CloneRefHierachy() should be used to perform cloning. These methods ensure that the mapping from the original object to the clone is added to the RemapDir used for cloning, which may be used during backpatch operations

Note:
See the remarks in method BaseClone() below.
Parameters:
remap - A RemapDir instance used for remapping references during a Clone.
Returns:
A pointer to the cloned item.

Reimplemented in EaseCurveList, MultCurveList, DummyObject, SphereGizmoObject, CylGizmoObject, BoxGizmoObject, CollisionPlane, CollisionSphere, CollisionMesh, MtlLib, MtlBaseLib, DADBitmapCarrier, LinearShape, DefNoteTrack, PatchObject, PolyObject, SimpleOSMToWSMMod, SimpleOSMToWSMMod2, SimpleShape, SimpleSpline, SplineShape, TriObject, MSCustAttrib, MSPluginGeomObject, MSGeomObjectXtnd, MSPluginHelper, MSHelperXtnd, MSPluginLight, MSLightXtnd, MSPluginCamera, MSCameraXtnd, MSPluginShape, MSShapeXtnd, MSPluginSimpleObject, MSSimpleObjectXtnd, MSPluginSimpleManipulator, MSSimpleManipulatorXtnd, MSPluginModifier, MSModifierXtnd, MSPluginSimpleMod, MSSimpleModXtnd, MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, MSMtlXtnd, MSPluginEffect, MSEffectXtnd, MSPluginAtmos, MSAtmosXtnd, MSPluginTrackViewUtility, and PFSimpleAction.

virtual CoreExport void BaseClone ( ReferenceTarget from,
ReferenceTarget to,
RemapDir remap 
) [virtual]

This method copies base class data from an object to its clone.

This method is available in release 4.0 and later only. Virtual method.

Note:
All plugins that implement a Clone() method have to call this BaseClone() method from that Clone() method with the old and the new object as parameters. The ordering in regards to when this method is called is unimportant, however this method must, of course, be called after the cloned object is created. This method allows base classes to copy their data into a new object created by the clone operation. As described in the Clone method, the Clone method should just create a new instance and then call the BaseClone method. The BaseClone method should then clones any references and sets any other necessary data. This allows classes that derive from this class to clone cleanly. See the Clone method documentation for a code example. All overrides of BaseClone() must call the base class implementation. The base class implementation copies the CustAttrib objects into the newly created object.
Parameters:
from - Points to the old object to clone.
to - Points to the new object created.
remap - This class is used for remapping references during a Clone.

Reimplemented in Control, and MtlBase.

virtual CoreExport RefResult NotifyDependents ( Interval  changeInt,
PartID  partID,
RefMessage  message,
SClass_ID  sclass = NOTIFY_ALL,
BOOL  propagate = TRUE,
RefTargetHandle  hTarg = NULL 
) [virtual]

Notify all dependent RefMakers concerned with the message.

Implemented by the System. This method broadcasts the message specified by the message parameter to all the items which reference this item. Note the following on how reference messages propagate (that is, travel to the dependents):

  • When a plugin sends a message via NotifyDependents(), the message
    1. Propagates to ALL the items that reference it.
    2. And also to all the items which reference those items.
    3. And so on.
  • The only exceptions to this are as follows:
  1. The propagate parameter passed is FALSE. In that case the message only goes to the immediate dependents.
  2. If the SClass_ID sclass = NOTIFY_ALL parameter limits the dependents to a certain specified Super Class.
  3. If one of the items that references the plugin, processes the message inside its NotifyRefChanged() and returns REF_STOP instead of REF_SUCCEED. In this case, the message is not further propagated.

Also, whenever a message propagates, the hTarget parameter received in NotifyRefChanged() is reset to the this pointer of the immediate dependent (not the originator) who propagates the message.

Parameters:
changeInt - Currently all plug-ins must pass FOREVER for this interval. This indicates the interval of time over which the change reported by the message is in effect.
partID - This parameter is used to pass message specific information to the items which will receive the message. See the ReferenceMaker::NotifiyRefChanged() method for more details.
message - The message to broadcast to all dependents. See the ReferenceMaker::NotifiyRefChanged() method for more details.
sclass - This parameter defaults to NOTIFY_ALL. If this value is passed to NotifyDependents() all dependents will be notified. Other super class values may be passed to only send the message to certain items whose SuperClassID matches the one passed.
propagate - This parameter defaults to TRUE. This indicates that the message should be sent to all 'nested' dependencies. If passed as FALSE, this parameter indicates the message should only be sent to first level dependents. Normally this should be left to default to TRUE.
hTarg - This parameter must always default to NULL.
Returns:
This method always returns REF_SUCCEED.

Reimplemented from ReferenceMaker.

void FlagDependents ( TimeValue  t,
PartID  which = PART_PUT_IN_FG 
) [inline]

This sends the REFMSG_FLAGDEPENDENTS message up the pipeline.

This sends the REFMSG_FLAGDEPENDENTS message up the pipeline. There are two reasons to flag dependents:

  1. To put the node in the FG plane. (PART_PUT_IN_FG)
  2. To set the node's mesh color to green to indicate it is a dependent. (PART_SHOW_DEPENDENCIES). If the PART_SHOWDEP_ON bit is set, the dependency display is turned on, otherwise it is turned off.
    Parameters:
    t - Currently all plug-ins must pass FOREVER for this interval.
    which - The part id that is sent with REFMSG_FLAGDEPENDENTS
virtual void NotifyForeground ( TimeValue  t ) [inline, virtual]

This method is called to flag dependents into the FG.

This method is called to flag dependents into the FG. (Note that the above method is obsolete) The default implementation just sends out the notification REFMSG_FLAGDEPENDENTS with PART_PUT_IN_FG as the partID. In particular, a slave controller could override this method and call its master's version of this method

virtual void NotifyTarget ( int  message,
ReferenceMaker hMaker 
) [inline, virtual]

Sends messages to ReferenceTargets.

This method is available in release 4.0 and later only. Used by a ReferenceMaker to send 'reverse' notification messages to its ReferenceTargets, or to this ReferenceTarget.

Parameters:
message - The message sent to the reference target.
hMaker - The ReferenceMaker sending the message.
{ UNUSED_PARAM(message); UNUSED_PARAM(hMaker); }
virtual CoreExport void* GetInterface ( ULONG  id ) [virtual]
virtual CoreExport BaseInterface* GetInterface ( Interface_ID  id ) [virtual]
virtual CoreExport int DoEnumDependentsImpl ( DependentEnumProc dep ) [protected, virtual]

Method to perform an enumeration on a ReferenceTarget.

Implemented by the System. This method is initially called by DoEnumDependents. This method allows a ReferenceTarget to call the given callback object's proc on itself, and then optionally enumerate all references to it. How to continue enumeration is based on the return value from the callback object's proc. All ReferenceTargets have a list of back pointers to entities that directly reference it. The default implementation of this method first checks to see if this ReferenceTarget was previously processed as part of the enumeration, and if so immediately returns 0. If the ReferenceTarget was not previously processed, it calls the callback object's proc on itself and then, dependent on the return value from the callback object's proc, enumerates those back pointers calling DoEnumDependentsImpl once per dependent. Normally you will not need to override this method. If you do override this method, you should use DependentEnumProc::CheckIfAndSetAsVisited to process your instance and its dependents only if it was not previously processed.

Parameters:
dep - The callback object called for each dependent.
Returns:
Return 1 to stop the enumeration and 0 to continue.
See also:
DependentEnumProc::CheckIfAndSetAsVisited(ReferenceMaker *rmaker)
        int RefTargMonitorRefMaker::DoEnumDependentsImpl(DependentEnumProc* dep) {
            // If already processed this reftarg once, no need to process it or its dependents again
            if (dep->CheckIfAndSetAsVisited(this)) 
                return 0;
            int res = dep->proc(this);
            if (res == DEP_ENUM_SKIP)
                return 0;
            else if (res)
                return 1;
            return mOwner.ProcessEnumDependents(dep);
        }

Reimplemented from ReferenceMaker.


Friends And Related Function Documentation

friend class DependentIterator [friend]
friend class DeleteRefRestore [friend]
friend class MakeRefRestore [friend]
friend class ReferenceMaker [friend]

ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget
ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget ReferenceTarget