Class IKeyControl
See Also: Class Animatable, Class IKey, Class Control, List of SuperClass IDs, Keyframe and Procedural Controller Data Access.
class IKeyControl
Description:
This is an interface into the TCB, Linear, and Bezier keyframe controllers. It allows a developer to add, delete, retrieve and store the keys of the controller. This is for controllers that have made their keys accessible using this interface. 3ds max has done this for its keyframe controllers. It is up to other third party developers to decide if they wish to make their keys available through this interface as well. See below for more details.
It is up to the developer to make sure that the IKey* points to a key of the appropriate derived class based on the ClassID() of the controller. For the details of using these APIs see the Advanced Topics section Keyframe and Procedural Cotroller Data Access.
All methods of this class are implemented by the system.
To get a pointer to this interface given a pointer to a controller, use the following macro (defined in ANIMTBL.H ). Using this macro, given any Animatable, it is easy to ask for the control interface.
#define GetKeyControlInterface(anim)
((IKeyControl*)anim->GetInterface(I_KEYCONTROL))
A plug-in developer may use this macro as follows:
IKeyControl *ikc = GetKeyControlInterface(anim);
This return value will either be NULL or a pointer to a valid controller interface. Here is an example of getting the controller interface from a node in the scene. First get the position controller from the node (see Class INode) and then get the controller interface.
Control *c;
c = node->GetTMController()->GetPositionController();
IKeyControl *ikeys = GetKeyControlInterface(c);
With this controller interface you can use its methods to get information about the keys.
int num = ikeys->GetNumKeys();
Developers should note that the values that are retrieved from this class may differ from the values that appear in Key Info in the 3ds max user interface. For instance, the Intan and Outtan values are multiplied by the global function GetFrameRate() when displayed. Additionally, the sign of angles (+ or -) may be reversed from the what is found in the UI. For example, the following shows the values shown in Key Info versus the values retrieved from GetKey():
Motion branch Key Info:
Key#1
X: -1.0
Y: 0.0
Z: 0.0
Ang: 0.0
Key#2
X: 0.0
Y: 1.0
Z: 0.0
Ang: 90.0
Key#3
X: 0.0
Y: 0.0
Z: 1.0
Ang: 90.0
ITCBRotKey key;
ikc->GetKey(i, &key);
Key#1
X: 1.0
Y: 0.0
Z: 0.0
Ang: 0.0
Key#2
X: 0.0
Y: -1.0
Z: 0.0
Ang: 1.57
Key#3
X: 0.0
Y: 0.0
Z: -1.0
Ang: 1.57
Sample code in the SDK that makes use of this interface is the 3D Studio Export plug-in. See \MAXSDK\SAMPLES\IMPEXP\3DSEXP.CPP.
The following classes are available for keyframe data storage:
Tension/Continuity/Bias:
Bezier:
Linear:
Note: Developers creating controller plug-ins may wish to make their keys accessible to others through this interface. The way 3ds max does this is by deriving the controllers from this class (IKeyControl) in addition to class Control. So, multiple inheritance is used, and 3ds max then implements the methods of this class to provide the interface.
Below is the code from 3ds max implementation of Animatable::GetInterface() (as part of a template). Note the cast of the this pointer to IKeyControl.
INTERP_CONT_TEMPLATE
void* InterpControl<INTERP_CONT_PARAMS>::GetInterface(ULONG id)
{
if (id==I_KEYCONTROL) {
return (IKeyControl*)this;
} else {
return Control::GetInterface(id);
}
}
Methods:
Prototype:
virtual int GetNumKeys()=0;
Remarks:
Returns the total number of keys.
Prototype:
virtual void SetNumKeys(int n)=0;
Remarks:
Sets the number of keys allocated. This may add blank keys or delete existing keys. It is more efficient to set a large number of keys using this method and then calling SetKey() to store the values rather than calling AppendKey() over and over for each key.
Parameters:
int n
The new number of keys.
Prototype:
virtual void GetKey(int i,IKey *key)=0;
Remarks:
Retrieves the 'i-th' key and stores the result in key.
Parameters:
int i
The index of the key to retrieve.
IKey *key
Storage for the key data.
Prototype:
virtual void SetKey(int i,IKey *key)=0;
Remarks:
Sets the 'i-th' key. The 'i-th' key must exist.
Parameters:
int i
The index of the key to set.
IKey *key
Pointer to the key data.
Prototype:
virtual int AppendKey(IKey *key)=0;
Remarks:
This method will append a new key onto the end of the key list. Note that the key list will ultimately be sorted by time.
Parameters:
IKey *key
Pointer to the key data to append.
Return Value:
The key's index.
Prototype:
virtual void SortKeys()=0;
Remarks:
This method should be called if any changes are made that would require the keys to be sorted. The keys are stored in order by TimeValue.
Prototype:
virtual DWORD &GetTrackFlags()=0;
Remarks:
Retrieves the track flags.
Return Value:
One or more of the following values:
TFLAG_CURVESEL
Determines if the curve is selected in the track view in the function curve editor.
TFLAG_RANGE_UNLOCKED
Determines if the range is locked to the first key and the last key. If a user goes into Position Ranges mode and moves the range bar, the range becomes unlocked.
TFLAG_LOOPEDIN
This is set if the in out of range type is set to loop.
TFLAG_LOOPEDOUT
This is set if the out of range type is set to loop.
TFLAG_COLOR
Set for Bezier Point3 controllers that are color controllers.
TFLAG_HSV
Set for color controls that interpolate in HSV rather than RGB.