Viewing Reference Messages

This section discusses a utility plug-in called the Reference Watcher. This plug-in is used to help understand the reference structure of a chosen item and to monitor the reference messages it sends. This provides a quick, visual way for developers to examine the use of references in 3ds Max.

This plug-in allows you to create a reference to a chosen Reference Target and then watch the messages sent as you work with the target. For instance, follow the steps below to analyze the reference messages sent by a node in the scene.

Setting up Reference Watcher in Visual Studio

The project is in \MAXSDK\HOWTO\UTILITIES\REFERENCECHECK\

Load this project into VC++, set up your input and output paths and build it. Place REFCHECK.DLU into your 3ds Max DLL search path (for example in the \Plug-inS directory). You can then run the program by choosing How To/Reference Watcher in the utility panel.

Running Reference Watcher in 3ds Max

Reset 3ds Max and create a single Box in the scene called Sphere01. Leave it selected after creation.

Launch the Reference Watcher from the Utility branch of the command panel.

Click on the Pick Reference Target to Watch button and choose the Sphere01 node from the track bar dialog by opening the Objects branch and selecting the Sphere01 label then pressing OK.

Result

The Reference Watcher utility creates a reference to the box node in the scene and displays information about it.

As you work with the node (select it/deselect it, assign modifiers, bind to space warps, assign materials, change controllers, drag the item in the viewports, etc.), you can monitor the reference messages sent. You recognized them because the use the #define name from ref.h (for exampleREFMSG_CHANGE) in the upper most window. If you want to clear the message list so you can see what messages are sent for a particular action, press the Clear Message List button first.

ListBox - Reference Messages Recieved From Target

This upper most list box shows a list of reference messages. The list is blank at first, but once the sphere is moved, it fills with messages as shown at right.

ListBox - ReferenceMakers Who Reference This Item

The second list box in the dialog shows the items referencing the node you have selected. This provides a way to see who is referencing an item. In the case of the Sphere01 node these are:

0: NodeSelection
1: Animatable
2: (This Reference Watcher)
3: Animatable
4: Animatable

ListBox - ReferenceTargets This Item References

The bottom most list box shows the references that the node itself has. Sphere01 node has 16 reference targets. Many ReferenceTargets are NULL but you can see a few references of interest in the following table: