Keyframe Data Access Classes and Methods

This section discusses access to keyframe controller data. The 3ds Max API provides a class IKeyControl. This class provides an interface into the TCB, Bezier, and Linear keyframe controllers allowing a developer to add, delete, retrieve and update the keys of the controller.

Use of the IKeyControl methods requires you to include \\MAXSDK\INCLUDE\ISTDPLUG.H, i.e.:

#include"ISTDPLUG.H"

The standard 3ds Max PRS keyframe controllers provide access to their keys using this class. To get an interface you can use to call methods of IKeyControl use the following macro (defined in \\MAXSDK\INCLUDE\ANIMTBL.H):

#define GetKeyControlInterface(anim)
   ((IKeyControl*)anim->GetInterface(I_KEYCONTROL))

You may use this macro as follows:

IKeyControl *ikc = GetKeyControlInterface(anim);

The return value will either be NULL or a pointer to a valid controller interface. A NULL pointer indicates the controller does not support this interface to allow access to its data.

The following is an example of getting a position controller interface from a node in the scene. The first thing that happens is the position controller is retrieved from the node (using methods of class INode and Control) and then the controller interface is returned via the GetKeyControlInterface() macro:

Control *c;
c = node->GetTMController()->GetPositionController();
 
IKeyControl *ikeys = GetKeyControlInterface(c);
if (!ikeys) return; // No interface available to access the keys...

The methods of IKeyControl may be called using the ikeys pointer. For example the method IKeyControl::GetKey() retrieves the nth You'll need to check the ClassID of the controller so you can pass the appropriate class to the method to retrieve the keys. There are three type of controllers and five data types that are supported by the IKeyControl interface. The controller types are Tension/Continuity/Bias (TCB), Bezier, and Linear. The data types are floating point (float), Position (Point3), Rotation (Quat or AngAxis), and Scale (ScaleValue). The type of key you pass to the GetKey() or SetKey() methods depends on both the controller and data type.

The following classes are used for key storage for each valid possibility:

• Tension/Continuity/Bias Controllers: ITCBFloatKey, ITCBPoint3Key, ITCBRotKey, ITCBScaleKey.
• Bezier Controllers: IBezFloatKey, IBezPoint3Key, IBezQuatKey, IBezScaleKey.
• Linear Controllers: ILinFloatKey, ILinPoint3Key, ILinRotKey, ILinScaleKey.

Example

ITCBPoint3Key tcbPosKey;
int numKeys = ikeys->GetNumKeys();
 
if (c->ClassID() == Class_ID(TCBINTERP_POSITION_CLASS_ID, 0))
{
   for (i = 0; i < numKeys; i++)
   {
     ikeys->GetKey(i, &tcbPosKey);
     DebugPrint(_T("\nPosition Key: %d=(%.1f, %.1f, %.1f)"),
            i, tcbPosKey.val.x,
            tcbPosKey.val.y,
            tcbPosKey.val.z);
   }
}
 

Note how an instance of the ITCBPoint3Key class was passed to GetKey() since the ClassID indicates the controller is a TCB controller and we want position keys (which operate on Point3s).