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.
Constructs an AlChannel wrapper object. Use the create() method to initialize the AlChannel.
Deletes an AlChannel wrapper object.
Deletes a channel. The actions that are used by the channel will not be deleted.
sSuccess - the data for the AlChannel was successfully deleted
sInvalidObject - the channel was not valid
Makes a copy of the AlChannel. The returned AlChannel will reference the same data as the original.
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.
sSuccess - channel was successfully created
sInvalidArgument - either ’faction’ was invalid or ’anima’ was NULL
sInvalidObject - channel was not created
sAlreadyCreated - channel is already created
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.
< anima - the object that will be animated
< field - which field of DAG node to attach the expression to
< szExprText - expression to be attached to the field
sSuccess - channel was successfully created
sInvalidArgument - either ’szExprText’ or ’anima’ was NULL
sInvalidObject - channel was not created
sAlreadyCreated - channel is already created
sExpr{Errors} - errors from parsing the expression (see statusCodes.h)
Returns the class identifier ’kChannelType’.
Returns the item that is being animated by this AlChannel. The item can be any of the possible animatable items, namely: AlDagNode, AlCurveCV, AlSurfaceCV, AlCamera, AlLight, AlShader, AlTexture or AlEnvironment.
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.
Returns a string that is a lexical name for the parameter/field that this channel animates.
Returns the type of channel (kAnimChannel or kExprChannel). kUnknownChannel is returned if there is an error.
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.
< anima - the item to receive the new copy of the channel
< field - the field of the DAG node that will be animated by the new copy of the channel
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.
< anima - the item to receive the new copy of the channel
< field - the field of the DAG node that will be animated by the new copy of the channel
sSuccess - the channel was successfully copied
sInvalidArgument - ’anima’ was NULL
sInvalidObject - the channel was not valid or the copy failed
sFailure - could not copy the channel
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.
sSuccess - the link was successfully completed
sInvalidObject - the channel was not valid
sFailure - an error occurred
sInvalidArgument - the action was invalid
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).
sSuccess - the application of the warp was successful
sInvalidObject - the channel was not valid
sFailure - applying the warp failed
sInsufficientMemory - the new warp was not created
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.
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.
< action - the action to be removed from the channel’s list of time warps
sSuccess - the ’action’ was successfully removed from the channel’s time warp actions
sInvalidArgument - ’action’ was invalid
sInvalidObject - the channel was not valid
sFailure - the ’action’ was not being used as a time warp by this channel
Evaluates this channel at the given time, and returns the value of the channel at that time. If the call can not be completed, 0.0 is returned.
< time - the time at which to evaluate the channel
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.
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.
< n - which action of the channel to return, where 1 refers to the base action of the channel, and 2 to numAppliedActions() refers to the channel’s time warp actions
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().
< n - which action of the channel the extract component should be determined for
If this channel is represented by an expression, this method returns a string representing the expression.