alias_api.AlChannel

class alias_api.AlChannel

Bases: AlObject

Basic interface to Alias channels

A channel controls how a field of an animatable item should change over time. It contains one or more actions which are evaluated at a given time and combined to produce an overall value of the channel at that 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 (i.e. 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 apply_warp() and remove_warp() methods modify the timewarp actions applied to the base action of the channel. They cannot affect the base action of the channel.

The num_applied_actions() 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 applied_actions() will tell you which actions animate the channel. applied_actions(1) is the base action, and applied_actions(2 to n) are the timewarp actions, where n is num_applied_actions().

animated_item(self: alias_api.AlChannel) → alias_api.AlObject

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

applied_action(self: alias_api.AlChannel, n: SupportsInt) → AlAction

This method 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 timewarps, 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.

Parameters

n (int) – 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 timewarp actions.

Returns

The ‘n’th action of the channel.

Return type

AlAction

applied_action_component(self: alias_api.AlChannel, n: SupportsInt) → alias_api.AlTripleComponent

This method returns the extract component that the channel applies to the ‘n’th action. This method only makes sense 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().

Parameters

n (int) – which action of the channel the extract component should be determined for.

Returns

The extract component of the ‘n’th action of the channel.

Return type

AlTripleComponent

apply_warp(self: alias_api.AlChannel) → int

This method creates a new action and applies it as a timewarp 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 timewarp will be initially created to have no effect on the channel (i.e. y = x, with kEXTRAP_IDENTITY extrapolation types).

Returns

The status code result of the operation Success - the application of the warp was successful. InvalidObject - the channel was not valid Failure - applying the warp failed. InsufficientMemory - the new warp was not created.

Return type

AlStatusCode

apply_warp_o(self: alias_api.AlChannel) → AlParamAction

This method creates a new action and applies it as a timewarp 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 timewarp will be initially created to have no effect on the channel (i.e. y = x, with kEXTRAP_IDENTITY extrapolation types). The newly created action will be returned.

channel_type(self: alias_api.AlChannel) → alias_api.AlChannelDataType

This method returns a the type of channel (kAnimChannel or kExprChannel). kUnknownChannel is returned if there is an error.

copy(self: alias_api.AlChannel, anima: alias_api.AlAnimatable, field: SupportsInt) → alias_api.AlChannel

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

Parameters

• anima (AlAnimatable) – the item to receive the new copy of the channel

• field (int) – the field of the dag node that will be animated by the new copy of the channel

Returns

The copied channel

Return type

AlChannel

copy_wrapper(self: alias_api.AlChannel) → alias_api.AlObject

This method makes a copy of the AlChannel. The returned AlChannel will reference the same data as the original.

Returns

The copied AlChannel

Return type

AlObject

create(*args, **kwargs)

Overloaded function.

1. create(self: alias_api.AlChannel, arg0: alias_api.AlAnimatable, arg1: typing.SupportsInt, arg2: AlAction, arg3: alias_api.AlTripleComponent) -> int

   This method creates a new channel that will animate the given field of the given object. The channel will be animated using the given action as a base action. If the field of the object is already animated (i.e. 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.

   param anima

   object that will be animated

   type anima

   AlAnimatable

   param field

   Field of animtable object to animate

   type field

   int

   param action

   Base action which the channel should use

   type action

   AlAction

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

   type component

   AlTripleComponent

   return

   The status code result of the operation Success - channel was successfully created InvalidArgument - either ‘dag_node’ or ‘action’ was NULL. InvalidObject - channel was not created AlreadyCreated - channel is already created

   rtype

   AlStatusCode

2. create(self: alias_api.AlChannel, anima: alias_api.AlAnimatable, field: typing.SupportsInt, sz_expr_text: str) -> int

   This method 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 (i.e. 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.

   param anima

   object that will be animated

   type anima

   AlAnimatable

   param field

   field of dag node to attach the expression

   type field

   AlAction

   parm sz_expr_text

   expression to be attached to the field

   type sz_expr_text

   AlTripleComponent

   return

   The status code result of the operation: Success - channel was successfully created sInvalidArgument - either ‘szExprText’ or ‘anima’ was NULL. InvalidObject - channel was not created AlreadyCreated - channel is already created Expr{Errors} - errors from parsing the expression (see statusCodes.h)

   rype

   AlStatusCode

delete_object(self: alias_api.AlChannel) → int

This method deletes a channel. The actions that are used by the channel will not be deleted.

Returns

The status code result of the operation Success - the data for the AlChannel was successfully deleted InvalidObject - the channel was not valid

Return type

AlStatusCode

eval(self: alias_api.AlChannel, time: SupportsFloat) → float

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

Parameters

time (float) – the time at which to evaluate the channel

expression_string(self: alias_api.AlChannel) → str

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

link(self: alias_api.AlChannel, action: AlAction, component: alias_api.AlTripleComponent) → int

This method 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 timewarp 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 timewarp actions T1 and T2.

Parameters

• action (AlAction) – the action with which the channel should replace its current base action

• component (AlTripleComponent) – 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.

Returns

The status code result of the operation Success - the link was successfully completed. InvalidObject - the channel was not valid Failure - an error occurred InvalidArgument - the action was invalid

Return type

AlStatusCode

num_applied_actions(self: alias_api.AlChannel) → int

This method 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 timewarp actions, T1 and T2, then this method will return 3.

parameter(self: alias_api.AlChannel) → int

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

parameter_name(self: alias_api.AlChannel) → str

This method returns a string that is a lexical name for the parameter/field which this channel animates.

remove_warp(self: alias_api.AlChannel, action: AlAction) → int

This method removes the given ‘action’ from the channel as a timewarp. For example, if the channel is currently animated by action A, followed by ‘action’ as a first timewarp, and action T as a second timewarp, 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 timewarps 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 timewarps 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. :param action: the action to be removed from the channel’s list of timewarps. :type action: AlAction

Returns

The status code result of the operation: Success - the ‘action’ was successfully removed from the channel’s timewarp actions. InvalidArgument - ‘action’ was invalid InvalidObject - the channel was not valid Failure - the ‘action’ was not being used as a timewarp by this channel

Return type

AlStatusCode

sample(self: alias_api.AlChannel) → float

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

type(self: alias_api.AlChannel) → alias_api.AlObjectType

Returns the class identifier ‘ChannelType’.