Lesson 4: Animation Controllers

Procedural Controllers

Procedural controllers are extended from the base class Control. The main responsibility of these controllers is to answer a query from 3ds Max on a parameter's value at the given time, and to include the validity Interval for that answer. Including a validity interval reduces the communication cost between 3ds Max and your plug-in since 3ds Max does not query the controller during the intervals in which the value does not change.

Procedural controllers do not need to maintain a cache since 3ds Max never tries to write any value to the parameter they are controlling. Developers can use an algorithm that produces values for different times. This should be done in the member function Control::GetValue() and is explained in the example below, where a procedural controller plug-in named SampleProCtrl is assigning a periodic movement to an object:

void SampleProCtrl::GetValue(TimeValue t, void *ptr, Interval &valid, GetSetMethod method)
{
    Point3 p3OurAbsValue(0, 0, 0);
    p3OurAbsValue.x = 15*sin((float)t/960);
    p3OurAbsValue.y = (float)t/192;
	   valid.Set(t,t+1); //This answer is only valid at the calling time.

	   if (method == CTRL_ABSOLUTE)
	   {
	      	Point3* p3InVal = (Point3*)ptr;
		      *p3InVal = p3OurAbsValue;
	   }
	   else // CTRL_RELATIVE
	   {
		      Matrix3* m3InVal = (Matrix3*)ptr;
		      m3InVal->PreTranslate(p3OurAbsValue);
	   }
}

Controller::GetValue() parameters:

• TimeValue t is the time at which 3ds Max wants to know the value of the animated parameter. It is essentially an integer number, and each 4800 unit is equal to one second.
• GetSetMethod method indicates whether your implementation should return the absolute (CTRL_ABSOLUTE) or relative (CTRL_RELATIVE) value of the animated parameter. If a relative answer is required, the reference value will be the value 3ds Max pre-loads in the *ptr parameter in its call to this function.
• Void* ptr points to the address where the value of the animated parameter should be written. If a relative answer is required (method == CTRL_RELATIVE), it initially holds the reference point. It is a void pointer because the answer can be any of the six types above and needs to be type-casted in your code according to the type of animated parameter.
• Interval &valid is an output parameter and indicates how long the value you computed for ptr is valid. Failing to update this parameter will be interpreted as "forever" by 3ds Max, and it will not call this function at any later time. This can result in freezing your parameter in its initial value in the course of animation.

This controller animates the object with a periodic movement along the x axis with the mathematical function x=a.sin(w.t). The terms a and w are just two coefficients to control the amplitude and frequency of the periodic movement so the movement can be observed easily in the viewport (a = 15 and w = 1/960 in this example). There is also a linear movement along the y axis (y=b.t where b is a coefficient representing the linear speed and is set to 1/192). The function Matrix3::PreTranslate() is used if a relative answer is required. It applies an incremental translation transformation to the matrix m3InVal that is initialized to the reference point.

The project Lesson4a implements an animation controller plug-in. The class name is SampleProCtrl and it appears in 3ds Max with the name "Sample Procedural Controller". To assign it to an object in the view port, while the object is selected in 3ds Max click on the Motion tab, expand Assign Controller and select Position from the Transform: Position/Rotation/Scale tree. Then click on the green check mark under the title Assign Controller to find "Sample Procedural Controller" and assign it to your object. You can then click on the Play Animation button to see the effect of your animation controller. You can also use the Curve Editor to assign it to an object.

Although we are not holding any reference in our very basic controller, you can see that the four basic functions discussed in Lesson 3 are implemented here. That is because an animation controller plug-in extends from the control class, which indirectly extends from the ReferenceMaker class. You also need to implement the pure virtual function Control::Copy() to be able to instantiate from your plug-in class. Notice that the x, y and z curves are observed all in the same graph in the curve editor and you cannot have them in separate graphs. You will need to break your position controller into basic independent controllers and implement two other functions, Control::NumSubs() and Control::SubAnim() to observe them as separate graphs in the curve editor. We talk about these functions later in this lesson.

Keyframe Controllers

A keyframe controller extends from the base class Control, similar to a procedural controller. It only differs from a procedural controller in the way it implements the member functions. Similar to a procedural controller, 3ds Max calls Control::GetValue() to read values of an animated parameter with a keyframe controller. However, it can also write values to an animated parameter of a keyframe controller. When calling to write a value to the controller, 3ds Max indicates at which time and for how long the value it provides is valid. It is the responsibility of the keyframe controller to maintain a data cache to store those values and interpolate between them for unknown values. 3ds Max has no restriction on how the controller plug-in handles this cache. While it is possible to implement and maintain your own cache to keep this data, it is very common to use multiple default basic controllers to form the aggregated animation controller. In such case, it is a good practice to hold one reference per basic controller and access them through the references.

The simplest type of controller is the float controller. It can be combined to form the elements of an aggregated controller. For example, three float controllers can be used to control each of the x, y and z elements in a point3 or position controller. While developers can implement any interpolator (e.g. constant, linear, polynomial, etc) for float controllers, it is normal in the computer graphics applications to use Bezier interpolation. 3ds Max SDK already has a default implementation of a float controller that uses this type of interpolator. Developers can use the function Control *NewDefaultFloatController() to instantiate a new object of a float controller with Bezier interpolation. We will use this function for our example here.