doxygen: add newline after \file
[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 /* ************************************************ */
117 /* Non-Destuctive Editing API (keyframes_edit.c) */
118
119 /* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */
120
121 /* which verts of a keyframe is active (after polling) */
122 typedef enum eKeyframeVertOk {
123         /* 'key' itself is ok */
124         KEYFRAME_OK_KEY     = (1 << 0),
125         /* 'handle 1' is ok */
126         KEYFRAME_OK_H1      = (1 << 1),
127         /* 'handle 2' is ok */
128         KEYFRAME_OK_H2      = (1 << 2),
129         /* all flags */
130         KEYFRAME_OK_ALL     = (KEYFRAME_OK_KEY | KEYFRAME_OK_H1 | KEYFRAME_OK_H2),
131 } eKeyframeVertOk;
132
133 /* Flags for use during iteration */
134 typedef enum eKeyframeIterFlags {
135         /* consider handles in addition to key itself */
136         KEYFRAME_ITER_INCL_HANDLES  = (1 << 0),
137
138         /* Perform NLA time remapping (global -> strip) for the "f1" parameter
139          * (e.g. used for selection tools on summary tracks)
140          */
141         KED_F1_NLA_UNMAP            = (1 << 1),
142
143         /* Perform NLA time remapping (global -> strip) for the "f2" parameter */
144         KED_F2_NLA_UNMAP            = (1 << 2),
145 } eKeyframeIterFlags;
146
147 /* --- Generic Properties for Keyframe Edit Tools ----- */
148
149 typedef struct KeyframeEditData {
150         /* generic properties/data access */
151         /** temp list for storing custom list of data to check */
152         ListBase list;
153         /** pointer to current scene - many tools need access to cfra/etc.  */
154         struct Scene *scene;
155         /** pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
156         void *data;
157         /** storage of times/values as 'decimals' */
158         float f1, f2;
159         /** storage of times/values/flags as 'whole' numbers */
160         int i1, i2;
161
162         /* current iteration data */
163         /** F-Curve that is being iterated over */
164         struct FCurve *fcu;
165         /** index of current keyframe being iterated over */
166         int curIndex;
167         /** y-position of midpoint of the channel (for the dopesheet) */
168         float channel_y;
169
170         /* flags */
171         /** current flags for the keyframe we're reached in the iteration process */
172         eKeyframeVertOk curflags;
173         /** settings for iteration process */
174         eKeyframeIterFlags iterflags;
175 } KeyframeEditData;
176
177 /* ------- Function Pointer Typedefs ---------------- */
178
179 /* callback function that refreshes the F-Curve after use */
180 typedef void (*FcuEditFunc)(struct FCurve *fcu);
181 /* callback function that operates on the given BezTriple */
182 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
183
184
185 /* ------- Custom Data Type Defines ------------------ */
186
187 /* Custom data for remapping one range to another in a fixed way */
188 typedef struct KeyframeEditCD_Remap {
189         float oldMin, oldMax;           /* old range */
190         float newMin, newMax;           /* new range */
191 } KeyframeEditCD_Remap;
192
193 /* Paste options */
194 typedef enum eKeyPasteOffset {
195         /* paste keys starting at current frame */
196         KEYFRAME_PASTE_OFFSET_CFRA_START,
197         /* paste keys ending at current frame */
198         KEYFRAME_PASTE_OFFSET_CFRA_END,
199         /* paste keys relative to the current frame when copying */
200         KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
201         /* paste keys from original time */
202         KEYFRAME_PASTE_OFFSET_NONE
203 } eKeyPasteOffset;
204
205 typedef enum eKeyMergeMode {
206         /* overlay existing with new keys */
207         KEYFRAME_PASTE_MERGE_MIX,
208         /* replace entire fcurve */
209         KEYFRAME_PASTE_MERGE_OVER,
210         /* overwrite keys in pasted range */
211         KEYFRAME_PASTE_MERGE_OVER_RANGE,
212         /* overwrite keys in pasted range (use all keyframe start & end for range) */
213         KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL
214 } eKeyMergeMode;
215
216 /* ---------------- Looping API --------------------- */
217
218 /* functions for looping over keyframes */
219 /* function for working with F-Curve data only
220  * (i.e. when filters have been chosen to explicitly use this) */
221 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
222 /* function for working with any type (i.e. one of the known types) of animation channel
223  * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
224  */
225 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, struct bAnimListElem *ale, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
226 /* same as above, except bAnimListElem wrapper is not needed...
227  * - keytype is eAnim_KeyType
228  */
229 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, void *data, int keytype, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
230
231 /* functions for making sure all keyframes are in good order */
232 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
233
234 /* ----------- BezTriple Callback Getters ---------- */
235
236 /* accessories */
237 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
238
239 /* edit */
240 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
241 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
242 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
243 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
244 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
245 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
246 KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
247
248 /* -------- BezTriple Callbacks (Selection Map) ---------- */
249
250 /* Get a callback to populate the selection settings map
251  * requires: ked->custom = char[] of length fcurve->totvert
252  */
253 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
254
255 /* Change the selection status of the keyframe based on the map entry for this vert
256  * requires: ked->custom = char[] of length fcurve->totvert
257  */
258 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
259
260 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
261
262 /* used to calculate the average location of all relevant BezTriples by summing their locations */
263 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
264
265 /* used to extract a set of cfra-elems from the keyframes */
266 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
267
268 /* used to remap times from one range to another
269  * requires:  ked->custom = KeyframeEditCD_Remap
270  */
271 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
272
273 /* ------ 1.5-D Region Testing Uitls (Lasso/Circle Select) ------- */
274 /* XXX: These are temporary,
275  * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
276
277 bool keyframe_region_lasso_test(
278         const KeyframeEdit_LassoData *data_lasso,
279         const float xy[2]);
280
281 bool keyframe_region_circle_test(
282         const KeyframeEdit_CircleData *data_circle,
283         const float xy[2]);
284
285
286 /* ************************************************ */
287 /* Destructive Editing API (keyframes_general.c) */
288
289 void delete_fcurve_key(struct FCurve *fcu, int index, bool do_recalc);
290 bool delete_fcurve_keys(struct FCurve *fcu);
291 void clear_fcurve_keys(struct FCurve *fcu);
292 void duplicate_fcurve_keys(struct FCurve *fcu);
293
294 void clean_fcurve(struct bAnimContext *ac, struct bAnimListElem *ale, float thresh, bool cleardefault);
295 void smooth_fcurve(struct FCurve *fcu);
296 void sample_fcurve(struct FCurve *fcu);
297
298 /* ----------- */
299
300 void ANIM_fcurves_copybuf_free(void);
301 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
302 short paste_animedit_keys(struct bAnimContext *ac, ListBase *anim_data,
303                           const eKeyPasteOffset offset_mode, const eKeyMergeMode merge_mode, bool flip);
304
305 /* ************************************************ */
306
307 #endif /* __ED_KEYFRAMES_EDIT_H__ */