9851988edd444e50a596e4bd603c4f06ce919173
[blender.git] / source / blender / editors / include / ED_keyframing.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  * This is a new part of Blender (with some old code)
18  */
19
20 /** \file
21  * \ingroup editors
22  */
23
24 #ifndef __ED_KEYFRAMING_H__
25 #define __ED_KEYFRAMING_H__
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 struct ID;
32 struct ListBase;
33 struct Main;
34 struct Scene;
35
36 struct KeyingSet;
37
38 struct BezTriple;
39 struct FCurve;
40 struct bAction;
41
42 struct bPoseChannel;
43
44 struct ReportList;
45 struct bContext;
46
47 struct Depsgraph;
48
49 struct EnumPropertyItem;
50 struct PointerRNA;
51 struct PropertyRNA;
52
53 struct NlaKeyframingContext;
54
55 #include "DNA_anim_types.h"
56 #include "RNA_types.h"
57
58 /* ************ Keyframing Management **************** */
59
60 /* Get the active settings for keyframing settings from context (specifically the given scene)
61  * - incl_mode: include settings from keyframing mode in the result (i.e. replace only)
62  */
63 short ANIM_get_keyframing_flags(struct Scene *scene, short incl_mode);
64
65 /* -------- */
66
67 /* Get (or add relevant data to be able to do so) the Active Action for the given
68  * Animation Data block, given an ID block where the Animation Data should reside.
69  */
70 struct bAction *verify_adt_action(struct Main *bmain, struct ID *id, short add);
71
72 /* Get (or add relevant data to be able to do so) F-Curve from the given Action.
73  * This assumes that all the destinations are valid.
74  */
75 struct FCurve *verify_fcurve(struct Main *bmain,
76                              struct bAction *act,
77                              const char group[],
78                              struct PointerRNA *ptr,
79                              const char rna_path[],
80                              const int array_index,
81                              short add);
82
83 /* -------- */
84
85 /* Lesser Keyframing API call:
86  *  Update integer/discrete flags of the FCurve (used when creating/inserting keyframes,
87  *  but also through RNA when editing an ID prop, see T37103).
88  */
89 void update_autoflags_fcurve(struct FCurve *fcu,
90                              struct bContext *C,
91                              struct ReportList *reports,
92                              struct PointerRNA *ptr);
93
94 /* -------- */
95
96 /* Lesser Keyframing API call:
97  *  Use this when validation of necessary animation data isn't necessary as it already
98  *  exists, and there is a beztriple that can be directly copied into the array.
99  */
100 int insert_bezt_fcurve(struct FCurve *fcu, const struct BezTriple *bezt, eInsertKeyFlags flag);
101
102 /* Main Keyframing API call:
103  *  Use this when validation of necessary animation data isn't necessary as it
104  *  already exists. It will insert a keyframe using the current value being keyframed.
105  *  Returns the index at which a keyframe was added (or -1 if failed)
106  */
107 int insert_vert_fcurve(
108     struct FCurve *fcu, float x, float y, eBezTriple_KeyframeType keytype, eInsertKeyFlags flag);
109
110 /* -------- */
111
112 /* Secondary Keyframing API calls:
113  * Use this to insert a keyframe using the current value being keyframed, in the
114  * nominated F-Curve (no creation of animation data performed). Returns success.
115  */
116 bool insert_keyframe_direct(struct ReportList *reports,
117                             struct PointerRNA ptr,
118                             struct PropertyRNA *prop,
119                             struct FCurve *fcu,
120                             float cfra,
121                             eBezTriple_KeyframeType keytype,
122                             struct NlaKeyframingContext *nla,
123                             eInsertKeyFlags flag);
124
125 /* -------- */
126
127 /* Main Keyframing API calls:
128  * Use this to create any necessary animation data, and then insert a keyframe
129  * using the current value being keyframed, in the relevant place. Returns success.
130  */
131 short insert_keyframe(struct Main *bmain,
132                       struct Depsgraph *depsgraph,
133                       struct ReportList *reports,
134                       struct ID *id,
135                       struct bAction *act,
136                       const char group[],
137                       const char rna_path[],
138                       int array_index,
139                       float cfra,
140                       eBezTriple_KeyframeType keytype,
141                       struct ListBase *nla_cache,
142                       eInsertKeyFlags flag);
143
144 /* Main Keyframing API call:
145  * Use this to delete keyframe on current frame for relevant channel.
146  * Will perform checks just in case. */
147 short delete_keyframe(struct Main *bmain,
148                       struct ReportList *reports,
149                       struct ID *id,
150                       struct bAction *act,
151                       const char group[],
152                       const char rna_path[],
153                       int array_index,
154                       float cfra,
155                       eInsertKeyFlags flag);
156
157 /* ************ Keying Sets ********************** */
158
159 /* forward decl. for this struct which is declared a bit later... */
160 struct ExtensionRNA;
161 struct KeyingSetInfo;
162
163 /* Polling Callback for KeyingSets */
164 typedef bool (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C);
165 /* Context Iterator Callback for KeyingSets */
166 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi,
167                                      struct bContext *C,
168                                      struct KeyingSet *ks);
169 /* Property Specifier Callback for KeyingSets (called from iterators) */
170 typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi,
171                                      struct bContext *C,
172                                      struct KeyingSet *ks,
173                                      struct PointerRNA *ptr);
174
175 /* Callback info for 'Procedural' KeyingSets to use */
176 typedef struct KeyingSetInfo {
177   struct KeyingSetInfo *next, *prev;
178
179   /* info */
180   /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
181   char idname[64];
182   /* identifier so that user can hook this up to a KeyingSet (used as label). */
183   char name[64];
184   /* short help/description. */
185   char description[240]; /* RNA_DYN_DESCR_MAX */
186   /* keying settings */
187   short keyingflag;
188
189   /* polling callbacks */
190   /* callback for polling the context for whether the right data is available */
191   cbKeyingSet_Poll poll;
192
193   /* generate callbacks */
194   /* iterator to use to go through collections of data in context
195    * - this callback is separate from the 'adding' stage, allowing
196    *   BuiltIn KeyingSets to be manually specified to use
197    */
198   cbKeyingSet_Iterator iter;
199   /* generator to use to add properties based on the data found by iterator */
200   cbKeyingSet_Generate generate;
201
202   /* RNA integration */
203   struct ExtensionRNA ext;
204 } KeyingSetInfo;
205
206 /* -------- */
207
208 /* Add another data source for Relative Keying Sets to be evaluated with */
209 void ANIM_relative_keyingset_add_source(ListBase *dsources,
210                                         struct ID *id,
211                                         struct StructRNA *srna,
212                                         void *data);
213
214 /* mode for modify_keyframes */
215 typedef enum eModifyKey_Modes {
216   MODIFYKEY_MODE_INSERT = 0,
217   MODIFYKEY_MODE_DELETE,
218 } eModifyKey_Modes;
219
220 /* return codes for errors (with Relative KeyingSets) */
221 typedef enum eModifyKey_Returns {
222   /* context info was invalid for using the Keying Set */
223   MODIFYKEY_INVALID_CONTEXT = -1,
224   /* there isn't any typeinfo for generating paths from context */
225   MODIFYKEY_MISSING_TYPEINFO = -2,
226 } eModifyKey_Returns;
227
228 /* poll the current KeyingSet, updating it's set of paths
229  * (if "builtin"/"relative") for context changes */
230 short ANIM_validate_keyingset(struct bContext *C, ListBase *dsources, struct KeyingSet *ks);
231
232 /* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
233 int ANIM_apply_keyingset(struct bContext *C,
234                          ListBase *dsources,
235                          struct bAction *act,
236                          struct KeyingSet *ks,
237                          short mode,
238                          float cfra);
239
240 /* -------- */
241
242 /* Get the first builtin KeyingSet with the given name, which occurs after the given one
243  * (or start of list if none given) */
244 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
245
246 /* Find KeyingSet type info given a name */
247 KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]);
248
249 /* Find a given ID in the KeyingSet */
250 bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id);
251
252 /* for RNA type registrations... */
253 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
254 void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi);
255
256 /* cleanup on exit */
257 void ANIM_keyingset_infos_exit(void);
258
259 /* -------- */
260
261 /* Get the active KeyingSet for the given scene */
262 struct KeyingSet *ANIM_scene_get_active_keyingset(struct Scene *scene);
263
264 /* Get the index of the Keying Set provided, for the given Scene */
265 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
266
267 /* Get Keying Set to use for Auto-Keyframing some transforms */
268 struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene,
269                                                     const char *tranformKSName);
270
271 /* Dynamically populate an enum of Keying Sets */
272 const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C,
273                                                            struct PointerRNA *ptr,
274                                                            struct PropertyRNA *prop,
275                                                            bool *r_free);
276
277 /* Use to get the keying set from the int value used by enums. */
278 KeyingSet *ANIM_keyingset_get_from_enum_type(struct Scene *scene, int type);
279 KeyingSet *ANIM_keyingset_get_from_idname(struct Scene *scene, const char *idname);
280
281 /* Check if KeyingSet can be used in the current context */
282 bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
283
284 /* ************ Drivers ********************** */
285
286 /* Flags for use by driver creation calls */
287 typedef enum eCreateDriverFlags {
288   /** create drivers with a default variable for nicer UI */
289   CREATEDRIVER_WITH_DEFAULT_DVAR = (1 << 0),
290   /** create drivers with Generator FModifier (for backwards compat) */
291   CREATEDRIVER_WITH_FMODIFIER = (1 << 1),
292 } eCreateDriverFlags;
293
294 /* Heuristic to use for connecting target properties to driven ones */
295 typedef enum eCreateDriver_MappingTypes {
296   /** 1 to Many - Use the specified index, and drive all elements with it */
297   CREATEDRIVER_MAPPING_1_N = 0,
298   /** 1 to 1 - Only for the specified index on each side */
299   CREATEDRIVER_MAPPING_1_1 = 1,
300   /** Many to Many - Match up the indices one by one (only for drivers on vectors/arrays) */
301   CREATEDRIVER_MAPPING_N_N = 2,
302
303   /** None (Single Prop):
304    * Do not create driver with any targets; these will get added later instead */
305   CREATEDRIVER_MAPPING_NONE = 3,
306   /** None (All Properties):
307    * Do not create driver with any targets; these will get added later instead */
308   CREATEDRIVER_MAPPING_NONE_ALL = 4,
309 } eCreateDriver_MappingTypes;
310
311 /* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */
312 extern EnumPropertyItem prop_driver_create_mapping_types[];
313
314 /* -------- */
315
316 /* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools,
317  * although there are special cases where this approach is preferable.
318  */
319 struct FCurve *verify_driver_fcurve(struct ID *id,
320                                     const char rna_path[],
321                                     const int array_index,
322                                     short add);
323
324 /* -------- */
325
326 /* Main Driver Management API calls:
327  *  Add a new driver for the specified property on the given ID block,
328  *  and make it be driven by the specified target.
329  *
330  * This is intended to be used in conjunction with a modal "eyedropper"
331  * for picking the variable that is going to be used to drive this one.
332  *
333  * - flag: eCreateDriverFlags
334  * - driver_type: eDriver_Types
335  * - mapping_type: eCreateDriver_MappingTypes
336  */
337 int ANIM_add_driver_with_target(struct ReportList *reports,
338                                 struct ID *dst_id,
339                                 const char dst_path[],
340                                 int dst_index,
341                                 struct ID *src_id,
342                                 const char src_path[],
343                                 int src_index,
344                                 short flag,
345                                 int driver_type,
346                                 short mapping_type);
347
348 /* -------- */
349
350 /* Main Driver Management API calls:
351  *  Add a new driver for the specified property on the given ID block
352  */
353 int ANIM_add_driver(struct ReportList *reports,
354                     struct ID *id,
355                     const char rna_path[],
356                     int array_index,
357                     short flag,
358                     int type);
359
360 /* Main Driver Management API calls:
361  *  Remove the driver for the specified property on the given ID block (if available)
362  */
363 bool ANIM_remove_driver(
364     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
365
366 /* -------- */
367
368 /* Clear copy-paste buffer for drivers */
369 void ANIM_drivers_copybuf_free(void);
370
371 /* Clear copy-paste buffer for driver variable sets */
372 void ANIM_driver_vars_copybuf_free(void);
373
374 /* -------- */
375
376 /* Returns whether there is a driver in the copy/paste buffer to paste */
377 bool ANIM_driver_can_paste(void);
378
379 /* Main Driver Management API calls:
380  *  Make a copy of the driver for the specified property on the given ID block
381  */
382 bool ANIM_copy_driver(
383     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
384
385 /* Main Driver Management API calls:
386  * Add a new driver for the specified property on the given ID block or replace an existing one
387  * with the driver + driver-curve data from the buffer
388  */
389 bool ANIM_paste_driver(
390     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
391
392 /* -------- */
393
394 /* Checks if there are driver variables in the copy/paste buffer */
395 bool ANIM_driver_vars_can_paste(void);
396
397 /* Copy the given driver's variables to the buffer */
398 bool ANIM_driver_vars_copy(struct ReportList *reports, struct FCurve *fcu);
399
400 /* Paste the variables in the buffer to the given FCurve */
401 bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace);
402
403 /* ************ Auto-Keyframing ********************** */
404 /* Notes:
405  * - All the defines for this (User-Pref settings and Per-Scene settings)
406  *   are defined in DNA_userdef_types.h
407  * - Scene settings take precedence over those for userprefs, with old files
408  *   inheriting userpref settings for the scene settings
409  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
410  *   as userprefs
411  */
412
413 /* Auto-Keying macros for use by various tools */
414 /* check if auto-keyframing is enabled (per scene takes precedence) */
415 #define IS_AUTOKEY_ON(scene) \
416   ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
417 /* check the mode for auto-keyframing (per scene takes precedence)  */
418 #define IS_AUTOKEY_MODE(scene, mode) \
419   ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : \
420              (U.autokey_mode == AUTOKEY_MODE_##mode))
421 /* check if a flag is set for auto-keyframing (per scene takes precedence) */
422 #define IS_AUTOKEY_FLAG(scene, flag) \
423   ((scene) ? ((scene->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || \
424               (U.autokey_flag & AUTOKEY_FLAG_##flag)) : \
425              (U.autokey_flag & AUTOKEY_FLAG_##flag))
426
427 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
428 bool autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
429
430 /* ************ Keyframe Checking ******************** */
431
432 /* Lesser Keyframe Checking API call:
433  * - Used for the buttons to check for keyframes...
434  */
435 bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
436
437 /* Lesser Keyframe Checking API call:
438  * - Returns whether the current value of a given property differs from the interpolated value.
439  * - Used for button drawing.
440  */
441 bool fcurve_is_changed(struct PointerRNA ptr,
442                        struct PropertyRNA *prop,
443                        struct FCurve *fcu,
444                        float frame);
445
446 /**
447  * Main Keyframe Checking API call:
448  * Checks whether a keyframe exists for the given ID-block one the given frame.
449  * - It is recommended to call this method over the other keyframe-checkers directly,
450  *   in case some detail of the implementation changes...
451  * - frame: the value of this is quite often result of #BKE_scene_frame_get()
452  */
453 bool id_frame_has_keyframe(struct ID *id, float frame, short filter);
454
455 /* filter flags for id_cfra_has_keyframe
456  *
457  * WARNING: do not alter order of these, as also stored in files
458  * (for v3d->keyflags)
459  */
460 typedef enum eAnimFilterFlags {
461   /* general */
462   ANIMFILTER_KEYS_LOCAL = (1 << 0),  /* only include locally available anim data */
463   ANIMFILTER_KEYS_MUTED = (1 << 1),  /* include muted elements */
464   ANIMFILTER_KEYS_ACTIVE = (1 << 2), /* only include active-subelements */
465
466   /* object specific */
467   ANIMFILTER_KEYS_NOMAT = (1 << 9),   /* don't include material keyframes */
468   ANIMFILTER_KEYS_NOSKEY = (1 << 10), /* don't include shape keys (for geometry) */
469 } eAnimFilterFlags;
470
471 /* utility funcs for auto keyframe */
472 bool ED_autokeyframe_object(struct bContext *C,
473                             struct Scene *scene,
474                             struct Object *ob,
475                             struct KeyingSet *ks);
476 bool ED_autokeyframe_pchan(struct bContext *C,
477                            struct Scene *scene,
478                            struct Object *ob,
479                            struct bPoseChannel *pchan,
480                            struct KeyingSet *ks);
481
482 /* Names for builtin keying sets so we don't confuse these with labels/text,
483  * defined in python script: keyingsets_builtins.py */
484 #define ANIM_KS_LOCATION_ID "Location"
485 #define ANIM_KS_ROTATION_ID "Rotation"
486 #define ANIM_KS_SCALING_ID "Scaling"
487 #define ANIM_KS_LOC_ROT_SCALE_ID "LocRotScale"
488 #define ANIM_KS_AVAILABLE_ID "Available"
489 #define ANIM_KS_WHOLE_CHARACTER_ID "WholeCharacter"
490 #define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID "WholeCharacterSelected"
491
492 #ifdef __cplusplus
493 }
494 #endif
495
496 #endif /*  __ED_KEYFRAMING_H__ */