unify include guard defines, __$FILENAME__
[blender-staging.git] / source / blender / editors / include / ED_keyframes_edit.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version. 
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2008 Blender Foundation.
19  * All rights reserved.
20  *
21  * 
22  * Contributor(s): Joshua Leung
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file ED_keyframes_edit.h
28  *  \ingroup editors
29  */
30
31 #ifndef __ED_KEYFRAMES_EDIT_H__
32 #define __ED_KEYFRAMES_EDIT_H__
33
34 struct bAnimContext;
35 struct bAnimListElem;
36 struct bDopeSheet;
37 struct FCurve;
38 struct BezTriple;
39 struct Scene;
40
41 /* ************************************************ */
42 /* Common Macros and Defines */
43
44 /* --------- BezTriple Selection ------------- */
45
46 #define BEZ_SEL(bezt)           { (bezt)->f1 |=  SELECT; (bezt)->f2 |=  SELECT; (bezt)->f3 |=  SELECT; }
47 #define BEZ_DESEL(bezt)         { (bezt)->f1 &= ~SELECT; (bezt)->f2 &= ~SELECT; (bezt)->f3 &= ~SELECT; }
48 #define BEZ_INVSEL(bezt)        { (bezt)->f1 ^=  SELECT; (bezt)->f2 ^=  SELECT; (bezt)->f3 ^=  SELECT; }
49
50 /* --------- Tool Flags ------------ */
51
52 /* bezt validation */
53 typedef enum eEditKeyframes_Validate {
54         BEZT_OK_FRAME   = 1,
55         BEZT_OK_FRAMERANGE,
56         BEZT_OK_SELECTED,
57         BEZT_OK_VALUE,
58         BEZT_OK_VALUERANGE,
59         BEZT_OK_REGION
60 } eEditKeyframes_Validate;
61
62 /* ------------ */
63
64 /* select modes */
65 typedef enum eEditKeyframes_Select {
66                 /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
67         SELECT_REPLACE  =       (1<<0),
68                 /* add ok keyframes to selection */
69         SELECT_ADD              =       (1<<1),
70                 /* remove ok keyframes from selection */
71         SELECT_SUBTRACT =       (1<<2),
72                 /* flip ok status of keyframes based on key status */
73         SELECT_INVERT   =       (1<<3)
74 } eEditKeyframes_Select;
75
76 /* "selection map" building modes */
77 typedef enum eEditKeyframes_SelMap {
78         SELMAP_MORE     = 0,
79         SELMAP_LESS
80 } eEditKeyframes_SelMap;
81
82 /* snapping tools */
83 typedef enum eEditKeyframes_Snap {
84         SNAP_KEYS_CURFRAME = 1,
85         SNAP_KEYS_NEARFRAME,
86         SNAP_KEYS_NEARSEC,
87         SNAP_KEYS_NEARMARKER,
88         SNAP_KEYS_HORIZONTAL,
89         SNAP_KEYS_VALUE
90 } eEditKeyframes_Snap;
91
92 /* mirroring tools */
93 typedef enum eEditKeyframes_Mirror {
94         MIRROR_KEYS_CURFRAME = 1,
95         MIRROR_KEYS_YAXIS,
96         MIRROR_KEYS_XAXIS,
97         MIRROR_KEYS_MARKER,
98         MIRROR_KEYS_VALUE
99 } eEditKeyframes_Mirror;
100
101 /* ************************************************ */
102 /* Non-Destuctive Editing API (keyframes_edit.c) */
103
104 /* --- Generic Properties for Keyframe Edit Tools ----- */
105
106 typedef struct KeyframeEditData {
107                 /* generic properties/data access */
108         ListBase list;                          /* temp list for storing custom list of data to check */
109         struct Scene *scene;            /* pointer to current scene - many tools need access to cfra/etc.  */
110         void *data;                                     /* pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
111         float f1, f2;                           /* storage of times/values as 'decimals' */
112         int i1, i2;                                     /* storage of times/values/flags as 'whole' numbers */
113         
114                 /* current iteration data */
115         struct FCurve *fcu;                     /* F-Curve that is being iterated over */
116         int curIndex;                           /* index of current keyframe being iterated over */
117         
118                 /* flags */
119         short curflags;                         /* current flags for the keyframe we're reached in the iteration process */
120         short iterflags;                        /* settings for iteration process */ // XXX: unused...
121 } KeyframeEditData;
122
123 /* ------- Function Pointer Typedefs ---------------- */
124
125         /* callback function that refreshes the F-Curve after use */
126 typedef void (*FcuEditFunc)(struct FCurve *fcu);
127         /* callback function that operates on the given BezTriple */
128 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
129
130 /* ---------- Defines for 'OK' polls ----------------- */
131
132 /* which verts of a keyframe is active (after polling) */
133 typedef enum eKeyframeVertOk {
134                 /* 'key' itself is ok */
135         KEYFRAME_OK_KEY         = (1<<0),
136                 /* 'handle 1' is ok */
137         KEYFRAME_OK_H1          = (1<<1),
138                 /* 'handle 2' is ok */
139         KEYFRAME_OK_H2          = (1<<2),
140                 /* all flags */
141         KEYFRAME_OK_ALL         = (KEYFRAME_OK_KEY|KEYFRAME_OK_H1|KEYFRAME_OK_H2)
142 } eKeyframeVertOk;
143
144 /* Flags for use during iteration */
145 typedef enum eKeyframeIterFlags {
146                 /* consider handles in addition to key itself */
147         KEYFRAME_ITER_INCL_HANDLES      = (1<<0),
148 } eKeyframeIterFlags;   
149
150 /* ------- Custom Data Type Defines ------------------ */
151
152 /* Custom data for remapping one range to another in a fixed way */
153 typedef struct KeyframeEditCD_Remap {
154         float oldMin, oldMax;                   /* old range */
155         float newMin, newMax;                   /* new range */
156 } KeyframeEditCD_Remap;
157
158 /* Paste options */
159 typedef enum eKeyPasteOffset {
160                 /* paste keys starting at current frame */
161         KEYFRAME_PASTE_OFFSET_CFRA_START,
162                 /* paste keys ending at current frame */
163         KEYFRAME_PASTE_OFFSET_CFRA_END,
164                 /* paste keys relative to the current frame when copying */
165         KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
166                 /* paste keys from original time */
167         KEYFRAME_PASTE_OFFSET_NONE
168 } eKeyPasteOffset;
169
170 typedef enum eKeyMergeMode {
171                 /* overlay existing with new keys */
172         KEYFRAME_PASTE_MERGE_MIX,
173                 /* replace entire fcurve */
174         KEYFRAME_PASTE_MERGE_OVER,
175                 /* overwrite keys in pasted range */
176         KEYFRAME_PASTE_MERGE_OVER_RANGE,
177                 /* overwrite keys in pasted range (use all keyframe start & end for range) */
178         KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL
179 } eKeyMergeMode;
180
181 /* ---------------- Looping API --------------------- */
182
183 /* functions for looping over keyframes */
184         /* function for working with F-Curve data only (i.e. when filters have been chosen to explicitly use this) */
185 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
186         /* function for working with any type (i.e. one of the known types) of animation channel 
187          *      - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
188          */
189 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, struct bAnimListElem *ale, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
190         /* same as above, except bAnimListElem wrapper is not needed... 
191          *      - keytype is eAnim_KeyType
192          */
193 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, void *data, int keytype, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
194
195 /* functions for making sure all keyframes are in good order */
196 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
197
198 /* ----------- BezTriple Callback Getters ---------- */
199
200 /* accessories */
201 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
202
203 /* edit */
204 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
205 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
206 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
207 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
208 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
209 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
210
211 /* -------- BezTriple Callbacks (Selection Map) ---------- */
212
213 /* Get a callback to populate the selection settings map  
214  * requires: ked->custom = char[] of length fcurve->totvert 
215  */
216 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
217
218 /* Change the selection status of the keyframe based on the map entry for this vert
219  * requires: ked->custom = char[] of length fcurve->totvert
220  */
221 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
222
223 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
224
225 /* used to calculate the the average location of all relevant BezTriples by summing their locations */
226 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
227
228 /* used to extract a set of cfra-elems from the keyframes */
229 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
230
231 /* used to remap times from one range to another
232  * requires:  ked->custom = KeyframeEditCD_Remap        
233  */
234 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
235
236 /* ************************************************ */
237 /* Destructive Editing API (keyframes_general.c) */
238
239 void delete_fcurve_key(struct FCurve *fcu, int index, short do_recalc);
240 void delete_fcurve_keys(struct FCurve *fcu);
241 void clear_fcurve_keys(struct FCurve *fcu);
242 void duplicate_fcurve_keys(struct FCurve *fcu);
243
244 void clean_fcurve(struct FCurve *fcu, float thresh);
245 void smooth_fcurve(struct FCurve *fcu);
246 void sample_fcurve(struct FCurve *fcu);
247
248 /* ----------- */
249
250 void free_anim_copybuf(void);
251 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
252 short paste_animedit_keys(struct bAnimContext *ac, ListBase *anim_data,
253         const eKeyPasteOffset offset_mode, const eKeyMergeMode merge_mode);
254
255 /* ************************************************ */
256
257 #endif /* __ED_KEYFRAMES_EDIT_H__ */