formZ SDK | 5.0 API Reference | Project | Modeling | Animation

# fz_anim_cntl_bezier_key_insert

Description

This general purpose insertion function inserts a given keyframe (a value at a time) on to a given animation node. The animation node may be an entity, track, or controller node.
The trac_id is necessary only in certain situations, and identifies a child track of the given animation node anim_node. The child track node does not have to exist. Some track types are defined already (for example, FZ_TRAC_TYPE_POS_X).
If the animation node anim_node is an entity, the trac_id parameter specifies which track of the entity that the keyframe is inserted on. If the track node and controller node do not already exist, they will be automatically created and the keyframe inserted on the controller node. If the track node exists, the keyframe will be inserted on its first found Bezier controller. If it does not have a Bezier controller, a new one will be created on which the keyframe will be inserted. The track type must be supported by the entity.
If the animation node anim_node is a track, the trac_id parameter is optional. If NULL, the keyframe is inserted on this track's first found Bezier controller. If it does not have a Bezier controller, a new one will be created on which the keyframe will be inserted. If trac_id is not NULL, the trac_id specifies which track of the track node that the keyframe is inserted on (certain tracks themselves support tracks, e.g. path tracks support bank tracks). If you intend to add a keyframe to the given animation node track anim_node, then pass NULL for the trac_id.
If the animation node anim_node is a Bezier controller, the trac_id parameter is optional. If NULL, the keyframe is inserted into this controller's list of keyframes. If trac_id is not NULL, the trac_id specifies which track of the controller node that the keyframe is inserted on (certain controllers themselves support tracks). If you intend to add a keyframe to the given animation node controller anim_node, then pass NULL for the trac_id.
The insert_type that would generally be used is FZ_BEZIER_INSERT_METHOD_OFF_CURVE. This inserts a keyframe on to a controller at any new value.
If the insert_type is FZ_BEZIER_INSERT_METHOD_ON_CURVE, then only the time (x) value of the key needs to be provided, and the value (y) will be automatically determined. This implies that there already exists at least two keyframes and the newly inserted keyframe is between them. The lead parameters will be ignored and will be automatically determined so as to maintain the same curve.
If the insert type is FZ_BEZIER_INSERT_METHOD_AUTO, then the lead parameters may or may not be used. If it is determined from the given key value that the new point is on the existing curve, then the behavior of the function is as it is in the FZ_BEZIER_INSERT_METHOD_ON_CURVE case (so leads will be ignored). If it is determined that FZ_BEZIER_INSERT_METHOD_OFF_CURVE is used, then the leads will be used. If they are not provided, they will be automatically set according to the auto keyframe options.
If the use_tol option is TRUE, the inserted key replaces any existing key within the FZ_ANIM_TIME_TOL tolerance. Otherwise the key is inserted no matter what, though this may cause unexpected discontinuities in the animation.
If the key_type parameter is FZ_BEZIER_KEY_TYPE_TANG, then the lead parameters will be made to be tangent. If the leads are not provided, they will be computed automatically.
If the key_type parameter is FZ_BEZIER_KEY_TYPE_TANG_EQUAL, then the lead parameters will be made to be tangent, and equidistant. Only one lead needs to be specified. If the leads are not provided, they will be computed automatically.
If the key_type parameter is FZ_BEZIER_KEY_TYPE_NO_TANG, then the lead parameters will be taken as they are without tangency adjustment. This option should be used for leads that are stepped or linear (otherwise leads are ignored). Curved leads can also use this option. If the leads are not provided, they will be computed automatically.
If a lead type is FZ_BEZIER_LEAD_TYPE_LINEAR, then its corresponding time and value parameter will be ignored, and can be NULL.
If a lead type is FZ_BEZIER_LEAD_TYPE_STEP, then its corresponding time (x) is used, but the value (y) field will be ignored. The value for a lead's step point is the same as its connected key's value.
Inserting some control points may have an effect on neighboring control points. The last insertion has precedence over what occurs. If you insert a key control point with equal tangents at time 6 seconds, and then insert a control point at time 5 seconds with a lead out type FZ_BEZIER_LEAD_TYPE_STEP, the neighboring key that was inserted earlier will have its lead in changed to have a FZ_BEZIER_LEAD_TYPE_STEP type also.
To get a complete list of track types supported by the animation node anim_node, see the fz_anim_node_get_trac_list function.
Other ways of setting keyframes include: fz_anim_node_add_trac, fz_anim_node_add_tracs, .

Plugin Prototype

fzrt_error_td fz_anim_cntl_bezier_key_insert(

fzrt_int | windex,
fz_anim_node_ptr | anim_node,
fzrt_UUID_td | trac_id,
fz_bezier_insert_method_enum | insert_type,
fzrt_boolean | use_tol,
fz_xy_td * | key,
fz_bezier_key_type_enum | key_type,
fz_xy_td * | lead_in,
fz_bezier_lead_type_enum * | lead_in_type,
fz_xy_td * | lead_out,
fz_bezier_lead_type_enum * | lead_out_type,
fzrt_int * | inserted_indx,
fz_anim_node_ptr * | cntl_node )

Parameters

windex [Input]

project window index

anim_node [Input]

animation node (entity, track, or bezier controller node)

trac_id [Input, Optional]

if anim_node is an entity (not a track or controller), this parameter specifies the track type of the track for which to insert the keyframe.

insert_type [Input]

type of insertion

use_tol [Input]

whether or not to use the time tolerance. If TRUE, keys within the time tolerance are replaced, If FALSE, keys within the time tolerance are still inserted

key [Input]

time (x) and value (y) to insert keyframe

key_type [Input]

Key control point type of newly inserted key. The first and last keyframes are usually not tangency locked.

lead_in [Input, Optional]

time (x) and value (y) of lead in. The first keyframe does not have a lead in control point.

lead_in_type [Input, Optional]

Lead In control point type of newly inserted key. The first keyframe does not have a lead in control point.

lead_out [Input, Optional]

time (x) and value (y) of lead out. The last keyframe does not have a lead out control point.

lead_out_type [Input, Optional]

Lead Out control point type of newly inserted key. The last keyframe does not have a lead out control point.

inserted_indx [Result, Optional]

index of inserted key.

cntl_node [Result, Optional]

controller node of inserted key.

Returns

Error codes

Availability

6.1.0.0

Example Files

util_anim_animate_enty.fsl
util_anim_change_grup.fsl
util_anim_cntl.fsl
util_anim_cntl_bezier.fsl
util_anim_dfrm.fsl
util_anim_eval_value.fsl
util_anim_grup_tree.fsl
util_anim_input_values.fsl
util_anim_part.fsl
util_anim_test_color.fsl

Function Set

fz_anim_fset

Defined in

fz_anim_api.h