621a325eabd9ccb90e9bb0cb5f62c8ab0ba0d218
[blender.git] / source / blender / editors / include / ED_keyframes_edit.h
1 /*
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.
6  *
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.
11  *
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.
15  *
16  * The Original Code is Copyright (C) 2008 Blender Foundation.
17  * All rights reserved.
18  */
19
20 /** \file
21  * \ingroup editors
22  */
23
24 #ifndef __ED_KEYFRAMES_EDIT_H__
25 #define __ED_KEYFRAMES_EDIT_H__
26
27 struct BezTriple;
28 struct FCurve;
29 struct Scene;
30 struct bAnimContext;
31 struct bAnimListElem;
32 struct bDopeSheet;
33
34 /* ************************************************ */
35 /* Common Macros and Defines */
36
37 /* --------- Tool Flags ------------ */
38
39 /* bezt validation */
40 typedef enum eEditKeyframes_Validate {
41   /* Frame range */
42   BEZT_OK_FRAME = 1,
43   BEZT_OK_FRAMERANGE,
44   /* Selection status */
45   BEZT_OK_SELECTED,
46   /* Values (y-val) only */
47   BEZT_OK_VALUE,
48   BEZT_OK_VALUERANGE,
49   /* For graph editor keyframes (2D tests) */
50   BEZT_OK_REGION,
51   BEZT_OK_REGION_LASSO,
52   BEZT_OK_REGION_CIRCLE,
53   /* Only for keyframes a certain Dopesheet channel */
54   BEZT_OK_CHANNEL_LASSO,
55   BEZT_OK_CHANNEL_CIRCLE,
56 } eEditKeyframes_Validate;
57
58 /* ------------ */
59
60 /* select modes */
61 typedef enum eEditKeyframes_Select {
62   /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
63   SELECT_REPLACE = (1 << 0),
64   /* add ok keyframes to selection */
65   SELECT_ADD = (1 << 1),
66   /* remove ok keyframes from selection */
67   SELECT_SUBTRACT = (1 << 2),
68   /* flip ok status of keyframes based on key status */
69   SELECT_INVERT = (1 << 3),
70 } eEditKeyframes_Select;
71
72 /* "selection map" building modes */
73 typedef enum eEditKeyframes_SelMap {
74   SELMAP_MORE = 0,
75   SELMAP_LESS,
76 } eEditKeyframes_SelMap;
77
78 /* snapping tools */
79 typedef enum eEditKeyframes_Snap {
80   SNAP_KEYS_CURFRAME = 1,
81   SNAP_KEYS_NEARFRAME,
82   SNAP_KEYS_NEARSEC,
83   SNAP_KEYS_NEARMARKER,
84   SNAP_KEYS_HORIZONTAL,
85   SNAP_KEYS_VALUE,
86   SNAP_KEYS_TIME,
87 } eEditKeyframes_Snap;
88
89 /* mirroring tools */
90 typedef enum eEditKeyframes_Mirror {
91   MIRROR_KEYS_CURFRAME = 1,
92   MIRROR_KEYS_YAXIS,
93   MIRROR_KEYS_XAXIS,
94   MIRROR_KEYS_MARKER,
95   MIRROR_KEYS_VALUE,
96   MIRROR_KEYS_TIME,
97 } eEditKeyframes_Mirror;
98
99 /* use with BEZT_OK_REGION_LASSO */
100 typedef struct KeyframeEdit_LassoData {
101   rctf *rectf_scaled;
102   const rctf *rectf_view;
103   const int (*mcords)[2];
104   int mcords_tot;
105 } KeyframeEdit_LassoData;
106
107 /* use with BEZT_OK_REGION_CIRCLE */
108 typedef struct KeyframeEdit_CircleData {
109   rctf *rectf_scaled;
110   const rctf *rectf_view;
111   float mval[2];
112   float radius_squared;
113 } KeyframeEdit_CircleData;
114
115 /* ************************************************ */
116 /* Non-Destuctive Editing API (keyframes_edit.c) */
117
118 /* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */
119
120 /* which verts of a keyframe is active (after polling) */
121 typedef enum eKeyframeVertOk {
122   /* 'key' itself is ok */
123   KEYFRAME_OK_KEY = (1 << 0),
124   /* 'handle 1' is ok */
125   KEYFRAME_OK_H1 = (1 << 1),
126   /* 'handle 2' is ok */
127   KEYFRAME_OK_H2 = (1 << 2),
128   /* all flags */
129   KEYFRAME_OK_ALL = (KEYFRAME_OK_KEY | KEYFRAME_OK_H1 | KEYFRAME_OK_H2),
130 } eKeyframeVertOk;
131
132 /* Flags for use during iteration */
133 typedef enum eKeyframeIterFlags {
134   /* consider handles in addition to key itself */
135   KEYFRAME_ITER_INCL_HANDLES = (1 << 0),
136
137   /* Perform NLA time remapping (global -> strip) for the "f1" parameter
138    * (e.g. used for selection tools on summary tracks)
139    */
140   KED_F1_NLA_UNMAP = (1 << 1),
141
142   /* Perform NLA time remapping (global -> strip) for the "f2" parameter */
143   KED_F2_NLA_UNMAP = (1 << 2),
144 } eKeyframeIterFlags;
145
146 /* --- Generic Properties for Keyframe Edit Tools ----- */
147
148 typedef struct KeyframeEditData {
149   /* generic properties/data access */
150   /** temp list for storing custom list of data to check */
151   ListBase list;
152   /** pointer to current scene - many tools need access to cfra/etc.  */
153   struct Scene *scene;
154   /** pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
155   void *data;
156   /** storage of times/values as 'decimals' */
157   float f1, f2;
158   /** storage of times/values/flags as 'whole' numbers */
159   int i1, i2;
160
161   /* current iteration data */
162   /** F-Curve that is being iterated over */
163   struct FCurve *fcu;
164   /** index of current keyframe being iterated over */
165   int curIndex;
166   /** y-position of midpoint of the channel (for the dopesheet) */
167   float channel_y;
168
169   /* flags */
170   /** current flags for the keyframe we're reached in the iteration process */
171   eKeyframeVertOk curflags;
172   /** settings for iteration process */
173   eKeyframeIterFlags iterflags;
174 } KeyframeEditData;
175
176 /* ------- Function Pointer Typedefs ---------------- */
177
178 /* callback function that refreshes the F-Curve after use */
179 typedef void (*FcuEditFunc)(struct FCurve *fcu);
180 /* callback function that operates on the given BezTriple */
181 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
182
183 /* ------- Custom Data Type Defines ------------------ */
184
185 /* Custom data for remapping one range to another in a fixed way */
186 typedef struct KeyframeEditCD_Remap {
187   float oldMin, oldMax; /* old range */
188   float newMin, newMax; /* new range */
189 } KeyframeEditCD_Remap;
190
191 /* Paste options */
192 typedef enum eKeyPasteOffset {
193   /* paste keys starting at current frame */
194   KEYFRAME_PASTE_OFFSET_CFRA_START,
195   /* paste keys ending at current frame */
196   KEYFRAME_PASTE_OFFSET_CFRA_END,
197   /* paste keys relative to the current frame when copying */
198   KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
199   /* paste keys from original time */
200   KEYFRAME_PASTE_OFFSET_NONE,
201 } eKeyPasteOffset;
202
203 typedef enum eKeyMergeMode {
204   /* overlay existing with new keys */
205   KEYFRAME_PASTE_MERGE_MIX,
206   /* replace entire fcurve */
207   KEYFRAME_PASTE_MERGE_OVER,
208   /* overwrite keys in pasted range */
209   KEYFRAME_PASTE_MERGE_OVER_RANGE,
210   /* overwrite keys in pasted range (use all keyframe start & end for range) */
211   KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL,
212 } eKeyMergeMode;
213
214 /* ---------------- Looping API --------------------- */
215
216 /* functions for looping over keyframes */
217 /* function for working with F-Curve data only
218  * (i.e. when filters have been chosen to explicitly use this) */
219 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked,
220                                  struct FCurve *fcu,
221                                  KeyframeEditFunc key_ok,
222                                  KeyframeEditFunc key_cb,
223                                  FcuEditFunc fcu_cb);
224 /* function for working with any type (i.e. one of the known types) of animation channel
225  * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
226  */
227 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked,
228                                       struct bDopeSheet *ads,
229                                       struct bAnimListElem *ale,
230                                       KeyframeEditFunc key_ok,
231                                       KeyframeEditFunc key_cb,
232                                       FcuEditFunc fcu_cb);
233 /* same as above, except bAnimListElem wrapper is not needed...
234  * - keytype is eAnim_KeyType
235  */
236 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked,
237                                           struct bDopeSheet *ads,
238                                           void *data,
239                                           int keytype,
240                                           KeyframeEditFunc key_ok,
241                                           KeyframeEditFunc key_cb,
242                                           FcuEditFunc fcu_cb);
243
244 /* functions for making sure all keyframes are in good order */
245 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
246
247 /* ----------- BezTriple Callback Getters ---------- */
248
249 /* accessories */
250 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
251
252 /* edit */
253 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
254 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
255 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
256 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
257 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
258 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
259 KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
260
261 /* -------- BezTriple Callbacks (Selection Map) ---------- */
262
263 /* Get a callback to populate the selection settings map
264  * requires: ked->custom = char[] of length fcurve->totvert
265  */
266 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
267
268 /* Change the selection status of the keyframe based on the map entry for this vert
269  * requires: ked->custom = char[] of length fcurve->totvert
270  */
271 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
272
273 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
274
275 /* used to calculate the average location of all relevant BezTriples by summing their locations */
276 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
277
278 /* used to extract a set of cfra-elems from the keyframes */
279 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
280
281 /* used to remap times from one range to another
282  * requires:  ked->custom = KeyframeEditCD_Remap
283  */
284 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
285
286 /* ------ 1.5-D Region Testing Uitls (Lasso/Circle Select) ------- */
287 /* XXX: These are temporary,
288  * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
289
290 bool keyframe_region_lasso_test(const KeyframeEdit_LassoData *data_lasso, const float xy[2]);
291
292 bool keyframe_region_circle_test(const KeyframeEdit_CircleData *data_circle, const float xy[2]);
293
294 /* ************************************************ */
295 /* Destructive Editing API (keyframes_general.c) */
296
297 void delete_fcurve_key(struct FCurve *fcu, int index, bool do_recalc);
298 bool delete_fcurve_keys(struct FCurve *fcu);
299 void clear_fcurve_keys(struct FCurve *fcu);
300 void duplicate_fcurve_keys(struct FCurve *fcu);
301
302 void clean_fcurve(struct bAnimContext *ac,
303                   struct bAnimListElem *ale,
304                   float thresh,
305                   bool cleardefault);
306 void decimate_fcurve(struct bAnimListElem *ale, float remove_ratio);
307 void smooth_fcurve(struct FCurve *fcu);
308 void sample_fcurve(struct FCurve *fcu);
309
310 /* ----------- */
311
312 void ANIM_fcurves_copybuf_free(void);
313 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
314 short paste_animedit_keys(struct bAnimContext *ac,
315                           ListBase *anim_data,
316                           const eKeyPasteOffset offset_mode,
317                           const eKeyMergeMode merge_mode,
318                           bool flip);
319
320 /* ************************************************ */
321
322 #endif /* __ED_KEYFRAMES_EDIT_H__ */