This reference page is linked to from the following overview topics: Controller API Elements, Controller Data Access, Keyframe Data Access Classes and Methods, Keyframe Interpolation, Procedural Controller Data Access, Making Controllers Lockable.

Detailed Description

See also:: Class Animatable, Class IKey, Class Control, List of SuperClass IDs, Keyframe and Procedural Controller Data Access.

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 AnimatableInterfaceIDs.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.

Tension/Continuity/Bias:: Class ITCBKey

Class ITCBFloatKey

Class ITCBPoint3Key,

Class ITCBRotKey

Class ITCBScaleKey

Bezier:: Class IBezFloatKey

Class IBezPoint3Key

Class IBezQuatKey

Class IBezScaleKey

Linear:

Class ILinFloatKey

Class ILinPoint3Key

Class ILinRotKey

Class ILinScaleKey

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);
    }
}

#include <istdplug.h>

Inheritance diagram for IKeyControl:

[legend]

List of all members.

Public Member Functions
virtual int	GetNumKeys ()=0
virtual void	SetNumKeys (int n)=0
virtual void	GetKey (int i, IKey *key)=0
virtual void	SetKey (int i, IKey *key)=0
virtual int	AppendKey (IKey *key)=0
virtual void	SortKeys ()=0
virtual DWORD &	GetTrackFlags ()=0
virtual int	GetKeySize ()

Member Function Documentation

virtual int GetNumKeys ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the total number of keys.

virtual void SetNumKeys ( int n ) [pure virtual]

Search for all occurrences

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.

virtual void GetKey	(	int	i,
		IKey *	key
	)		`[pure virtual]`

Search for all occurrences

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.

virtual void SetKey	(	int	i,
		IKey *	key
	)		`[pure virtual]`

Search for all occurrences

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.

virtual int AppendKey ( IKey * key ) [pure virtual]

Search for all occurrences

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.

Returns:: The key's index.

virtual void SortKeys ( ) [pure virtual]

Search for all occurrences

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.

virtual DWORD& GetTrackFlags ( ) [pure virtual]

Search for all occurrences

Remarks:: Retrieves the track flags.

Returns:: 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.

virtual int GetKeySize ( ) [inline, virtual]

Search for all occurrences

Remarks:: Retrieves the maximim size of a key in bytes. Implement only if size of IKey is greater than the default value.

Returns:: 128 (default), or the value you specify in your implementation.

{return 128;}

IKeyControl Class Reference

Detailed Description

Public Member Functions

Member Function Documentation