AlKeyframe

Synopsis

#include <AlKeyframe.h>
class AlKeyframe : public AlObject
AlKeyframe();
virtual	~AlKeyframe();
virtual statusCode	deleteObject();
virtual AlObject*	copyWrapper() const;
virtual AlObjectType	type() const;
boolean	isLocked() const;
statusCode	setLock(boolean);
AlKeyframe*	prev() const;
AlKeyframe*	next() const;
statusCode	prevD();
statusCode	nextD();
double	value() const;
double	location() const;
double	inTangent() const;
double	outTangent() const;
statusCode	tangentTypes( AlTangentType&, AlTangentType& ) const;
statusCode	setValue(double, boolean = TRUE );
statusCode	setLocation(double, boolean = TRUE );
statusCode	setInTangent(double);
statusCode	setOutTangent(double);
statusCode	setTangentTypes(AlTangentType, AlTangentType, boolean = TRUE );

Description

AlKeyframe represents a keyframe belonging to an AlParamAction. The keyframe class does not have a create method. New keyframes are created using the AlParamAction::addKeyframe() methods (this is faster than creating the keyframes, then adding them to the paramaction).

A keyframe cannot belong to more than one action. Thus attempting to add a keyframe that has already been added to an AlParamAction will fail.

If an AlKeyframe is deleted and if the AlKeyframe belongs to an AlParamAction and it is the last keyframe of that parameter curve action, then the AlParamAction will also be deleted. This ensures that no AlParamAction parameter curves will exist with no keyframes.

If a keyframe is added to an AlParamAction, and another keyframe already exists in that AlParamAction with the same location as the keyframe to be added, then the existing keyframe in the AlParamAction will be deleted.

The method that applies tangent types to a keyframe (that is, setTangentTypes()) does not make much sense if the keyframe is not part of an AlParamAction. It is best to add all the desired keyframes to an AlParamAction, and then walk the list of keyframes, and call the tangent methods.

You can lock a keyframe by calling the method AlKeyframe::setLock(TRUE). If an AlKeyframe is locked, then none of the AlKeyframe methods that change its location, value, or tangents will succeed. The keyframe is non-modifiable. You can unlock the keyframe again by calling AlKeyframe::setLock(FALSE).

AlKeyframe::AlKeyframe()

Description

Constructs an AlKeyframe wrapper object.

AlKeyframe::~AlKeyframe()

Description

Deletes an AlKeyframe wrapper object.

statusCode AlKeyframe::deleteObject()

Description

Deletes a keyframe. If the keyframe is part of an action, then the keyframe will be removed from the action’s list of keyframes. If the keyframe is the last keyframe in an action, the action will also be deleted.

Return Codes

sSuccess - the object was deleted

sFailure - the object could not be deleted

sInvalidObject - the object was invalid

AlObject *AlKeyframe::copyWrapper() const

Description

Return an exact duplicate of this AlKeyframe wrapper.

AlObjectType AlKeyframe::type() const

Description

Returns the class identifier ’kKeyframeType’.

double AlKeyframe::location() const

Description

Returns the time value for this keyframe, or 0.0 if the keyframe is invalid.

statusCode AlKeyframe::setLocation(double newTime, boolean recompute)

Description

Sets the time of the keyframe to be the value given by newTime. If this keyframe is part of a parameter curve action, the list of keyframes may be reordered to reflect the new position of the keyframe. If the given newTime has the same value as the time of an existing keyframe, then this keyframe will not be moved.

Arguments

< newTime - the new value for the time of the keyframe

< recompute - whether or not to recompute tangents now

Return Codes

sSuccess - keyframe’s time was successfully changed

sFailure - keyframe is locked, thus cannot be changed

sInvalidObject - the keyframe was invalid

double AlKeyframe::value() const

Description

Returns the value of this keyframe, or 0.0 if the keyframe is not valid.

statusCode AlKeyframe::setValue(double newVal, boolean recompute)

Description

Sets the value of the keyframe to be the value given by newVal.

Arguments

< newVal - the new value for the value of the keyframe

< recompute - whether to recompute the tangents or not.

Return Codes

sSuccess - keyframe’s value was successfully changed

sFailure - keyframe is locked, thus cannot be changed

sInvalidObject - the keyframe was invalid

double AlKeyframe::inTangent() const

Description

Returns the value of the in-tangent of the keyframe. The value will be between 90.0 and -90.0, where 0.0 represents a flat (horizontal) tangent pointing to the left, 90.0 means the tangent points straight up, and -90.0 means the tangent points straight down. 0.0 is returned in the case of an error.

statusCode AlKeyframe::setInTangent(double inTangent)

Description

Sets the in-tangent of the keyframe to the given value. The tangent value must be in the range -90.0 < inTangent < 90.0.

If the given tangent value is outside this range, it is clamped to within this range.

This method requires the AlKeyframe to have been attached to an AlParamAction; otherwise, an assertion will fail.

Arguments

< inTangent - the angle in degrees to which the keyframe’s in tangent should be set

Return Codes

sSuccess - keyframe’s inTangent was successfully changed

sFailure - keyframe is locked, thus cannot be changed or failed to make tangent FIXED

sInvalidObject - the keyframe was invalid

double AlKeyframe::outTangent() const

Description

Returns the value of the out-tangent of the keyframe. The value will be between 90.0 and -90.0, where 0.0 represents a flat (horizontal) tangent pointing to the right, 90.0 means the tangent points straight up, and -90.0 means the tangent points straight down. This method returns 0.0 if the keyframe is invalid.

statusCode AlKeyframe::setOutTangent(double outTangent)

Description

Sets the out-tangent of the keyframe to the given value. The tangent value must be in the range -90.0 < outTangent < 90.0.

If the given tangent value is outside this range, it is clamped to within this range.

This method requires the AlKeyframe to have been attached to an AlParamAction; otherwise, an assertion will fail.

Arguments

< outTangent - the angle in degrees to which the keyframe’s out tangent should be set

Return Codes

sSuccess - keyframe’s outTangent was successfully changed

sFailure - keyframe is locked, thus cannot be changed or failed to make tangent FIXED

sInvalidObject - the keyframe was invalid

boolean AlKeyframe::isLocked() const

Description

Returns TRUE if the keyframe is locked, FALSE if it is not. A locked keyframe means that you cannot change its time, value or tangents. FALSE is returned in the case of an error.

statusCode AlKeyframe::setLock(boolean flag)

Description

Sets the lock flag of a keyframe. If the keyframe is locked, its time, value, and tangents will not be modifiable.

Arguments

< flag - TRUE (if the keyframe should be locked) or FALSE (if not)

Return Codes

sSuccess - normal completion

sInvalidObject - object is invalid

AlKeyframe *AlKeyframe::prev() const

Description

If this keyframe belongs to a parameter curve action (AlParamAction), then this method will return the previous AlKeyframe in the action (or NULL if this keyframe is the first keyframe in the action). If this keyframe does not belong to an action, NULL is returned.

AlKeyframe *AlKeyframe::next() const

Description

If this keyframe belongs to a parameter curve action (AlParamAction), then this method will return the next AlKeyframe in the action (or NULL if this keyframe is the last keyframe in the action). If this keyframe does not belong to an action, NULL is returned.

statusCode AlKeyframe::prevD()

Description

If this keyframe belongs to a parameter curve action (AlParamAction), and it is not the first keyframe in that action, this function will set the information for this AlKeyframe to refer to the previous keyframe in the action, and return sSuccess. Otherwise, the information in this object is unchanged and sFailure is returned.

Return Codes

sSuccess - this wrapper points to the next keyframe

sInvalidObject - object is invalid

statusCode AlKeyframe::nextD()

Description

If this keyframe belongs to a parameter curve action (AlParamAction), and it is not the last keyframe in that action, this function will set the information for this AlKeyframe to refer to the next keyframe in the action, and return sSuccess. Otherwise, the information in this object is unchanged and sFailure is returned.

Return Codes

sSuccess - this wrapper points to the previous keyframe

sFailure - there was no next keyframe

sInvalidObject - object is invalid

statusCode AlKeyframe::setTangentTypes(AlTangentType inTangentType, AlTangentType outTangentType, boolean recompute )

Description

Sets the in and out tangents of this keyframe to a specific type. Use kTangentUnchanged if you want either to remain unchanged.

This method requires the AlKeyframe to have been attached to an AlParamAction, otherwise an assertion will fail.

Note that this function sets the tangents on a segment. So depending on your choice of tangents, the tangents of the keyframe’s neighbors may be changed.

Arguments

< inTangentType - the type of the in tangent

< outTangentType - the type of the out tangent

< recompute - recompute the spline

Return Codes

sSuccess - keyframe’s tangents were successfully changed

sFailure - keyframe is locked, thus cannot be changed

sInvalidObject - the keyframe was invalid

statusCode AlKeyframe::tangentTypes(AlTangentType& inTangentType, AlTangentType& outTangentType) const

Description

Gets the in and out tangent types of this keyframe. If this method fails to determine the type of either the in or out tangent, sFailure is returned, and either or both of the arguments are set to kTangentUnchanged.

Arguments

> inTangentType - returned inTangent’s type

> outTangentType - returned outTangent’s type

Return Codes

sSuccess - successfully determined keyframe’s tangents

sFailure - failed to determine one of the keyframe’s tangents

sInvalidObject - the keyframe was invalid