Basic interface to derived class of actions for parameter curve actions.

Synopsis

#include <AlParamAction.h>
class AlParamAction : public AlAction
AlParamAction();
virtual    ~AlParamAction();
virtual AlObject*    copyWrapper() const;
virtual AlObjectType    type() const;
AlKeyframe*    firstKeyframe() const;
AlKeyframe*    lastKeyframe() const;
statusCode    addKeyframe( double, double, AlKeyframe *&, boolean = TRUE, AlTangentType = kTangentFlat, AlTangentType = kTangentFlat );
statusCode    addKeyframe( double, double, AlKeyframe &, boolean = TRUE, AlTangentType = kTangentFlat, AlTangentType = kTangentFlat );
statusCode    addKeyframe( double, double, boolean = TRUE, AlTangentType = kTangentFlat, AlTangentType = kTangentFlat );
int    numberOfKeyframes() const;
statusCode     applyIteratorToKeyframes( AlIterator*, int& );
statusCode    addKeyframeRange( int, double*, double*, boolean = TRUE, AlTangentType* = NULL, AlTangentType* = NULL );
statusCode    deleteKeyframeRange( double, double );

Description

An AlParamAction is derived from an AlAction. This particular action has a list of AlKeyframes which are CVs on a Poon-Ross spline. This spline is basically a Hermite-linear spline. That is, it is a Hermite in y (the vertical axis) and a linear in x (the horizontal axis).

In order to create an AlParamAction, you must have at least one valid, created AlKeyframe that will be the first keyframe of the action. After the AlParamAction is created, you can add other keyframes to the AlParamAction. Note that two AlKeyframes cannot have the same location. If you add a keyframe to the action that has the same location as an existing keyframe of the action, the existing keyframe will be deleted. Since an AlKeyframe is created at (0, 0), you cannot create a bunch of AlKeyframes, add them to the AlParamAction, and then modify their locations later, because the AlParamAction will only have one keyframe (the others will have been deleted as each successive keyframe with the same location is added to the AlParamAction). You must set the location of the AlKeyframe before adding it to the AlParamAction.

If you copy an AlParamAction, all the keyframes (and the keyframes’ streams) will also be copied. If you delete an AlParamAction, all its Keyframes will be deleted.

AlParamAction::AlParamAction()

Description

Constructs an AlParamAction wrapper object. Use the create() method to initialize the AlParamAction.

AlParamAction::~AlParamAction()

Description

Deletes an AlParamAction wrapper object.

AlObject* AlParamAction::copyWrapper() const

Description

Returns a duplicate of this wrapper object, pointing to the same object.

AlObjectType AlParamAction::type() const

Description

Returns the class identifier ’kParamActionType’.

AlParamAction* AlParamAction::asParamActionPtr()

Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlKeyframe* AlParamAction::firstKeyframe() const

Description

Returns the first keyframe of this parameter curve action.

AlKeyframe* AlParamAction::lastKeyframe() const

Description

Returns the last keyframe of this parameter curve action.

statusCode AlParamAction::addKeyframe( double location, double value, AlKeyframe &kf, boolean recompute, AlTangentType intan, AlTangentType outtan )

Description

Similar to addKeyframe, but returns the newly created AlKeyframe in ’kf’. This avoids the creation and deletion of wrappers when creating many keys.

An example loop may look like

     AlKeyframe key;      for( int i =0; i < 100; i++ )      {          param->addKeyframe( i, 1, key, ....)      }

Arguments

< location - the time value for the keyframe

< value - the value of the keyframe

> Alkeyframe &kf - the resulting keyframe

< intan - the in tangent for the keyframe

< outtan - the out tangent for the keyframe

< recompute - recompute the tangents of neighboring keyframes

Return Codes

sSuccess - key frame added

sInvalidArgument - kf was NULL

sFailure - key frame not added

statusCode AlParamAction::addKeyframe( double location, double value, AlKeyframe *& kf, boolean recompute, AlTangentType intan, AlTangentType outtan )

Description

Similar to addKeyframe, but allocates a wrapper and returns the newly created AlKeyframe. It is up to you to delete these wrappers. Use this overloaded form if you wish to have the wrapper created for you.

Below is an example code fragment

     Alkeyframe *key1, *key2, *key3;      param->addKeyframe( 0, 1, key1, ....       param->addKeyframe( 1, 1, key2, ....       param->addKeyframe( 2, 1, key3, ....       ...      delete key1;      delete key2;      delete key3;

Arguments

< location - the time value for the keyframe

< value - the value of the keyframe

> Alkeyframe* &kf - the resulting keyframe

< intan - the in tangent for the keyframe

< outtan - the out tangent for the keyframe

< recompute - recompute the tangents of neighboring keyframes

Return Codes

sSuccess - key frame added

sInvalidArgument - kf was NULL

sFailure - key frame not added

statusCode AlParamAction::addKeyframe( double location, double value, boolean recompute, AlTangentType intan, AlTangentType outtan )

Description

Adds a keyframe to the parameter curve’s list of keyframes. If the parameter curve already has another keyframe at the same location as this keyframe, then the existing keyframe at this location will be deleted and replaced with this keyframe. If this object does not yet reference an actual Parameter Curve, a new curve will be created.

Arguments

< location - the time value for the keyframe

< value - the value of the keyframe

< intan - the in tangent for the keyframe

< outtan - the out tangent for the keyframe

< recompute - recompute the tangents of neighboring keyframes

Return Codes

sSuccess - operation completed normally

sFailure - operation failed to complete normally

sInsufficientMemory - there wasn’t enough memory to complete the operation

int AlParamAction::numberOfKeyframes() const

Description

Returns the number of keyframes in this action, or -1 if the call fails.

statusCode AlParamAction::applyIteratorToKeyframes( AlIterator* iter, int &rc )

Description

Applies the given AlIterator to all keyframes in the action. The second argument will be set to the return value of the last application of the iterator’s function. See the AlIterator class for more information.

Arguments

< iter - the iterator to be applied to each keyframe

> rc - return value of the last application of the iterator

Return Codes

sSuccess - the application of the iterator terminated normally

sFailure - the application of the iterator terminated abnormally

sInvalidArgument - the iterator was NULL

sInvalidObject - the action was invalid

statusCode AlParamAction::deleteKeyframeRange( double minValue, double maxValue )

Description

Deletes all keyframes whose "time"s are greater or equal to the "minValue" given, and less than or equal to the "maxValue" given.

Arguments

< minValue - minimum time value to delete keyframes from

< maxValue - maximum time value to delete keyframes up to

Return Codes

sSuccess - operation completed normally

sFailure - operation failed to complete normally

sInvalidObject - the action was invalid

statusCode AlParamAction::addKeyframeRange( int size, double location[], double value[], boolean recompute, AlTangentType intan[], AlTangentType outtan[])

Description

Adds a block of keyframes to the parameter curve's list keyframes. If the parameter curve already has a keyframe at the same location as one of the added keyframes, then the method will fail. If this object does not yet reference an actual Parameter Curve, a new curve will be created.If intan and outan are NULL, kTangentFlat is assumed.

Arguments

< size - size of input arrays

< location - array of keyframe locations (time values)

< value - array of keyframe values

< recompute - recompute tangents of neighboring keyframes

< intan - array of the in-tangents for keyframes

< outtan - array of the out-tangents for keyframes

Return Codes

sSuccess - operation completed normally

sInvalidArgument - one of the arguments was NULL or invalid

sInsufficientMemory - ran out of memory

sFailure - could not create action

sObjectAlreadyPresent - a keyframe already exists in given location