Camera tracking: support of tripod motion solving
[blender.git] / source / blender / editors / include / ED_keyframing.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  * This is a new part of Blender (with some old code)
20  *
21  * Contributor(s): Joshua Leung
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  */
25
26 /** \file ED_keyframing.h
27  *  \ingroup editors
28  */
29
30 #ifndef __ED_KEYFRAMING_H__
31 #define __ED_KEYFRAMING_H__
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 struct Main;
38 struct ListBase;
39 struct ID;
40 struct Scene;
41
42 struct KeyingSet;
43
44 struct bAction;
45 struct FCurve;
46 struct BezTriple;
47
48 struct bPoseChannel;
49 struct bConstraint;
50
51 struct bContext;
52 struct wmOperatorType;
53 struct ReportList;
54
55 struct PointerRNA;
56 struct PropertyRNA;
57 struct EnumPropertyItem;
58
59 #include "RNA_types.h"
60
61 /* ************ Keyframing Management **************** */
62
63 /* Get the active settings for keyframing settings from context (specifically the given scene) 
64  *      - incl_mode: include settings from keyframing mode in the result (i.e. replace only)
65  */
66 short ANIM_get_keyframing_flags(struct Scene *scene, short incl_mode);
67
68 /* -------- */
69
70 /* Get (or add relevant data to be able to do so) the Active Action for the given 
71  * Animation Data block, given an ID block where the Animation Data should reside.
72  */
73 struct bAction *verify_adt_action(struct ID *id, short add);
74
75 /* Get (or add relevant data to be able to do so) F-Curve from the given Action. 
76  * This assumes that all the destinations are valid.
77  */
78 struct FCurve *verify_fcurve(struct bAction *act, const char group[], const char rna_path[], const int array_index, short add);
79
80 /* -------- */
81
82 /* Lesser Keyframing API call:
83  *      Use this when validation of necessary animation data isn't necessary as it already
84  *      exists, and there is a beztriple that can be directly copied into the array.
85  */
86 int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt, short flag);
87
88 /* Main Keyframing API call: 
89  *      Use this when validation of necessary animation data isn't necessary as it
90  *      already exists. It will insert a keyframe using the current value being keyframed.
91  *      Returns the index at which a keyframe was added (or -1 if failed)
92  */
93 int insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
94
95 /* -------- */
96
97 /* Secondary Keyframing API calls: 
98  *      Use this to insert a keyframe using the current value being keyframed, in the 
99  *      nominated F-Curve (no creation of animation data performed). Returns success.
100  */
101 short insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
102
103 /* -------- */
104
105 /* Main Keyframing API calls: 
106  *      Use this to create any necessary animation data, and then insert a keyframe
107  *      using the current value being keyframed, in the relevant place. Returns success.
108  */
109 short insert_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
110
111 /* Main Keyframing API call: 
112  *      Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
113  */
114 short delete_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
115
116 /* ************ Keying Sets ********************** */
117
118 /* forward decl. for this struct which is declared a bit later... */
119 struct KeyingSetInfo;
120 struct ExtensionRNA;
121
122 /* Polling Callback for KeyingSets */
123 typedef int (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C);
124 /* Context Iterator Callback for KeyingSets */
125 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks);
126 /* Property Specifier Callback for KeyingSets (called from iterators) */
127 typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks, struct PointerRNA *ptr); 
128
129
130 /* Callback info for 'Procedural' KeyingSets to use */
131 typedef struct KeyingSetInfo {
132         struct KeyingSetInfo *next, *prev;
133         
134         /* info */
135                 /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
136         char idname[64];
137                 /* identifier so that user can hook this up to a KeyingSet (used as label). */
138         char name[64];
139                 /* short help/description. */
140         char description[240]; /* RNA_DYN_DESCR_MAX */
141                 /* keying settings */
142         short keyingflag;
143         
144         /* polling callbacks */
145                 /* callback for polling the context for whether the right data is available */
146         cbKeyingSet_Poll poll;
147         
148         /* generate callbacks */
149                 /* iterator to use to go through collections of data in context
150                  *      - this callback is separate from the 'adding' stage, allowing 
151                  *        BuiltIn KeyingSets to be manually specified to use 
152                  */
153         cbKeyingSet_Iterator iter;
154                 /* generator to use to add properties based on the data found by iterator */
155         cbKeyingSet_Generate generate;
156         
157         /* RNA integration */
158         struct ExtensionRNA ext;
159 } KeyingSetInfo;
160
161 /* -------- */
162
163 /* Add another data source for Relative Keying Sets to be evaluated with */
164 void ANIM_relative_keyingset_add_source(ListBase *dsources, struct ID *id, struct StructRNA *srna, void *data);
165
166
167 /* mode for modify_keyframes */
168 typedef enum eModifyKey_Modes {
169         MODIFYKEY_MODE_INSERT = 0,
170         MODIFYKEY_MODE_DELETE,
171 } eModifyKey_Modes;
172
173 /* return codes for errors (with Relative KeyingSets) */
174 typedef enum eModifyKey_Returns {
175                 /* context info was invalid for using the Keying Set */
176         MODIFYKEY_INVALID_CONTEXT = -1,
177                 /* there isn't any typeinfo for generating paths from context */
178         MODIFYKEY_MISSING_TYPEINFO = -2,
179 } eModifyKey_Returns;
180
181 /* poll the current KeyingSet, updating it's set of paths (if "builtin"/"relative") for context changes */
182 short ANIM_validate_keyingset(struct bContext *C, ListBase *dsources, struct KeyingSet *ks);
183
184 /* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
185 int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
186
187 /* -------- */
188
189 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
190 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
191
192 /* Find KeyingSet type info given a name */
193 KeyingSetInfo *ANIM_keyingset_info_find_named(const char name[]);
194
195 /* for RNA type registrations... */
196 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
197 void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi);
198
199 /* cleanup on exit */
200 void ANIM_keyingset_infos_exit(void);
201
202 /* -------- */
203
204 /* Get the active KeyingSet for the given scene */
205 struct KeyingSet *ANIM_scene_get_active_keyingset(struct Scene *scene);
206
207 /* Get the index of the Keying Set provided, for the given Scene */
208 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
209
210 /* Get Keying Set to use for Auto-Keyframing some transforms */
211 struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene, const char *tranformKSName);
212
213 /* Dynamically populate an enum of Keying Sets */
214 struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, int *free);
215
216 /* Check if KeyingSet can be used in the current context */
217 short ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
218
219 /* ************ Drivers ********************** */
220
221 /* Flags for use by driver creation calls */
222 typedef enum eCreateDriverFlags {
223         CREATEDRIVER_WITH_DEFAULT_DVAR  = (1<<0),       /* create drivers with a default variable for nicer UI */
224 } eCreateDriverFlags;
225
226 /* -------- */
227
228 /* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools,
229  * although there are special cases where this approach is preferable.
230  */
231 struct FCurve *verify_driver_fcurve(struct ID *id, const char rna_path[], const int array_index, short add);
232
233 /* -------- */
234
235 /* Returns whether there is a driver in the copy/paste buffer to paste */
236 short ANIM_driver_can_paste(void);
237
238 /* Main Driver Management API calls:
239  *      Add a new driver for the specified property on the given ID block
240  */
241 short ANIM_add_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag, int type);
242
243 /* Main Driver Management API calls:
244  *      Remove the driver for the specified property on the given ID block (if available)
245  */
246 short ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
247
248 /* Main Driver Management API calls:
249  *      Make a copy of the driver for the specified property on the given ID block
250  */
251 short ANIM_copy_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
252
253 /* Main Driver Management API calls:
254  *      Add a new driver for the specified property on the given ID block or replace an existing one
255  *      with the driver + driver-curve data from the buffer 
256  */
257 short ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
258
259 /* ************ Auto-Keyframing ********************** */
260 /* Notes:
261  * - All the defines for this (User-Pref settings and Per-Scene settings)
262  *      are defined in DNA_userdef_types.h
263  * - Scene settings take presidence over those for userprefs, with old files
264  *      inheriting userpref settings for the scene settings
265  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
266  *      as userprefs
267  */
268
269 /* Auto-Keying macros for use by various tools */
270         /* check if auto-keyframing is enabled (per scene takes presidence) */
271 #define IS_AUTOKEY_ON(scene)    ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
272         /* check the mode for auto-keyframing (per scene takes presidence)  */
273 #define IS_AUTOKEY_MODE(scene, mode)    ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
274         /* check if a flag is set for auto-keyframing (per scene takes presidence) */
275 #define IS_AUTOKEY_FLAG(scene, flag) \
276         ((scene)? \
277                 ((scene->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || (U.autokey_flag & AUTOKEY_FLAG_##flag)) \
278          : \
279                 (U.autokey_flag & AUTOKEY_FLAG_##flag))
280
281 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
282 int autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
283
284 /* ************ Keyframe Checking ******************** */
285
286 /* Lesser Keyframe Checking API call:
287  *      - Used for the buttons to check for keyframes...
288  */
289 short fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
290
291 /* Main Keyframe Checking API call:
292  * Checks whether a keyframe exists for the given ID-block one the given frame.
293  *  - It is recommended to call this method over the other keyframe-checkers directly,
294  *        in case some detail of the implementation changes...
295  *      - frame: the value of this is quite often result of BKE_curframe()
296  */
297 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
298
299 /* filter flags for id_cfra_has_keyframe 
300  *
301  * WARNING: do not alter order of these, as also stored in files
302  *      (for v3d->keyflags)
303  */
304 typedef enum eAnimFilterFlags {
305                 /* general */
306         ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
307         ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
308         ANIMFILTER_KEYS_ACTIVE  = (1<<2),               /* only include active-subelements */
309         
310                 /* object specific */
311         ANIMFILTER_KEYS_NOMAT           = (1<<9),               /* don't include material keyframes */
312         ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
313 } eAnimFilterFlags;
314
315 /* utility funcs for auto keyframe */
316 int ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, struct KeyingSet *ks);
317 int ED_autokeyframe_pchan(struct bContext *C, struct Scene *scene, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks);
318
319 /* Names for builtin keying sets so we don't confuse these with labels/text,
320  * defined in python script: keyingsets_builtins.py */
321 #define ANIM_KS_LOCATION_ID         "Location"
322 #define ANIM_KS_ROTATION_ID         "Rotation"
323 #define ANIM_KS_SCALING_ID          "Scaling"
324 #define ANIM_KS_LOC_ROT_SCALE_ID    "LocRotScale"
325 #define ANIM_KS_AVAILABLE_ID        "Available"
326 #define ANIM_KS_WHOLE_CHARACTER_ID  "WholeCharacter"
327
328 #ifdef __cplusplus
329 }
330 #endif
331
332 #endif /*  __ED_KEYFRAMING_H__ */