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