3ds Max C++ API Reference
IKeyControl Class Referenceabstract

#include <istdplug.h>

+ 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 voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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 voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects. More...
 
static UtilExport voidoperator 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 voidoperator 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 voidoperator 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 voidoperator 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...
 
static UtilExport voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary. More...
 
static UtilExport voidaligned_realloc (void *ptr, size_t size, size_t alignment)
 Reallocates memory on a specified alignment boundary. More...
 
static UtilExport void aligned_free (void *ptr)
 Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...
 

Detailed 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
{
if (id==I_KEYCONTROL) {
return (IKeyControl*)this;
}
else {
}
}
CoreExport FPInterface * GetInterface(SClass_ID super, Class_ID cls, Interface_ID id)
Get ID'd interface from ClassDesc for given class/sclass.
virtual CoreExport void * GetInterface(ULONG id)
Inherited from Animatable.
Definition: istdplug.h:1573
#define I_KEYCONTROL
An Animatable supporting this interface is an IKeyControl.
Definition: AnimatableInterfaceIDs.h:51

Member Typedef Documentation

◆ KeyType

typedef IKey KeyType

Member Function Documentation

◆ GetNumKeys()

virtual int GetNumKeys ( )
pure virtual
Remarks
Returns the total number of keys.

◆ SetNumKeys()

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.

◆ GetKey()

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.

◆ SetKey()

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.

◆ AppendKey()

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.

◆ SortKeys()

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.

◆ GetTrackFlags()

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.

◆ GetKeySize()

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.

1654 {return 128;}