Basic interface to Alias channels.
#include <AlChannel.h> class AlChannel : public AlObject AlChannel(); virtual ~AlChannel(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( AlAnimatable*, int, AlAction*, AlTripleComponent = kX_COMPONENT ); statusCode create( AlAnimatable *, int, const char *); virtual AlObjectType type() const; AlObject* animatedItem() const; int parameter() const; const char* parameterName() const; AlChannelDataType channelType() const; AlChannel* copy( AlAnimatable*, int ); statusCode copyD( AlAnimatable*, int ); statusCode link(AlAction*, AlTripleComponent); statusCode applyWarp(); AlParamAction* applyWarpO(); statusCode removeWarp(AlAction*); double eval( double ) const; int numAppliedActions() const; AlAction* appliedAction(const int) const; AlTripleComponent appliedActionComponent( const int ) const; const char* expressionString () const;
A channel controls how a field of an animatable item should change over time. It contains one or more actions that are evaluated at a given time and combined to produce an overall value of the channel at that time. When a channel is evaluated, for example at playback time, or, in the method AlViewFrame::viewFrame(), the value it is evaluated to is "stuffed" into the parameter of the item, thereby changing the value of that item’s parameter over time.
A channel belongs solely to one field or parameter of an animatable item. A parameter of an item is animated by at most one channel. Thus, the create() methods will fail if an attempt is made to create a channel of a field that already has a channel (that is, is already animated). Under similar conditions, the copy() method will fail.
Currently a channel must contain at least one action (the base action of the channel), and thus the create() method requires you to supply this base action. You can modify this base action using the link() method. The applyWarp() and removeWarp() methods modify the time warp actions applied to the base action of the channel. They cannot affect the base action of the channel.
The numAppliedActions() method will tell you how many actions are currently used by channel. This number will always be at least 1, since a channel must be animated by at least a base action. The appliedActions() will tell you which actions animate the channel. appliedActions(1) is the base action, and appliedActions(2 to n) are the time warp actions, where n is numAppliedActions(). If any of the actions are an AlMotionAction, then you may also want to know which of the X, Y or Z components the channel is using from the AlMotionAction (since this type of action evaluates to a triple of values). The method appliedActionComponent() can be used to determine this.
statusCode AlChannel::create(AlAnimatable *anima, int field,AlAction *faction, AlTripleComponent component)
Creates a new channel that will animate the given field of the given object. The channel is animated using the given action as a base action. If the field of the object is already animated (that is, already has a channel), then this method will fail, and a new channel will not be created. The channel will also not be created if there is a motion path curve somewhere below this DAG node.
< dagNode - DAG node that will be animated
< field - which field of the DAG node to animate
< action - base action which the channel should use
< component - if the action is an AlMotionAction, this specifies which component of the evaluation of the curve should be used when evaluating the channel; if the action is not an AlMotionAction, this argument is ignored.
statusCode AlChannel::create(AlAnimatable *anima, int field,const char *szExprText)
Creates a new channel that will attach an expression to the given field of the given object. If the field of the object is already animated or has an expression attached to it (that is, already has a channel), then this method will fail, and a new channel will not be created.
This method sends out an update message in order to have the expression evaluated properly. As a result, creating a lot of expressions could be a slow process.
int AlChannel::parameter() const
Returns the field of the item that is being animated by this channel. The return value is cast from whatever enum type corresponds to the animatable item, to an integer. For example: If this channel is animating an AlDagNode, then this method will return an AlDagNodeFields cast to an integer. If this channel is animating an AlCamera, then this method will return an AlCameraFields cast to an integer. If this channel is animating an AlShader, AlTexture or an AlEnvironment, then this method will return an AlShadingFields cast to an integer. If the call could not be completed, -1 is returned.
AlChannel* AlChannel::copy(AlAnimatable *anima, int field)
Copies this channel, and applies the copied channel to animating the given field of the given object. If the given object is already animated by that field, this method will fail. When the channel is copied, each action in the original channel will be reused by the copy of the channel. This means that each of the actions will now be referenced by at least two channels. The new copy of the channel will be returned. If any error occurred (for example object is already animated by the given field, or animating this object would animate a motion path) then NULL will be returned.
statusCode AlChannel::copyD(AlAnimatable *anima, int field)
Copies this channel, and applies the copied channel to animating the given field of the given object. If the given object is already animated by that field, this method will fail. When the channel is copied, each action in the original channel will be reused by the copy of the channel. This means that each of the actions will now be referenced by at least two channels. The new copy of the channel will be returned. If any error occurred (for example object is already animated by the given field, or animating this object would animate a motion path) then NULL will be returned.
statusCode AlChannel::link(AlAction* action, AlTripleComponent component)
Replaces the base action of this channel with the given action. For example, if this channel is currently animated by action A, then this method will remove action A from the channel, and replace it by the given action, ’action’. This channel will now only be animated by ’action’. If this channel is currently animated by three actions, a base action A, and two time warp actions T1 and T2, then this method will replace the base action A with the given ’action’ so that the channel will now be animated by the base action ’action’ and the two time warp actions T1 and T2.
< action - the action with which the channel should replace its current base action
< component - if the action is an AlMotionAction, this specifies which component of the evaluation of the motion action curve should be used when evaluating the channel; if the action is not an AlMotionAction, this argument is ignored.
statusCode AlChannel::applyWarp()
Creates a new action and applies it as a time warp to this channel. The new action will be an AlParamAction, and will have two keyframes, one at each of the min and max time of the range of animation of the channel. The time warp will be initially created to have no effect on the channel (that is, y = x, with kEXTRAP_IDENTITY extrapolation types).
AlParamAction* AlChannel::applyWarpO()
Creates a new action and applies it as a time warp to this channel. The new action will be an AlParamAction, and will have two keyframes, one at each of the min and max time of the range of animation of the channel. The time warp will be initially created to have no effect on the channel (that is, y = x, with kEXTRAP_IDENTITY extrapolation types). The newly created action will be returned.
statusCode AlChannel::removeWarp(AlAction* action)
Removes the given ’action’ from the channel as a time warp. For example, if the channel is currently animated by action A, followed by ’action’ as a first time warp, and action T as a second time warp, then after this method has been invoked, the channel will be animated by action A followed by action T. If this channel is currently animated by action, ’action’ as a base action, followed by four time warps in the following order: T1, ’action’, ’action’, "T2."
After this method has been invoked, the channel will be animated by action ’action’ as a base action, and three time warps as follows: T1, ’action’, "T2."
Note that the base action cannot be removed from the channel by using this method. Removing the base action (for example, by deleting the action), will also cause the channel to be deleted.
int AlChannel::numAppliedActions() const
Returns the number of actions that this channel references and uses for its evaluation. The return value will always be >= 1 (except in the case of failure in which the return value is 0), since the channel must be animated by at least one base action. For example, if this channel is animated using base action A, and two time warp actions, T1 and T2, then this method will return 3.
AlAction* AlChannel::appliedAction(const int n) const
Returns the ’n’th action that is applied to this channel. For example, if this channel is animated by action A as a base action, and then three time warps, T, A and T (note the reuse of the same actions), then appliedAction(1) and appliedAction(3) will return action A, and appliedAction(2) and appliedAction(4) will return action T. If ’n’ is less than 1, or greater than the number of actions used by this channel (as returned by AlChannel::numAppliedActions()), then NULL will be returned.
AlTripleComponent AlChannel::appliedActionComponent(const int n ) const
Returns the extract component that the channel applies to the ’n’th action. This method makes sense only if the n’th action of the channel is an AlMotionAction. If the action is an AlParamAction, or the channel does not have a ’n’ action, then kINVALID_COMPONENT is returned. For example, if the channel is animated by the following actions,
AlMotionAction: A, kY_COMPONENT AlParamAction: T1 AlParamAction: T2
then this method will return kY_COMPONENT if ’n’ is 1, kINVALID_COMPONENT if ’n’ is 2 or 3 (since these actions are AlParamActions, and this method doesn’t make sense for those values of ’n’), and kINVALID_COMPONENT if ’n’ is less than 1, or greater than numAppliedActions().
