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.
