IKeyControl Class Reference

#include <istdplug.h>

Class Description

See also

Class Animatable, Class IKey, Class Control, Super Class IDs, 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 Controller 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);
    }
}

Inheritance diagram for IKeyControl:

Public Types
typedef IKey	KeyType

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 ()

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...

Member Typedef Documentation

typedef IKey KeyType

Member Function Documentation

virtual int GetNumKeys ( )

pure virtual

Remarks

Returns the total number of keys.

virtual void SetNumKeys ( int  n )

pure virtual

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

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

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

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

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

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 ( )

inlinevirtual

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