Working with Controllers
See Also: Class Control, Class StdControl, Class SetXFormPacket, Class IKeyControl, Class IKDeriv, Class IKEnumCallback, Class JointParams, Class AngAxis, Class Quat, Class Matrix3, Class Point3, Class ScaleValue, Class Interval.
Overview
Controllers are the plug-in type responsible for directing all animation in MAX. This topic provides information on working with controllers. There is an overview of the princial classes involved when creating and working with controllers, a list of the various controller types in MAX, information on accessing the keyframe for the systems controllers, and a note about the importance of undo / redo as related to controllers.
Principal Classes
The following classes are the main ones used when dealing with controllers in the SDK.
This is the base class for the creation of controller plug-ins.
This class provides a simplified way to create controller plug-ins. Developers who sub-classs their plug-in from this class will have fewer methods to implement.
This class is used to access the properties of controllers. The standard 3ds max plug-ins support this interface. Plug-In developers are encouraged to do so as well. This allows other third-party developers to access your controller's data.
This class is used to allow a transform controller to know that it is being specifically moved, rotated, or scaled.
Ease curves vary the timing of a superior function curve. A normal function curve charts an animated parameter value over time. An Ease curve charts changes to the time of a function curve over time. A 3ds max user may apply multiple ease curves to a parameter. This class holds a list of ease curves and allows developers to access their data.
The value of a multiplier curve is a scale factor applied to the value of its superior function curve. This class holds a list of multiplier curves and allows developers to access their data.
There are several interface classes that provide access to the parameters for the standard 3ds max controllers. These are listed below:
Path Controller: Class IPathPosition.
Noise Controller: Class INoiseControl.
Surface Position: Class ISurfPosition.
Link Inheritance Controller: Class ILinkCtrl.
Look At Controller: Class ILookatControl.
Controller Types in MAX
The basic data types that can be animated by controllers are:
Integer values (int).
Floating point values (float).
Three floats (Point3). Note: The Point3 class is also used for Color Controllers.
Position (Matrix3).
Scale (ScaleValue).
Transform (Matrix3).
Accessing Keyframe Data of Controllers
Developers have access to the data of MAX's keyframe and procedural controllers. There is a separate Advanced Topics section on this topic. See Keyframe and Procedural Controller Data Access.
The Undo Mechanism and Transform Controllers
The following is a discussion of how a transform controller responds to movement of the mouse when the user is dragging and how the undo mechanism is involved.
When the user first clicks the mouse button down to begin a drag operation, the initial position of a node is stored. As each move takes place a new vector is calculated from the initial position to the new position of the mouse. This new calculation is used to update the position of the node. This is different than accumulating the new position from the previous position. The accumulation approach can introduce error. It may also be a problem for the user to get back to the initial position of the node if they move the mouse back to the initial position.
3ds max uses the undo mechanism to avoid the problems associated with the accumulation approach. Every time the user moves the mouse 3ds max re-computes the entire modification. So 3ds max uses the original point and the current location of the mouse to compute the position. What this means internally is that every time the user moves the mouse the state at initial mouse down must be restored. To do this, when the mouse is initially pressed, theHold.Begin() is called to create a RestoreObj that stores the initial state. When the mouse is moved, theHold.Restore() is called. This restores the state to when theHold.Begin() was called.
As noted above, when the user initially mouses down, theHold.Begin() is called. Then at each mouse move theHold.Restore() is called. In iterative operations such as this it is often useful to set one of the flags of Animatable to indicate that a restore object is being held. In the example above, when the user first clicks down on the mouse the developer checks if theHold is holding and if it is calls theHold.Put() to register a restore object. Then the developer calls a method of Animatable SetAFlag(A_HELD). This sets the A_HELD bit of the Animatable aflag data member to indicate the restore object is held. Then on each iteration the bit is tested to see if it is set and if so another restore object is not registered. A single restore object can be restored over and other again.
When theHold.Accept() or theHold.Cancel() is called, the system calls a method of the restore object called EndHold(). The developer may then clear the A_HELD bit to indicate the restore object is no longer being held.
For sample code that does this see any of the transform controllers, for example, \MAXSDK\SAMPLES\CONTROLLERS\BOOLCTRL.CPP. Also, see the Advanced Topics section on Undo / Redo.
Global Functions
There are some global functions developer may use that relate to controllers. These provide things such as setting the default controllers used for various controller types, creating new instances of different controller types, turning animation mode on and off, temporarily suspending animate mode, and getting/setting the animation start and end times. There are also some global functions which provide access to the default tangent types for both the Bezier and TCB controllers. See List of Additional Controller Related Functions to review them.