This reference page is linked to from the following overview topics: Lesson 3: the reference system, Writing Reference Makers, Writing Reference Targets, Implementing Clone in a Plug-in, Creating and Changing References, Reference System Best Practices, Supporting Save to Previous, Handling Reference Messages, Reference Hierarchy Functions, Cloning Reference Targets, Incremental Improvements, Reference Messages During Animation.

#include "BuildWarnings.h"
#include "maxheap.h"
#include "strbasic.h"
#include "noncopyable.h"
#include "autoptr.h"
#include <WTypes.h>
#include "CoreExport.h"
#include "Animatable.h"
#include "AnimatableFlags.h"
#include "hold.h"
#include "channels.h"

Classes
class	RemapDir
	For remapping references during a Clone. More...
class	PostPatchProc
class	DependentEnumProc
	A callback class for enumerating dependents. More...
class	SaveEnumProc
	A callback class for saving dependents. More...
class	DefaultRemapDir
	Implements a default version of a RemapDir. More...
class	ReferenceMaker
	A scene entity that owns other scene entities and listens to messages from them. More...
class	ReferenceTarget
	A scene entity that is being owned and listened to by other scene entities. More...
class	ReferenceTarget::RefListItem
	Reference list link-node.
class	ReferenceTarget::RefList
	Stores the list of dependents for a ReferenceTargets, i.e. the list of references to a ReferenceTarget.
class	DependentIterator
	Iterates through all direct dependents of a given ReferenceTarget. More...
class	DeletedRestore
class	RefEnumProc
	A callback class for ReferenceMaker::EnumRefHierarchy. More...
class	GlobalReferenceMaker
	This class lets you tap in to ALL reference messages in the entire system. More...
class	GlobalReferenceMaker::GlobalReferenceDisableGuard
	This class is used to temporarily disable global reference makers. More...
class	SingleRefMaker
	Reference Maker to single entity. More...
class	AnimateSuspend
	Suspends the "animate" mode in an exception safe manner. More...
class	SuspendAll
	Suspends various system states in an exception safe manner. More...
Namespaces
namespace	MaxSDK
Defines
#define	PART_TOPO TOPO_CHANNEL
	See TOPO_CHANNEL.
#define	PART_GEOM GEOM_CHANNEL
	See GEOM_CHANNEL.
#define	PART_TEXMAP TEXMAP_CHANNEL
	See TEXMAP_CHANNEL.
#define	PART_MTL MTL_CHANNEL
	See MTL_CHANNEL.
#define	PART_SELECT SELECT_CHANNEL
	See SELECT_CHANNEL.
#define	PART_SUBSEL_TYPE SUBSEL_TYPE_CHANNEL
	See SUBSEL_TYPE_CHANNEL.
#define	PART_DISPLAY DISP_ATTRIB_CHANNEL
	See DISP_ATTRIB_CHANNEL.
#define	PART_VERTCOLOR VERTCOLOR_CHANNEL
	See VERTCOLOR_CHANNEL.
#define	PART_GFX_DATA GFX_DATA_CHANNEL
	See GFX_DATA_CHANNEL.
#define	PART_DISP_APPROX DISP_APPROX_CHANNEL
	See DISP_APPROX_CHANNEL.
#define	PART_EXTENSION EXTENSION_CHANNEL
	See EXTENSION_CHANNEL.
#define	PART_TM_CHAN TM_CHANNEL
	Transform Channel.
#define	PART_MTL_CHAN GLOBMTL_CHANNEL
	Material Channel.
#define	PART_OBJECT_TYPE (1<<11)
	The type of object in the pipeline changed.
#define	PART_TM (1<<12)
	node transform matrix
#define	PART_OBJ (PART_TOPO\|PART_GEOM)
	Combination of PART_TOPO and PART_GEOM.
#define	PART_ALL (ALL_CHANNELS\|PART_TM)
	Combination of ALL_CHANNELS and PART_TM.
#define	PART_GI_EXCLUDED (1<<0)
	Excluded.
#define	PART_GI_OCCLUDER (1<<1)
	Excluder.
#define	PART_GI_RECEIVER (1<<2)
	Receiver.
#define	PART_GI_DIFFUSE (1<<3)
	Diffuse.
#define	PART_GI_SPECULAR (1<<4)
	Specular.
#define	PART_GI_NBREFINESTEPS (1<<5)
	Refine Steps.
#define	PART_GI_MESHSIZE (1<<6)
	Mesh Size.
#define	PART_GI_MESHINGENABLED (1<<7)
	Meshing Enabled.
#define	PART_GI_USEGLOBALMESHING (1<<8)
	Use Global Meshing.
#define	PART_GI_EXCLUDEFROMREGATHERING (1<<9)
	Exclude From Regathering.
#define	PART_GI_STOREILLUMMESH (1<<10)
	Store Illumination Mesh.
#define	PART_GI_RAYMULT (1<<11)
	Ray Multiplier.
#define	PART_GI_USE_ADAPTIVE_SUBDIVISION (1<<12)
	Use Adaptive Subdivision.
#define	PART_GI_MIN_MESH_SIZE (1<<13)
	Minium Mesh size.
#define	PART_GI_INITIAL_MESH_SIZE (1<<14)
	Initial Mesh size.
#define	PART_GI_CONTRAST_THRESHOLD (1<<15)
	Contrast Threshold.
#define	PART_REND_PROP_RENDERABLE (1<<0)
	Renderable.
#define	PART_REND_PROP_CAST_SHADOW (1<<1)
	Cast Shadow.
#define	PART_REND_PROP_RCV_SHADOW (1<<2)
	Recieve Shadow.
#define	PART_REND_PROP_RENDER_OCCLUDED (1<<3)
	Render Occluded.
#define	PART_REND_PROP_VISIBILITY (1<<4)
	Visibility.
#define	PART_REND_PROP_INHERIT_VIS (1<<5)
	Inherit Visibility.
#define	PART_REND_PROP_PRIMARY_INVISIBILITY (1<<6)
	Primary Visibility.
#define	PART_REND_PROP_SECONDARY_INVISIBILITY (1<<7)
	Secondary Visibility.
#define	PART_DISP_PROP_IS_HIDDEN (1<<0)
	Is hidden.
#define	PART_DISP_PROP_IS_FROZEN (1<<1)
	Is frozen.
#define	PART_DISP_PROP_SHOW_FRZN_WITH_MTL (1<<2)
	Show frozen with material.
#define	PART_DISP_PROP_BOX_MODE (1<<3)
	Box mode.
#define	PART_DISP_PROP_BACKCULL (1<<4)
	Backface culling.
#define	PART_DISP_PROP_ALL_EDGES (1<<5)
	All edges.
#define	PART_DISP_PROP_BONE_ONLY (1<<6)
	Bones only.
#define	PART_DISP_PROP_BONE_AS_LINE (1<<7)
	Bones as lines.
#define	PART_DISP_PROP_SHOW_PATH (1<<8)
	Show path.
#define	PART_DISP_PROP_VERT_TICKS (1<<9)
	Vertex ticks.
#define	PART_DISP_PROP_XRAY_MTL (1<<10)
	XRay material.
#define	PART_DISP_PROP_IGNORE_EXTENTS (1<<11)
	Ignore extents.
#define	PART_DISP_PROP_COLOR_VERTS (1<<12)
	Vertex colors.
#define	PART_EXCLUDE_RADIOSITY (1<<29)
	Special part ID that prevents the radiosity engine from processing the change.
#define	PART_HIDESTATE (1<<30)
	Special part ID sent by visibility controllers.
#define	PART_MXS_PROPCHANGE (1<<16)
	Special part ID sent by MAXScript when it changes an object's parameter.
#define	REFMSG_LOOPTEST 0x00000010
	This tests for a cyclic reference. It will return REF_FAIL if there is a loop.
#define	REFMSG_TARGET_DELETED 0x00000020
	This message is sent when a ReferenceTarget is deleted.
#define	REFMSG_MODAPP_DELETING 0x00000021
	Used Internally.
#define	REFMSG_EVAL 0x00000030
	Used Internally.
#define	REFMSG_RESET_ORIGIN 0x00000040
	Used Internally.
#define	REFMSG_CHANGE 0x00000050
	Sent to dependents of a ReferenceTarget that has changed in some way.
#define	REFMSG_FLAGDEPENDENTS 0x00000070
	Used Internally.
#define	REFMSG_TARGET_SELECTIONCHANGE 0x00000080
	Used Internally.
#define	REFMSG_BEGIN_EDIT 0x00000090
	This is used by modifiers to indicate when they are beginning an edit.
#define	REFMSG_END_EDIT 0x000000A0
	This is used by modifiers to indicate when they are ending an edit.
#define	REFMSG_DISABLE 0x000000B0
	Used Internally.
#define	REFMSG_ENABLE 0x000000C0
	Used Internally.
#define	REFMSG_TURNON 0x000000D0
	Used Internally.
#define	REFMSG_TURNOFF 0x000000E0
	Used Internally.
#define	REFMSG_LOOKAT_TARGET_DELETED 0x000000F0
	Used Internally.
#define	REFMSG_INVALIDATE_IF_BG 0x000000F1
	Used Internally.
#define	REFMSG_MOD_DISPLAY_ON 0x000000F2
	This is used by modifiers to indicate that their apparatus (gizmo) is displayed.
#define	REFMSG_MOD_DISPLAY_OFF 0x000000F3
	This is used by modifiers to indicate that their apparatus (gizmo) is no longer displayed.
#define	REFMSG_MOD_EVAL 0x000000F4
	Modifier uses this to tell Modapps to call their Eval() procedure.
#define	REFMSG_IS_OK_TO_CHANGE_TOPOLOGY 0x000000F5
	Ask if it is ok to change topology.
#define	REFMSG_NODE_LINK 0x000000F6
	Sent by a node when it has a child linked to it or unlinked from it.
#define	REFMSG_NODE_NAMECHANGE 0x000000F7
	Sent by a node when it's name has been changed.
#define	REFMSG_OBREF_CHANGE 0x000000F8
	DEPRECATED Sent by a node (or derived object) when the object it references changes.
#define	REFMSG_MODIFIER_ADDED 0x000000F9
	Sent by a derived object when a modifier is a added or deleted.
#define	REFMSG_CONTROLREF_CHANGE 0x000000FA
	Sent when an animatable switches controllers for one of it's parameters.
#define	REFMSG_GET_PARAM_NAME 0x000000FB
	A parameter block sends the message to it's client when it needs the anim name of the ith parameter.
#define	REFMSG_GET_PARAM_DIM 0x000000FC
	A parameter block sends this message to it's client when it needs to know the dimension type of the ith parameter.
#define	REFMSG_GET_CONTROL_DIM 0x000000FD
	A controller can send this to it's client to get it's param dimension.
#define	REFMSG_TM_CHANGE 0x000000FE
	Sent when a Nodes transform matrix (TM) has changed in a different time.
#define	REFMSG_RANGE_CHANGE 0x000000FF
	A node sends this message when it's animation range changes.
#define	REFMSG_LINEHEIGHT_CHANGE 0x00000100
	Sent to the tree view when an animatable's line height changes.
#define	REFMSG_BECOMING_ANIMATED 0x00000101
	A controller should send this message to the track view when it becomes animated.
#define	REFMSG_SUBANIM_STRUCTURE_CHANGED 0x00000102
	Used in the TrackView to regenerate an objects sub components.
#define	REFMSG_REF_DELETED 0x00000103
	A target has had a reference deleted.
#define	REFMSG_REF_ADDED 0x00000104
	A target has had a reference added.
#define	REFMSG_BRANCHED_HISTORY_CHANGED 0x00000105
	Sent by an object that provides branching in the history to notify that the structure of the branches changed.
#define	REFMSG_NODEINSELSET_CHANGED 0x00000106
	The selection set sends this notification when it receives REFMSG_CHANGE from an item in the selection set.
#define	REFMSG_TEST_DEPENDENCY 0x00000107
	This method is used to see if this reference target depends on something.
#define	REFMSG_WANT_SHOWPARAMLEVEL 0x00000108
	Queries whether to display "Parameters" in the track view.
#define	REFMSG_BEFORE_PASTE 0x00000109
	Sent before a paste has been done.
#define	REFMSG_NOTIFY_PASTE 0x0000010A
	Sent after a paste has been done.
#define	REFMSG_UV_SYM_CHANGE 0x0000010B
	Sent when a UV Generator changes symmetry, so interactive texture display updates.
#define	REFMSG_GET_NODE_NAME 0x0000010C
	Gets the node's name.
#define	REFMSG_SEL_NODES_DELETED 0x0000010D
	Sent by the selection set whenever it has just deleted nodes.
#define	REFMSG_PRENOTIFY_PASTE 0x0000010E
	Sent before a reference target is pasted. Sent by the target about to be replaced.
#define	REFMSG_SHAPE_START_CHANGE 0x0000010F
	Sent when a shape starts changing.
#define	REFMSG_SHAPE_END_CHANGE 0x00000110
	Sent when a shape stops changing.
#define	REFMSG_TEXMAP_REMOVED 0x00000111
	A texture map has been removed.
#define	REFMSG_FLAG_NODES_WITH_SEL_DEPENDENTS 0x00000112
	Sent by an unselected node to see if any selected nodes depend on it.
#define	REFMSG_CONTAINED_SHAPE_POS_CHANGE 0x00000120
	Sent by objects which contain shapes when the shape position changes.
#define	REFMSG_CONTAINED_SHAPE_SEL_CHANGE 0x00000121
	Sent by objects which contain shapes when the shape position changes.
#define	REFMSG_CONTAINED_SHAPE_GENERAL_CHANGE 0x00000122
	Sent by objects which contain shapes when general changes occur.
#define	REFMSG_SELECT_BRANCH 0x00000130
	Select sub-object branch.
#define	REFMSG_MOUSE_CYCLE_STARTED 0x00000140
	Sent when a user begins a mouse operation in the viewport.
#define	REFMSG_MOUSE_CYCLE_COMPLETED 0x00000150
	Sent when a user ends a mouse operation in the viewport.
#define	REFMSG_CHECK_FOR_INVALID_BIND 0x00000161
	Sent when linking nodes.
#define	REFMSG_OBJECT_CACHE_DUMPED 0x00000162
	Sent when a cache is dumped in the pipeline.
#define	REFMSG_SFX_CHANGE 0x00000170
	Sent by Atmospheric or Effect when it makes or deletes a reference to a node.
#define	REFMSG_OBJXREF_UPDATEMAT 0x00000180
	For internal use only.
#define	REFMSG_OBJXREF_UPDATECTRL 0x00000181
	For internal use only.
#define	REFMSG_OBJECT_REPLACED 0x00000200
	Sent when objects are replaced from another scene (File->Replace).
#define	REFMSG_NODE_WIRECOLOR_CHANGED 0x00000210
	Sent when nodes wireframe color is changed.
#define	REFMSG_NUM_SUBOBJECTTYPES_CHANGED 0x00000211
	Indicates that the subobject types have changed and that the StackView should be updated.
#define	REFMSG_GET_NODE_HANDLE 0x00000220
	Returns a unique (per session) node handle integer.
#define	REFMSG_END_MODIFY_PARAMS 0x00000230
	This will cause EndEditParams to be called on the object displayed in the modify panel.
#define	REFMSG_BEGIN_MODIFY_PARAMS 0x00000231
	This will cause BeginEditParams to be called on the object displayed in the modify panel.
#define	REFMSG_TAB_ELEMENT_NULLED 0x00000232
	Sent when a Tab<> is deleted.
#define	REFMSG_NODE_HANDLE_CHANGED 0x00000233
	Sent to merged objects so that they can convert node handles.
#define	REFMSG_NODE_WSCACHE_UPDATED 0x00000234
	The pipeline was reevaluated and the wscache was updated.
#define	REFMSG_NODE_MATERIAL_CHANGED 0x00000235
	This notification is sent after a new material was assigned to a node.
#define	REFMSG_SUBANIM_NUMBER_CHANGED 0x00000236
	This notification is sent to dependents when a subanim's changes order.
#define	REFMSG_NODE_FLAGOMB_RENDER 0x00000237
	A Node is rendered with motion blur.
#define	REFMSG_NODE_GI_PROP_CHANGED 0x00000238
	For Internal use only.
#define	REFMSG_KEY_SELECTION_CHANGED 0x00000239
	Sent when key selection changes.
#define	REFMSG_NODE_RENDERING_PROP_CHANGED 0x00000240
	Sent AFTER the Node Rendering Properties have changed The part id will contain information about the property that has changed.
#define	REFMSG_NODE_DISPLAY_PROP_CHANGED 0x00000241
	Notification sent AFTER the Node Display Properties have changed.
#define	REFMSG_MXS_CUSTATTRIB_CHANGE 0x00000250
	Message type propagated to dependents of scripted Custom Attribute (CA) when CA gets a REFMSG_CHANGE.
#define	REFMSG_NODE_PRE_DELETE 0x00000255
	This message is sent immediately prior to a node being deleted.
#define	REFMSG_LOCKED 0x00000260
	This message is sent after an item has been locked.
#define	REFMSG_UNLOCKED 0x00000261
	This message is sent after an item has been unlocked.
#define	REFMSG_OBJECT_DEFINITION_CHANGE_BEGIN 0x00000270
	This message is sent immediately before an object instance is updated to a new object definition.
#define	REFMSG_OBJECT_DEFINITION_CHANGE_END 0x00000271
	This message is sent immediately after an object instance is updated to a new object definition.
#define	REFMSG_DISPLAY_MATERIAL_CHANGE 0x00000300
	Notification sent when any parameters of the material or texture map changed.
#define	REFMSG_USER 0x00010000
	Message numbers above this value can be defined for use by sub-classes, below are reserved.
#define	VALID(x) (x)
#define	NOTIFY_ALL 0xfffffff0
	If this super class is passed to NotifyDependents() all dependents will be notified.
#define	REFERENCE_MAKER_INTERFACE 0x2f96f73
	A ULONG Interface Id to determine if an Animatable is a Reference Maker or Target.
#define	REFERENCE_TARGET_INTERFACE 0x66b073ea
	A ULONG Interface Id to determine if an Animatable is a Reference Maker or Target.
PartIDs when notify dependents is called with REFMSG_FLAGDEPENDENTS
See also: REFMSG_FLAGDEPENDENTS
#define	PART_PUT_IN_FG (1<<0)
	Put in Foreground.
#define	PART_SHOW_DEPENDENCIES (1<<1)
	Show dependencies.
#define	PART_SHOWDEP_ON (1<<2)
	Show dependencies on.
Defines XRef Messages
Sent to build a list of nodes which use a particular XRef object.
#define	REFMSG_OBJXREF_GETNODES 0x00000190
	For Internal use only.
#define	REFMSG_CTRLXREF_GETNODES 0x00000191
	For internal use only.
#define	REFMSG_MTLXREF_GETNODES 0x00000192
	For internal use only.
Messages sent from ReferenceMaker to ReferenceTarget
#define	TARGETMSG_USER 0x00010000
	Codes used by a ReferenceMaker to send 'reverse' notification messages to a RefTarget.
#define	TARGETMSG_ATTACHING_NODE 0x00000010
	Send to a Node's ObjectRef when the node is attaching the object to itself.
#define	TARGETMSG_DELETING_NODE 0x00000020
	Send to a Node's ObjectRef when the node is about to be explicitly deleted.
#define	TARGETMSG_DETACHING_NODE 0x00000030
	Send to a Node's ObjectRef when the node is detaching the object from itself.
Defines enumeration return values
Possible return values for RefEnumProc::proc()
#define	DEP_ENUM_CONTINUE 0
	Continues enumeration.
#define	DEP_ENUM_HALT 1
	Halts enumeration.
#define	DEP_ENUM_SKIP 2
	Skip enumeration.
#define	REF_ENUM_CONTINUE 0
	Continues enumeration.
#define	REF_ENUM_HALT 1
	Halts enumeration.
#define	REF_ENUM_SKIP 2
	Skip enumeration.
Typedefs
typedef void *	ReferenceData
typedef unsigned int	TargetParam
typedef ULONG_PTR	PartID
	This is NOT just a bitmask, the parameter is also used to stuff pointers, hence the ULONG_PTR.
typedef unsigned int	RefMessage
	The message passed to notify and evaluate.
typedef ReferenceTarget *	RefTargetHandle
	Creates a typename for ReferenceTarget pointers.
typedef ReferenceMaker *	RefMakerHandle
	Creates a typename for ReferenceMaker pointers.
Enumerations
enum	RefResult { REF_FAIL = 0, REF_HALT = 0, REF_SUCCEED, REF_DONTCARE, REF_STOP, REF_INVALID, REF_AUTO_DELETE }
	Return codes for reference handling and message processing methods. More...
Functions
CoreExport RemapDir *	NewRemapDir (BOOL use_A_WORK2_flag=FALSE)
	Gets a pointer to a default version of a RemapDir.
CoreExport ReferenceTarget *	CloneRefHierarchy (ReferenceTarget *rm)
	This function is used to clone a single ReferenceTarget.
CoreExport void	RegisterGlobalReference (GlobalReferenceMaker *maker)
	Registers an instance of this class whose NotifyRefChanged() method will receive the messages.
CoreExport void	UnRegisterGlobalReference (GlobalReferenceMaker *maker)
	Unregisters the class so it won't be called anymore.
CoreExport void	ClearAFlagInHierarchy (RefMakerHandle rm, DWORD mask)
	Clears the specified Animatable Flag bits in a reference hierarchy.
CoreExport void	ClearAFlagInAllAnimatables (DWORD mask)
	Clears the specified Animatable Flag bits on all Animatables.
CoreExport BOOL	DependsOn (RefMakerHandle mkr, RefMakerHandle targ)
	Checks if there is a path of references from a ReferenceMaker to a ReferenceTarget.
CoreExport DWORD	GetSavingVersion ()
	Function to find out if we are saving an old version of a .MAX file.
CoreExport DWORD	SetSavingVersion (DWORD version)
	Function used internally to maintain the SavingVersion number, which should not be called by plugins.
CoreExport void	DisableRefMsgs ()
	Disable reference messages globally.
CoreExport void	EnableRefMsgs ()
	Enable reference messages globally.

Define Documentation

#define VALID ( x ) (x)

REF_FAIL	The operation failed. Search for all occurrences
REF_HALT	Return this from your implementation of ReferenceMaker::NotifyRefChanged() in order to immediately stop sending the reference message to dependents of the RefereneTarget the message originates from. Search for all occurrences
REF_SUCCEED	The operation succeeded. Search for all occurrences
REF_DONTCARE	The results of the operation don't matter. Search for all occurrences
REF_STOP	Return this from your implementation of ReferenceMaker::NotifyRefChanged() to stop propagating the reference message to your dependents, but allow it to be sent to the other dependents of the ReferenceTarget the message originates from. Search for all occurrences
REF_INVALID	Attempts to delete an invalid reference will return this value. Search for all occurrences
REF_AUTO_DELETE	Return this from your implementation of ReferenceMaker::NotifyRefChanged() in response to a REFMGS_TAGET_DELETED message to indicate that all the reference targets you depended on have been deleted, and you also wish to be deleted from the scene. Search for all occurrences

CoreExport void ClearAFlagInHierarchy	(	RefMakerHandle	rm,
		DWORD	mask
	)

rm	- The handle to the root ReferenceMaker to enumerate from
mask	The bits to turn off in the Animatable flags

CoreExport BOOL DependsOn	(	RefMakerHandle	mkr,
		RefMakerHandle	targ
	)

mkr	- The handle to the ReferenceMaker
targ	- The handle to the ReferenceTarget

Classes

Namespaces

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation