2 * This program is free software; you can redistribute it and/or
3 * modify it under the terms of the GNU General Public License
4 * as published by the Free Software Foundation; either version 2
5 * of the License, or (at your option) any later version.
7 * This program is distributed in the hope that it will be useful,
8 * but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 * GNU General Public License for more details.
12 * You should have received a copy of the GNU General Public License
13 * along with this program; if not, write to the Free Software Foundation,
14 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * The Original Code is Copyright (C) 2008 Blender Foundation.
17 * All rights reserved.
24 #ifndef __ED_KEYFRAMES_EDIT_H__
25 #define __ED_KEYFRAMES_EDIT_H__
31 #include "ED_anim_api.h" /* for enum eAnimFilter_Flags */
40 /* ************************************************ */
41 /* Common Macros and Defines */
43 /* --------- Tool Flags ------------ */
46 typedef enum eEditKeyframes_Validate {
50 /* Selection status */
52 /* Values (y-val) only */
55 /* For graph editor keyframes (2D tests) */
58 BEZT_OK_REGION_CIRCLE,
59 /* Only for keyframes a certain Dopesheet channel */
60 BEZT_OK_CHANNEL_LASSO,
61 BEZT_OK_CHANNEL_CIRCLE,
62 } eEditKeyframes_Validate;
67 typedef enum eEditKeyframes_Select {
68 /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
69 SELECT_REPLACE = (1 << 0),
70 /* add ok keyframes to selection */
71 SELECT_ADD = (1 << 1),
72 /* remove ok keyframes from selection */
73 SELECT_SUBTRACT = (1 << 2),
74 /* flip ok status of keyframes based on key status */
75 SELECT_INVERT = (1 << 3),
76 } eEditKeyframes_Select;
78 /* "selection map" building modes */
79 typedef enum eEditKeyframes_SelMap {
82 } eEditKeyframes_SelMap;
85 typedef enum eEditKeyframes_Snap {
86 SNAP_KEYS_CURFRAME = 1,
93 } eEditKeyframes_Snap;
96 typedef enum eEditKeyframes_Mirror {
97 MIRROR_KEYS_CURFRAME = 1,
103 } eEditKeyframes_Mirror;
105 /* use with BEZT_OK_REGION_LASSO */
106 typedef struct KeyframeEdit_LassoData {
108 const rctf *rectf_view;
109 const int (*mcords)[2];
111 } KeyframeEdit_LassoData;
113 /* use with BEZT_OK_REGION_CIRCLE */
114 typedef struct KeyframeEdit_CircleData {
116 const rctf *rectf_view;
118 float radius_squared;
119 } KeyframeEdit_CircleData;
121 /* ************************************************ */
122 /* Non-Destuctive Editing API (keyframes_edit.c) */
124 /* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */
126 /* which verts of a keyframe is active (after polling) */
127 typedef enum eKeyframeVertOk {
128 /* 'key' itself is ok */
129 KEYFRAME_OK_KEY = (1 << 0),
130 /* 'handle 1' is ok */
131 KEYFRAME_OK_H1 = (1 << 1),
132 /* 'handle 2' is ok */
133 KEYFRAME_OK_H2 = (1 << 2),
135 KEYFRAME_OK_ALL = (KEYFRAME_OK_KEY | KEYFRAME_OK_H1 | KEYFRAME_OK_H2),
138 /* Flags for use during iteration */
139 typedef enum eKeyframeIterFlags {
140 /* consider handles in addition to key itself */
141 KEYFRAME_ITER_INCL_HANDLES = (1 << 0),
143 /* Perform NLA time remapping (global -> strip) for the "f1" parameter
144 * (e.g. used for selection tools on summary tracks)
146 KED_F1_NLA_UNMAP = (1 << 1),
148 /* Perform NLA time remapping (global -> strip) for the "f2" parameter */
149 KED_F2_NLA_UNMAP = (1 << 2),
151 /* Set this when handles aren't visible by default and you want to perform additional checks to
152 * get the actual visibility state. E.g. in some cases handles are only drawn if either a handle
153 * or their control point is selected. The selection state will have to be checked in the
154 * iterator callbacks then. */
155 KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE = (1 << 3),
156 } eKeyframeIterFlags;
158 /* --- Generic Properties for Keyframe Edit Tools ----- */
160 typedef struct KeyframeEditData {
161 /* generic properties/data access */
162 /** temp list for storing custom list of data to check */
164 /** pointer to current scene - many tools need access to cfra/etc. */
166 /** pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
168 /** storage of times/values as 'decimals' */
170 /** storage of times/values/flags as 'whole' numbers */
173 /* current iteration data */
174 /** F-Curve that is being iterated over */
176 /** index of current keyframe being iterated over */
178 /** y-position of midpoint of the channel (for the dopesheet) */
182 /** current flags for the keyframe we're reached in the iteration process */
183 eKeyframeVertOk curflags;
184 /** settings for iteration process */
185 eKeyframeIterFlags iterflags;
188 /* ------- Function Pointer Typedefs ---------------- */
190 /* callback function that refreshes the F-Curve after use */
191 typedef void (*FcuEditFunc)(struct FCurve *fcu);
192 /* callback function that operates on the given BezTriple */
193 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
195 /* ------- Custom Data Type Defines ------------------ */
197 /* Custom data for remapping one range to another in a fixed way */
198 typedef struct KeyframeEditCD_Remap {
199 float oldMin, oldMax; /* old range */
200 float newMin, newMax; /* new range */
201 } KeyframeEditCD_Remap;
204 typedef enum eKeyPasteOffset {
205 /* paste keys starting at current frame */
206 KEYFRAME_PASTE_OFFSET_CFRA_START,
207 /* paste keys ending at current frame */
208 KEYFRAME_PASTE_OFFSET_CFRA_END,
209 /* paste keys relative to the current frame when copying */
210 KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
211 /* paste keys from original time */
212 KEYFRAME_PASTE_OFFSET_NONE,
215 typedef enum eKeyMergeMode {
216 /* overlay existing with new keys */
217 KEYFRAME_PASTE_MERGE_MIX,
218 /* replace entire fcurve */
219 KEYFRAME_PASTE_MERGE_OVER,
220 /* overwrite keys in pasted range */
221 KEYFRAME_PASTE_MERGE_OVER_RANGE,
222 /* overwrite keys in pasted range (use all keyframe start & end for range) */
223 KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL,
226 /* ---------------- Looping API --------------------- */
228 /* functions for looping over keyframes */
229 /* function for working with F-Curve data only
230 * (i.e. when filters have been chosen to explicitly use this) */
231 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked,
233 KeyframeEditFunc key_ok,
234 KeyframeEditFunc key_cb,
236 /* function for working with any type (i.e. one of the known types) of animation channel
237 * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
239 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked,
240 struct bDopeSheet *ads,
241 struct bAnimListElem *ale,
242 KeyframeEditFunc key_ok,
243 KeyframeEditFunc key_cb,
245 /* same as above, except bAnimListElem wrapper is not needed...
246 * - keytype is eAnim_KeyType
248 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked,
249 struct bDopeSheet *ads,
252 KeyframeEditFunc key_ok,
253 KeyframeEditFunc key_cb,
256 /* Calls callback_fn() for each keyframe in each fcurve in the filtered animation context.
257 * Assumes the callback updates keys. */
258 void ANIM_animdata_keyframe_callback(struct bAnimContext *ac,
259 eAnimFilter_Flags filter,
260 KeyframeEditFunc callback_fn);
262 /* functions for making sure all keyframes are in good order */
263 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
265 /* ----------- BezTriple Callback Getters ---------- */
268 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
271 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
272 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
273 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
274 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
275 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
276 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
277 KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
279 /* -------- BezTriple Callbacks (Selection Map) ---------- */
281 /* Get a callback to populate the selection settings map
282 * requires: ked->custom = char[] of length fcurve->totvert
284 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
286 /* Change the selection status of the keyframe based on the map entry for this vert
287 * requires: ked->custom = char[] of length fcurve->totvert
289 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
291 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
293 /* used to calculate the average location of all relevant BezTriples by summing their locations */
294 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
296 /* used to extract a set of cfra-elems from the keyframes */
297 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
299 /* used to remap times from one range to another
300 * requires: ked->custom = KeyframeEditCD_Remap
302 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
304 /* ------ 1.5-D Region Testing Uitls (Lasso/Circle Select) ------- */
305 /* XXX: These are temporary,
306 * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
308 bool keyframe_region_lasso_test(const KeyframeEdit_LassoData *data_lasso, const float xy[2]);
310 bool keyframe_region_circle_test(const KeyframeEdit_CircleData *data_circle, const float xy[2]);
312 /* ************************************************ */
313 /* Destructive Editing API (keyframes_general.c) */
315 void delete_fcurve_key(struct FCurve *fcu, int index, bool do_recalc);
316 bool delete_fcurve_keys(struct FCurve *fcu);
317 void clear_fcurve_keys(struct FCurve *fcu);
318 void duplicate_fcurve_keys(struct FCurve *fcu);
320 void clean_fcurve(struct bAnimContext *ac,
321 struct bAnimListElem *ale,
324 bool decimate_fcurve(struct bAnimListElem *ale, float remove_ratio, float error_sq_max);
325 void smooth_fcurve(struct FCurve *fcu);
326 void sample_fcurve(struct FCurve *fcu);
330 void ANIM_fcurves_copybuf_free(void);
331 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
332 short paste_animedit_keys(struct bAnimContext *ac,
334 const eKeyPasteOffset offset_mode,
335 const eKeyMergeMode merge_mode,
338 /* ************************************************ */
344 #endif /* __ED_KEYFRAMES_EDIT_H__ */