Basic interface to Alias action.
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.
