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