AlChannel
 
 
 

Basic interface to Alias channels.

Synopsis

#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;

Description

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.

AlChannel::AlChannel()

Description

Constructs an AlChannel wrapper object. Use the create() method to initialize the AlChannel.

AlChannel::~AlChannel()

Description

Deletes an AlChannel wrapper object.

statusCode AlChannel::deleteObject()

Description

Deletes a channel. The actions that are used by the channel will not be deleted.

Return Codes

sSuccess - the data for the AlChannel was successfully deleted

sInvalidObject - the channel was not valid

AlObject* AlChannel::copyWrapper() const

Description

Makes a copy of the AlChannel. The returned AlChannel will reference the same data as the original.

statusCode AlChannel::create(AlAnimatable *anima, int field,AlAction *faction, AlTripleComponent component)

Description

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.

Arguments

< 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.

Return Codes

sSuccess - channel was successfully created

sInvalidArgument - either ’faction’ was invalid or ’anima’ was NULL

sInvalidObject - channel was not created

sAlreadyCreated - channel is already created

statusCode AlChannel::create(AlAnimatable *anima, int field,const char *szExprText)

Description

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.

Note

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.

Arguments

< 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

Return Codes

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)

AlObjectType AlChannel::type() const

Description

Returns the class identifier ’kChannelType’.

AlObject* AlChannel::animatedItem() const

Description

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.

int AlChannel::parameter() const

Description

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.

const char* AlChannel::parameterName() const

Description

Returns a string that is a lexical name for the parameter/field that this channel animates.

AlChannelDataType AlChannel::channelType() const

Description

Returns the type of channel (kAnimChannel or kExprChannel). kUnknownChannel is returned if there is an error.

AlChannel* AlChannel::copy(AlAnimatable *anima, int field)

Description

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.

Arguments

< 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

statusCode AlChannel::copyD(AlAnimatable *anima, int field)

Description

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.

Arguments

< 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

Return Codes

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

statusCode AlChannel::link(AlAction* action, AlTripleComponent component)

Description

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.

Arguments

< 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.

Return Codes

sSuccess - the link was successfully completed

sInvalidObject - the channel was not valid

sFailure - an error occurred

sInvalidArgument - the action was invalid

statusCode AlChannel::applyWarp()

Description

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).

Return Codes

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

AlParamAction* AlChannel::applyWarpO()

Description

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)

Description

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.

Arguments

< action - the action to be removed from the channel’s list of time warps

Return Codes

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

double AlChannel::eval( double time ) const

Description

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.

Arguments

< time - the time at which to evaluate the channel

int AlChannel::numAppliedActions() const

Description

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

Description

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.

Arguments

< 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

AlTripleComponent AlChannel::appliedActionComponent(const int n ) const

Description

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().

Arguments

< n - which action of the channel the extract component should be determined for

const char* AlChannel::expressionString() const

Description

If this channel is represented by an expression, this method returns a string representing the expression.