Sub-Anims
See Also: Track View, Class Animatable, Parameter Blocks.
Overview
In the SDK the term anim refers to something derived from class Animatable. This anim can be anything such as a node, object, controller, material, texmap, parameter block, etc. Further, any item that has sub-items has what are referred to as sub-anims. This hierarchy of items, the parent item and it's sub-items, is referred to as the sub-anim hierarchy. The sub-anim hierarchy can be thought of as the Track View hierarchy.
Below is a partial screen capture of Track View showing a few anims and their sub-anims.
For example, a node has six sub-anims. These are: Space Warp Bindings, the Transform Controller, the Object Reference of the node, the Material, the Visibility Controller, the Image Motion Blur Controller. If a node does not have some of these assigned (for example the material and visibility controller) these sub-anims are NULL. Any sub-anims that are NULL don't appear in Track View. In the example above, the node Box01 has two sub-anims that are non-NULL: the transform controller (labeled Transform) and the object reference (labeled Object(Box)). The other node, Box02, has three non-NULL sub-anims. These are the transform controller (Transform), the derived object (Modified Object), and the Material (Material01).
Note that sub-anims may have sub-anims themselves. This can be seen in the parameters of Box01 sub-anim Object(Box). Procedural objects derived from SimpleObject (like Object(Box)) have a single sub-anim and that is the parameter block. The box's parameter block has six sub-anims (Length, Width, etc.). Note also that the node Box02 sub-anim Material #1 has sub-anims of its own. These are its parameters and its texture maps.
Sub-Anims are often the animatable parameters of a plug-in. In 3ds max any animated parameter has a controller to control the animation. The controller for a parameter appears in the track view. This allows the user to view the animation associated with a parameter in several formats such as in key frames, as a range of time over which the animation takes place, and graphically as a function curve.
3ds max accesses the sub-anims of a plug-in using a virtual array mechanism. That is, each sub-anim is given an index and is accessed by a method that returns a pointer to the 'i-th' sub-anim. These methods are Animatable::NumSubs(),Animatable::SubAnim(i) and Animatable::SubAnimName(i).
Methods
The plug-in can store its parameters in any way it chooses. When the system needs to access a parameter, it passes the plug-in an index and the plug-in returns the parameter it has assigned to that index. Below is a description of the three methods associated with sub-anims.
virtual int NumSubs();
This method returns the total number of sub-anims maintained by the plug-in. If a plug-in is using a parameter block to manage its parameters it should just return 1 for all those parameters. Below is the SimpleMod implementation of this method. It returns 3 as it has a controller for the Center, the Gizmo, and a parameter block.
int NumSubs() {return 3;}
virtual Animatable* SubAnim(int i);
This method returns a pointer to the 'i-th' sub-anim. If a plug-in is using a parameter block to manage all of its parameters it should just return a pointer to the parameter block itself from this method. Below is the SimpleMod implementation of this method.
Animatable* SimpleMod::SubAnim(int i)
{
switch (i) {
case 0: return posControl; // Center
case 1: return tmControl; // Gizmo
case 2: return pblock; // Parameter block
default: return NULL;
}
}
virtual TSTR SubAnimName(int i);
This method returns the name of the 'i-th' sub-anim to appear in track view. The system has no idea what name to assign to the parameter (it only knows it by the array index), so this method is called to retrieve one to display. Below is the SimpleMod implementation of this method. Note that it returns a descriptive name for each controller, i.e. "Center" for the center mark position controller, and "Gizmo" for the gizmo controller. However it just returns "Parameters" for the parameter block. The parameter block name itself does not show up in track view, only its sub-controllers. This is because the parameter block implements a method that tells the system to not show it in track view. This prevents the user from having to navigate another nested level to simply get to the parameters.
TSTR SimpleMod::SubAnimName(int i)
{
switch (i) {
case 0: return TSTR(_T("Center"));
case 1: return TSTR(_T("Gizmo"));
case 2: return TSTR(_T("Parameters"));
default: return TSTR(_T(""));
}
}
Summary
The sub-anim hierarchy of a plug-in corresponds to the Track View hierarchy. Any non-NULL sub-anims that a plug-in has appear in Track View as branches under the parent item. A developer implements three methods of the Animatable class, NumSubs(), SubAnim(i) and SubAnimName(i) to provide 3ds max with access to its sub-anims.