AlAction

Synopsis

#include <AlAction.h>

class AlAction : public AlObject

virtual	~AlAction();

virtual statusCode	deleteObject();

virtual AlObjectType	type() const;

virtual const char*	name() const;

virtual statusCode	setName(const char *);

const char*	comment() const;

AlActionExtrapType	extrapTypePRE() const;

AlActionExtrapType	extrapTypePOST() const;

statusCode	setComment(const char *);

statusCode	setExtrapTypePRE(AlActionExtrapType);

statusCode	setExtrapTypePOST(AlActionExtrapType);

AlAction*	copy() const;

statusCode	copyD();

double	eval( double, AlTripleComponent = kX_COMPONENT ) const;

int	numChannelReferences() const;

AlChannel*	channelReference(const int) const;

Description

AlAction is the base class for an Alias action. An action is an entity that will map time to a value. In Alias, there are two types of actions: parameter curve actions, represented by the derived class AlParamAction, and motion path actions, represented by the derived class AlMotionAction.

You can create new AlActions by creating an AlParamAction or an AlMotionAction. Existing actions can be accessed either through the global list of actions (AlUniverse::firstAction(), AlUniverse::nextAction()) or through the list of actions that a channel uses to animate a field of an item (AlChannel::appliedAction()). If you delete an action, it may cause other classes to be deleted (for example, AlKeyframe, and AlChannel if the action was the base action of a channel).

AlAction::~AlAction()

Description

Deletes an AlAction wrapper object.

statusCode AlAction::deleteObject()

Description

Deletes an action. The action is removed from any channel that uses it as a time warp. If the action is a base action of a channel, the channel is also deleted.

Return Codes

sSuccess - the data for the action was successfully deleted

sInvalidObject - the action was not valid the data may have been deleted already)

AlObjectType AlAction::type() const

Description

Returns the class identifier ’kActionType’.

const char* AlAction::name() const

Description

Returns the name of the action.

statusCode AlAction::setName(const char *newName)

Description

Changes the name of the action. If the given name is not a unique name in the universe, then a unique name is generated based on the given name and this name is given to the action. In this case, a status code of sNameChangedToUniqueOne is returned.

Arguments

< newName - new name for action

Return Codes

sSuccess - name was changed to newName

sInvalidArgument - the given string is NULL

sInvalidObject - the action is not valid

sNameChangedToUniqueOne - name was changed to be unique

const char* AlAction::comment() const

Description

Returns the comment on the action.

statusCode AlAction::setComment(const char *newComment)

Description

Makes a copy of ’newComment’ and replaces the existing comment on the action with this new comment.

Arguments

< newComment - the new comment to assign to the action

Return Codes

sSuccess - action’s comment was changed to newComment

sInvalidArgument - newComment was NULL

sInvalidObject - this action is not valid

AlActionExtrapType AlAction::extrapTypePRE() const

Description

Gets the out-of-range, or extrapolation to infinite type of the action before its defined range. If the type could not be retrieved, kEXTRAP_INVALID is returned.

statusCode AlAction::setExtrapTypePRE(AlActionExtrapType extrapType)

Description

Sets the out-of-range, or extrapolation to infinite type of the action before its defined range to the given extrapolation type.

Arguments

< extrapType - extrapolation type to set for action before defined range

Return Codes

sSuccess - the extrapolation type was successfully determined

sInvalidObject - the action was not valid

sInvalidArgument - the given extrapolation type was not valid

AlActionExtrapType AlAction::extrapTypePOST() const

Description

Returns the out-of-range, or extrapolation to infinite type of the action after its defined range. If the type can not be retrieved, kEXTRAP_INVALID is returned.

statusCode AlAction::setExtrapTypePOST(AlActionExtrapType extrapType)

Description

Sets the out-of-range, or extrapolation to infinite type of the action after its defined range to the given extrapolation type.

Arguments

< extrapType - extrapolation type to set for action after defined range

Return Codes

sSuccess - the extrapolation type was successfully determined

sInvalidObject - the action was not valid

sInvalidArgument - the given extrapolation type was not valid

AlAction* AlAction::copy() const

Description

Makes a copy of this action and returns the copy. If the copy fails, NULL is returned. Note that this method copies the action NOT the wrapper object.

statusCode AlAction::copyD()

Description

Makes a copy of the action (not the wrapper) and modifies the wrapper to point to the new action. This method is faster than AlAction::copy() above.

Return Codes

sSuccess - the action was successfully copied

sInvalidObject - the action was not valid

sFailure - the action was not valid or the copy failed

double AlAction::eval( double time, AlTripleComponent compo ) const

Description

Evaluates this action at the given time, and returns the value of the action at that time. If the action is an AlMotionAction, then you must specify which component of the resulting (x,y,z) value to retrieve using the optional second argument. If the action is not valid, 0.0 is returned.

Evaluation of an AlParamAction is as follows

An animation parameter curve is a "Poon-Ross" spline (developed by Angus Poon and Dave Ross). 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). If we call this spline C(t) = (x(t), y(t)), then we see that it is fairly straightforward to compute for the case when x = T since x(t) = t. So we would get C(t) for x = T is (T, y(T)). To compute a point on a curve segment C(t) (which is bounded by the CVs (t1, y1), (t2, y2) and has tangents m1 and m2 at the start and end of the segment) at t = T, we first make the mapping

T’ = (T - t1) / (t2 - t1)

so that t is in the range [0, 1]. We then get the y value off of the curve segment using the standard computation

C(T) = [T’^3 T’^2 T’ 1] * H *     | y1 | | y2 |                                    | m1 | | m2 |

where H is the hermite basis matrix.

Arguments

< time - the time at which to evaluate the action

< compo - which component to get, for motion actions

double AlChannel::sample( void ) const

Description

Samples the channel without actually evaluating it. The value of the current parameter is read without any updates being done. The channel is sampled at the current time. This method is faster than eval(), and is useful in cases where eval() has already been called, either explicitly or through a viewFrame operation.

If this method succeeds, it returns the value of the channel at the current frame. If it fails, 0.0 is returned.

int AlAction::numChannelReferences() const

Description

Returns the number of channels that use this action. If 0 is returned, this action is considered non-referenced. Note that if one channel uses this action 2 times, this is counted as 2 references. Also note that if the action is not valid -1 is returned.

AlChannel* AlAction::channelReference(const int n) const

Description

Returns the ’n’th AlChannel that references this AlAction. If ’n’ is less than 1, or greater than the number of channels that reference this action (as returned by AlAction::numChannelReferences()), then NULL is returned. The list of channels is not in any particular order.

Arguments

< n - the index between 1 and numChannelReferences() of the channel reference to return.