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