Main Index : Reference :

PluginTrack

Description

Definition

class PluginTrack : BaseTrack
{
public:
  PluginTrack();
  
  [int] GetID() = 0;
  [string] GetName() = 0; 
 
  [bool] Animate([BaseDocument] doc, [BaseObject] op, [BaseSequence] seq, 
                 [BaseTime] doctime, [float] fac, [float] rel, 
                 [BaseKey] k1, [BaseKey] k2) = 0;
                 
  [bool] ForeignReference();
  [bool] UseMenu();

  [bool] Copy([PluginTrack] dest);
  [bool] Save([HyperFile] hf);
  [bool] Load([HyperFile] hf);

  [bool] Message([int] type, [VariableChanged,BaseContainer] data);
}

Explanation

A class to derive animation plugin tracks from.

Members

GetID()

Should return the id of the plugin. Must be overloaded in derived classes.

GetName()

Should return the name of the animation track. Must be overloaded in derived classes.

Animate( doc, op, track, seq, doctime, fac, rel, k1, k2 )

[bool] Animate([BaseDocument] doc, [BaseObject] op, [BaseSequence] seq, 
               [BaseTime] doctime, [float] fac, [float] rel, 
               [BaseKey] k1, [BaseKey] k2) = 0;

Called during redraw or whenever CINEMA 4D wants to evaluate the animation track. Must be overloaded in derived classes. Return TRUE if the animation was successfully evaluated. The parameters are:

Parameter	Explanation
doc	The document.
op	The object to be animated.
seq	The animation sequence.
doctime	The current time as a BaseTime object.
fac	A value between 0.0 and 1.0 that gives the current position along the sequence. If the time is outside of the sequence it's either 0.0 or 1.0.
rel	The relative position between k1 and k2 as a value between 0.0 and 1.0.
k1	The next key to the left of the current time. Is NULL before the first key.
k2	The next key to the right of the current time. Is NULL after the last key

All times are given with respect to time curves etc., so doctime might not be the same as doc->GetTime(). It is the responsibility of each plugin to interpolate the values in k1 and k2 correctly using rel.

Important: Remember that both k1 and/or k2 might be NULL!

ForeignReference()

If the editor is running with two planes (active plane and inactive plane), CINEMA 4D does not know if the animation plugin references other objects. So CINEMA 4D has to switch to a one plane mode where the whole scene has to be redrawn every time if one or more of your tracks are there (even if they do nothing). To speedup things you can overload ForeignReference() and return whether you are referencing another object or not.

For example, if you are only modifying the position of your own object then you can return FALSE. Only if you are programming something similar to "AlignToSpine" or "AlignToObject" you have to return TRUE, because then there is unfortunately no other way than to redraw the whole scene.

Note: This optimization shows by principle no effect when OpenGL is turned on!

UseMenu()

Overload this function and return TRUE if you want your plugin to be added to the New Track menu in the Timeline.

Copy( dest )

This function must be overloaded if one wants to use custom variables in the derived track (i.e. not only the container). The function should copy any custom variables from this to dest and return TRUE. Otherwise the custom variables are lost when C4D wants to copy the track.

Save( hf )

This function must be overloaded if one wants one's custom variables to be saved to disk. Use the HyperFile object that C4D sends to the function, hf, to save all of your variables and return TRUE.

Tips: It might be a good idea to use the first field in the HyperFile to save a version number for the plugin. Otherwise future versions of the plugin, with possibly different variables, won't know how to load the old track's data.

Load( hf )

This function must be overloaded to load saved variables from disk. Load them from the HyperFile object in the same order as they were stored by Save() and return TRUE.

Message( type, data )

Overload this function to be able to receive messages, like MSG_POINTS_CHANGED.