Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / editors / animation / keyingsets.c
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) 2009 Blender Foundation, Joshua Leung
17  * All rights reserved.
18  */
19
20 /** \file \ingroup edanimation
21  */
22
23
24 #include <stdio.h>
25 #include <stddef.h>
26 #include <string.h>
27 #include <math.h>
28 #include <float.h>
29
30 #include "MEM_guardedalloc.h"
31
32 #include "BLI_blenlib.h"
33 #include "BLI_utildefines.h"
34
35 #include "DNA_anim_types.h"
36 #include "DNA_scene_types.h"
37 #include "DNA_object_types.h"
38
39 #include "BKE_main.h"
40 #include "BKE_animsys.h"
41 #include "BKE_context.h"
42 #include "BKE_report.h"
43
44 #include "DEG_depsgraph.h"
45
46 #include "ED_keyframing.h"
47 #include "ED_screen.h"
48
49 #include "UI_interface.h"
50 #include "UI_resources.h"
51
52 #include "WM_api.h"
53 #include "WM_types.h"
54
55 #include "RNA_access.h"
56 #include "RNA_define.h"
57 #include "RNA_enum_types.h"
58
59 #include "anim_intern.h"
60
61 /* ************************************************** */
62 /* KEYING SETS - OPERATORS (for use in UI panels) */
63 /* These operators are really duplication of existing functionality, but just for completeness,
64  * they're here too, and will give the basic data needed...
65  */
66
67 /* poll callback for adding default KeyingSet */
68 static bool keyingset_poll_default_add(bContext *C)
69 {
70         /* as long as there's an active Scene, it's fine */
71         return (CTX_data_scene(C) != NULL);
72 }
73
74 /* poll callback for editing active KeyingSet */
75 static bool keyingset_poll_active_edit(bContext *C)
76 {
77         Scene *scene = CTX_data_scene(C);
78
79         if (scene == NULL)
80                 return 0;
81
82         /* there must be an active KeyingSet (and KeyingSets) */
83         return ((scene->active_keyingset > 0) && (scene->keyingsets.first));
84 }
85
86 /* poll callback for editing active KeyingSet Path */
87 static bool keyingset_poll_activePath_edit(bContext *C)
88 {
89         Scene *scene = CTX_data_scene(C);
90         KeyingSet *ks;
91
92         if (scene == NULL)
93                 return 0;
94         if (scene->active_keyingset <= 0)
95                 return 0;
96         else
97                 ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
98
99         /* there must be an active KeyingSet and an active path */
100         return ((ks) && (ks->paths.first) && (ks->active_path > 0));
101 }
102
103
104 /* Add a Default (Empty) Keying Set ------------------------- */
105
106 static int add_default_keyingset_exec(bContext *C, wmOperator *UNUSED(op))
107 {
108         Scene *scene = CTX_data_scene(C);
109         short flag = 0, keyingflag = 0;
110
111         /* validate flags
112          * - absolute KeyingSets should be created by default
113          */
114         flag |= KEYINGSET_ABSOLUTE;
115
116         /* 2nd arg is 0 to indicate that we don't want to include autokeying mode related settings */
117         keyingflag = ANIM_get_keyframing_flags(scene, 0);
118
119         /* call the API func, and set the active keyingset index */
120         BKE_keyingset_add(&scene->keyingsets, NULL, NULL, flag, keyingflag);
121
122         scene->active_keyingset = BLI_listbase_count(&scene->keyingsets);
123
124         /* send notifiers */
125         WM_event_add_notifier(C, NC_SCENE | ND_KEYINGSET, NULL);
126
127         return OPERATOR_FINISHED;
128 }
129
130 void ANIM_OT_keying_set_add(wmOperatorType *ot)
131 {
132         /* identifiers */
133         ot->name = "Add Empty Keying Set";
134         ot->idname = "ANIM_OT_keying_set_add";
135         ot->description = "Add a new (empty) Keying Set to the active Scene";
136
137         /* callbacks */
138         ot->exec = add_default_keyingset_exec;
139         ot->poll = keyingset_poll_default_add;
140 }
141
142 /* Remove 'Active' Keying Set ------------------------- */
143
144 static int remove_active_keyingset_exec(bContext *C, wmOperator *op)
145 {
146         Scene *scene = CTX_data_scene(C);
147         KeyingSet *ks;
148
149         /* verify the Keying Set to use:
150          * - use the active one
151          * - return error if it doesn't exist
152          */
153         if (scene->active_keyingset == 0) {
154                 BKE_report(op->reports, RPT_ERROR, "No active keying set to remove");
155                 return OPERATOR_CANCELLED;
156         }
157         else if (scene->active_keyingset < 0) {
158                 BKE_report(op->reports, RPT_ERROR, "Cannot remove built in keying set");
159                 return OPERATOR_CANCELLED;
160         }
161         else
162                 ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
163
164         /* free KeyingSet's data, then remove it from the scene */
165         BKE_keyingset_free(ks);
166         BLI_freelinkN(&scene->keyingsets, ks);
167
168         /* the active one should now be the previously second-to-last one */
169         scene->active_keyingset--;
170
171         /* send notifiers */
172         WM_event_add_notifier(C, NC_SCENE | ND_KEYINGSET, NULL);
173
174         return OPERATOR_FINISHED;
175 }
176
177 void ANIM_OT_keying_set_remove(wmOperatorType *ot)
178 {
179         /* identifiers */
180         ot->name = "Remove Active Keying Set";
181         ot->idname = "ANIM_OT_keying_set_remove";
182         ot->description = "Remove the active Keying Set";
183
184         /* callbacks */
185         ot->exec = remove_active_keyingset_exec;
186         ot->poll = keyingset_poll_active_edit;
187 }
188
189 /* Add Empty Keying Set Path ------------------------- */
190
191 static int add_empty_ks_path_exec(bContext *C, wmOperator *op)
192 {
193         Scene *scene = CTX_data_scene(C);
194         KeyingSet *ks;
195         KS_Path *ksp;
196
197         /* verify the Keying Set to use:
198          * - use the active one
199          * - return error if it doesn't exist
200          */
201         if (scene->active_keyingset == 0) {
202                 BKE_report(op->reports, RPT_ERROR, "No active keying set to add empty path to");
203                 return OPERATOR_CANCELLED;
204         }
205         else
206                 ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
207
208         /* don't use the API method for this, since that checks on values... */
209         ksp = MEM_callocN(sizeof(KS_Path), "KeyingSetPath Empty");
210         BLI_addtail(&ks->paths, ksp);
211         ks->active_path = BLI_listbase_count(&ks->paths);
212
213         ksp->groupmode = KSP_GROUP_KSNAME; // XXX?
214         ksp->idtype = ID_OB;
215         ksp->flag = KSP_FLAG_WHOLE_ARRAY;
216
217         return OPERATOR_FINISHED;
218 }
219
220 void ANIM_OT_keying_set_path_add(wmOperatorType *ot)
221 {
222         /* identifiers */
223         ot->name = "Add Empty Keying Set Path";
224         ot->idname = "ANIM_OT_keying_set_path_add";
225         ot->description = "Add empty path to active Keying Set";
226
227         /* callbacks */
228         ot->exec = add_empty_ks_path_exec;
229         ot->poll = keyingset_poll_active_edit;
230 }
231
232 /* Remove Active Keying Set Path ------------------------- */
233
234 static int remove_active_ks_path_exec(bContext *C, wmOperator *op)
235 {
236         Scene *scene = CTX_data_scene(C);
237         KeyingSet *ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
238
239         /* if there is a KeyingSet, find the nominated path to remove */
240         if (ks) {
241                 KS_Path *ksp = BLI_findlink(&ks->paths, ks->active_path - 1);
242
243                 if (ksp) {
244                         /* remove the active path from the KeyingSet */
245                         BKE_keyingset_free_path(ks, ksp);
246
247                         /* the active path should now be the previously second-to-last active one */
248                         ks->active_path--;
249                 }
250                 else {
251                         BKE_report(op->reports, RPT_ERROR, "No active keying set path to remove");
252                         return OPERATOR_CANCELLED;
253                 }
254         }
255         else {
256                 BKE_report(op->reports, RPT_ERROR, "No active keying set to remove a path from");
257                 return OPERATOR_CANCELLED;
258         }
259
260         return OPERATOR_FINISHED;
261 }
262
263 void ANIM_OT_keying_set_path_remove(wmOperatorType *ot)
264 {
265         /* identifiers */
266         ot->name = "Remove Active Keying Set Path";
267         ot->idname = "ANIM_OT_keying_set_path_remove";
268         ot->description = "Remove active Path from active Keying Set";
269
270         /* callbacks */
271         ot->exec = remove_active_ks_path_exec;
272         ot->poll = keyingset_poll_activePath_edit;
273 }
274
275 /* ************************************************** */
276 /* KEYING SETS - OPERATORS (for use in UI menus) */
277
278 /* Add to KeyingSet Button Operator ------------------------ */
279
280 static int add_keyingset_button_exec(bContext *C, wmOperator *op)
281 {
282         Scene *scene = CTX_data_scene(C);
283         KeyingSet *ks = NULL;
284         PropertyRNA *prop = NULL;
285         PointerRNA ptr = {{NULL}};
286         char *path = NULL;
287         short success = 0;
288         int index = 0, pflag = 0;
289         const bool all = RNA_boolean_get(op->ptr, "all");
290
291         /* try to add to keyingset using property retrieved from UI */
292         if (!UI_context_active_but_prop_get(C, &ptr, &prop, &index)) {
293                 /* pass event on if no active button found */
294                 return (OPERATOR_CANCELLED | OPERATOR_PASS_THROUGH);
295         }
296
297         /* verify the Keying Set to use:
298          * - use the active one for now (more control over this can be added later)
299          * - add a new one if it doesn't exist
300          */
301         if (scene->active_keyingset == 0) {
302                 short flag = 0, keyingflag = 0;
303
304                 /* validate flags
305                  * - absolute KeyingSets should be created by default
306                  */
307                 flag |= KEYINGSET_ABSOLUTE;
308
309                 keyingflag |= ANIM_get_keyframing_flags(scene, 0);
310
311                 if (IS_AUTOKEY_FLAG(scene, XYZ2RGB))
312                         keyingflag |= INSERTKEY_XYZ2RGB;
313
314                 /* call the API func, and set the active keyingset index */
315                 ks = BKE_keyingset_add(&scene->keyingsets, "ButtonKeyingSet", "Button Keying Set", flag, keyingflag);
316
317                 scene->active_keyingset = BLI_listbase_count(&scene->keyingsets);
318         }
319         else if (scene->active_keyingset < 0) {
320                 BKE_report(op->reports, RPT_ERROR, "Cannot add property to built in keying set");
321                 return OPERATOR_CANCELLED;
322         }
323         else {
324                 ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
325         }
326
327         /* check if property is able to be added */
328         if (ptr.id.data && ptr.data && prop && RNA_property_animateable(&ptr, prop)) {
329                 path = RNA_path_from_ID_to_property(&ptr, prop);
330
331                 if (path) {
332                         /* set flags */
333                         if (all) {
334                                 pflag |= KSP_FLAG_WHOLE_ARRAY;
335
336                                 /* we need to set the index for this to 0, even though it may break in some cases, this is
337                                  * necessary if we want the entire array for most cases to get included without the user
338                                  * having to worry about where they clicked
339                                  */
340                                 index = 0;
341                         }
342
343                         /* add path to this setting */
344                         BKE_keyingset_add_path(ks, ptr.id.data, NULL, path, index, pflag, KSP_GROUP_KSNAME);
345                         ks->active_path = BLI_listbase_count(&ks->paths);
346                         success = 1;
347
348                         /* free the temp path created */
349                         MEM_freeN(path);
350                 }
351         }
352
353         if (success) {
354                 /* send updates */
355                 WM_event_add_notifier(C, NC_SCENE | ND_KEYINGSET, NULL);
356
357                 /* show notification/report header, so that users notice that something changed */
358                 BKE_reportf(op->reports, RPT_INFO, "Property added to Keying Set: '%s'", ks->name);
359         }
360
361         return (success) ? OPERATOR_FINISHED : OPERATOR_CANCELLED;
362 }
363
364 void ANIM_OT_keyingset_button_add(wmOperatorType *ot)
365 {
366         /* identifiers */
367         ot->name = "Add to Keying Set";
368         ot->idname = "ANIM_OT_keyingset_button_add";
369         ot->description = "Add current UI-active property to current keying set";
370
371         /* callbacks */
372         ot->exec = add_keyingset_button_exec;
373         //op->poll = ???
374
375         /* flags */
376         ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
377
378         /* properties */
379         RNA_def_boolean(ot->srna, "all", 1, "All", "Add all elements of the array to a Keying Set");
380 }
381
382 /* Remove from KeyingSet Button Operator ------------------------ */
383
384 static int remove_keyingset_button_exec(bContext *C, wmOperator *op)
385 {
386         Scene *scene = CTX_data_scene(C);
387         KeyingSet *ks = NULL;
388         PropertyRNA *prop = NULL;
389         PointerRNA ptr = {{NULL}};
390         char *path = NULL;
391         short success = 0;
392         int index = 0;
393
394         /* try to add to keyingset using property retrieved from UI */
395         if (UI_context_active_but_prop_get(C, &ptr, &prop, &index)) {
396                 /* pass event on if no active button found */
397                 return (OPERATOR_CANCELLED | OPERATOR_PASS_THROUGH);
398         }
399
400         /* verify the Keying Set to use:
401          * - use the active one for now (more control over this can be added later)
402          * - return error if it doesn't exist
403          */
404         if (scene->active_keyingset == 0) {
405                 BKE_report(op->reports, RPT_ERROR, "No active keying set to remove property from");
406                 return OPERATOR_CANCELLED;
407         }
408         else if (scene->active_keyingset < 0) {
409                 BKE_report(op->reports, RPT_ERROR, "Cannot remove property from built in keying set");
410                 return OPERATOR_CANCELLED;
411         }
412         else {
413                 ks = BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
414         }
415
416         if (ptr.id.data && ptr.data && prop) {
417                 path = RNA_path_from_ID_to_property(&ptr, prop);
418
419                 if (path) {
420                         KS_Path *ksp;
421
422                         /* try to find a path matching this description */
423                         ksp = BKE_keyingset_find_path(ks, ptr.id.data, ks->name, path, index, KSP_GROUP_KSNAME);
424
425                         if (ksp) {
426                                 BKE_keyingset_free_path(ks, ksp);
427                                 success = 1;
428                         }
429
430                         /* free temp path used */
431                         MEM_freeN(path);
432                 }
433         }
434
435
436         if (success) {
437                 /* send updates */
438                 WM_event_add_notifier(C, NC_SCENE | ND_KEYINGSET, NULL);
439
440                 /* show warning */
441                 BKE_report(op->reports, RPT_INFO, "Property removed from Keying Set");
442         }
443
444         return (success) ? OPERATOR_FINISHED : OPERATOR_CANCELLED;
445 }
446
447 void ANIM_OT_keyingset_button_remove(wmOperatorType *ot)
448 {
449         /* identifiers */
450         ot->name = "Remove from Keying Set";
451         ot->idname = "ANIM_OT_keyingset_button_remove";
452         ot->description = "Remove current UI-active property from current keying set";
453
454         /* callbacks */
455         ot->exec = remove_keyingset_button_exec;
456         //op->poll = ???
457
458         /* flags */
459         ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
460 }
461
462 /* ******************************************* */
463
464 /* Change Active KeyingSet Operator ------------------------ */
465 /* This operator checks if a menu should be shown for choosing the KeyingSet to make the active one */
466
467 static int keyingset_active_menu_invoke(bContext *C, wmOperator *op, const wmEvent *UNUSED(event))
468 {
469         uiPopupMenu *pup;
470         uiLayout *layout;
471
472         /* call the menu, which will call this operator again, hence the canceled */
473         pup = UI_popup_menu_begin(C, op->type->name, ICON_NONE);
474         layout = UI_popup_menu_layout(pup);
475         uiItemsEnumO(layout, "ANIM_OT_keying_set_active_set", "type");
476         UI_popup_menu_end(C, pup);
477
478         return OPERATOR_INTERFACE;
479 }
480
481 static int keyingset_active_menu_exec(bContext *C, wmOperator *op)
482 {
483         Scene *scene = CTX_data_scene(C);
484         int type = RNA_enum_get(op->ptr, "type");
485
486         /* If type == 0, it will deselect any active keying set. */
487         scene->active_keyingset = type;
488
489         /* send notifiers */
490         WM_event_add_notifier(C, NC_SCENE | ND_KEYINGSET, NULL);
491
492         return OPERATOR_FINISHED;
493 }
494
495 void ANIM_OT_keying_set_active_set(wmOperatorType *ot)
496 {
497         PropertyRNA *prop;
498
499         /* identifiers */
500         ot->name = "Set Active Keying Set";
501         ot->idname = "ANIM_OT_keying_set_active_set";
502         ot->description = "Select a new keying set as the active one";
503
504         /* callbacks */
505         ot->invoke = keyingset_active_menu_invoke;
506         ot->exec = keyingset_active_menu_exec;
507         ot->poll = ED_operator_areaactive;
508
509         /* flags */
510         ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
511
512         /* keyingset to use (dynamic enum) */
513         prop = RNA_def_enum(ot->srna, "type", DummyRNA_DEFAULT_items, 0, "Keying Set", "The Keying Set to use");
514         RNA_def_enum_funcs(prop, ANIM_keying_sets_enum_itemf);
515         // RNA_def_property_flag(prop, PROP_HIDDEN);
516 }
517
518 /* ******************************************* */
519 /* REGISTERED KEYING SETS */
520
521 /* Keying Set Type Info declarations */
522 static ListBase keyingset_type_infos = {NULL, NULL};
523
524 /* Built-In Keying Sets (referencing type infos)*/
525 ListBase builtin_keyingsets = {NULL, NULL};
526
527 /* --------------- */
528
529 /* Find KeyingSet type info given a name */
530 KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[])
531 {
532         /* sanity checks */
533         if ((name == NULL) || (name[0] == 0))
534                 return NULL;
535
536         /* search by comparing names */
537         return BLI_findstring(&keyingset_type_infos, name, offsetof(KeyingSetInfo, idname));
538 }
539
540 /* Find builtin KeyingSet by name */
541 KeyingSet *ANIM_builtin_keyingset_get_named(KeyingSet *prevKS, const char name[])
542 {
543         KeyingSet *ks, *first = NULL;
544
545         /* sanity checks  any name to check? */
546         if (name[0] == 0)
547                 return NULL;
548
549         /* get first KeyingSet to use */
550         if (prevKS && prevKS->next)
551                 first = prevKS->next;
552         else
553                 first = builtin_keyingsets.first;
554
555         /* loop over KeyingSets checking names */
556         for (ks = first; ks; ks = ks->next) {
557                 if (STREQ(name, ks->idname))
558                         return ks;
559         }
560
561         /* complain about missing keying sets on debug builds */
562 #ifndef NDEBUG
563         printf("%s: '%s' not found\n", __func__, name);
564 #endif
565
566         /* no matches found */
567         return NULL;
568 }
569
570 /* --------------- */
571
572 /* Add the given KeyingSetInfo to the list of type infos, and create an appropriate builtin set too */
573 void ANIM_keyingset_info_register(KeyingSetInfo *ksi)
574 {
575         KeyingSet *ks;
576
577         /* create a new KeyingSet
578          * - inherit name and keyframing settings from the typeinfo
579          */
580         ks = BKE_keyingset_add(&builtin_keyingsets, ksi->idname, ksi->name, 1, ksi->keyingflag);
581
582         /* link this KeyingSet with its typeinfo */
583         memcpy(&ks->typeinfo, ksi->idname, sizeof(ks->typeinfo));
584
585         /* Copy description... */
586         BLI_strncpy(ks->description, ksi->description, sizeof(ks->description));
587
588         /* add type-info to the list */
589         BLI_addtail(&keyingset_type_infos, ksi);
590 }
591
592 /* Remove the given KeyingSetInfo from the list of type infos, and also remove the builtin set if appropriate */
593 void ANIM_keyingset_info_unregister(Main *bmain, KeyingSetInfo *ksi)
594 {
595         KeyingSet *ks, *ksn;
596
597         /* find relevant builtin KeyingSets which use this, and remove them */
598         /* TODO: this isn't done now, since unregister is really only used atm when we
599          * reload the scripts, which kindof defeats the purpose of "builtin"? */
600         for (ks = builtin_keyingsets.first; ks; ks = ksn) {
601                 ksn = ks->next;
602
603                 /* remove if matching typeinfo name */
604                 if (STREQ(ks->typeinfo, ksi->idname)) {
605                         Scene *scene;
606                         BKE_keyingset_free(ks);
607                         BLI_remlink(&builtin_keyingsets, ks);
608
609                         for (scene = bmain->scene.first; scene; scene = scene->id.next)
610                                 BLI_remlink_safe(&scene->keyingsets, ks);
611
612                         MEM_freeN(ks);
613                 }
614         }
615
616         /* free the type info */
617         BLI_freelinkN(&keyingset_type_infos, ksi);
618 }
619
620 /* --------------- */
621
622 void ANIM_keyingset_infos_exit(void)
623 {
624         KeyingSetInfo *ksi, *next;
625
626         /* free type infos */
627         for (ksi = keyingset_type_infos.first; ksi; ksi = next) {
628                 next = ksi->next;
629
630                 /* free extra RNA data, and remove from list */
631                 if (ksi->ext.free)
632                         ksi->ext.free(ksi->ext.data);
633                 BLI_freelinkN(&keyingset_type_infos, ksi);
634         }
635
636         /* free builtin sets */
637         BKE_keyingsets_free(&builtin_keyingsets);
638 }
639
640 /* Check if the ID appears in the paths specified by the KeyingSet */
641 bool ANIM_keyingset_find_id(KeyingSet *ks, ID *id)
642 {
643         /* sanity checks */
644         if (ELEM(NULL, ks, id))
645                 return false;
646
647         return BLI_findptr(&ks->paths, id, offsetof(KS_Path, id)) != NULL;
648 }
649
650 /* ******************************************* */
651 /* KEYING SETS API (for UI) */
652
653 /* Getters for Active/Indices ----------------------------- */
654
655 /* Get the active Keying Set for the Scene provided */
656 KeyingSet *ANIM_scene_get_active_keyingset(Scene *scene)
657 {
658         /* if no scene, we've got no hope of finding the Keying Set */
659         if (scene == NULL)
660                 return NULL;
661
662         /* currently, there are several possibilities here:
663          * -   0: no active keying set
664          * - > 0: one of the user-defined Keying Sets, but indices start from 0 (hence the -1)
665          * - < 0: a builtin keying set
666          */
667         if (scene->active_keyingset > 0)
668                 return BLI_findlink(&scene->keyingsets, scene->active_keyingset - 1);
669         else
670                 return BLI_findlink(&builtin_keyingsets, (-scene->active_keyingset) - 1);
671 }
672
673 /* Get the index of the Keying Set provided, for the given Scene */
674 int ANIM_scene_get_keyingset_index(Scene *scene, KeyingSet *ks)
675 {
676         int index;
677
678         /* if no KeyingSet provided, have none */
679         if (ks == NULL)
680                 return 0;
681
682         /* check if the KeyingSet exists in scene list */
683         if (scene) {
684                 /* get index and if valid, return
685                  * - (absolute) Scene KeyingSets are from (>= 1)
686                  */
687                 index = BLI_findindex(&scene->keyingsets, ks);
688                 if (index != -1)
689                         return (index + 1);
690         }
691
692         /* still here, so try builtins list too
693          * - builtins are from (<= -1)
694          * - none/invalid is (= 0)
695          */
696         index = BLI_findindex(&builtin_keyingsets, ks);
697         if (index != -1)
698                 return -(index + 1);
699         else
700                 return 0;
701 }
702
703 /* Get Keying Set to use for Auto-Keyframing some transforms */
704 KeyingSet *ANIM_get_keyingset_for_autokeying(Scene *scene, const char *transformKSName)
705 {
706         /* get KeyingSet to use
707          * - use the active KeyingSet if defined (and user wants to use it for all autokeying),
708          *   or otherwise key transforms only
709          */
710         if (IS_AUTOKEY_FLAG(scene, ONLYKEYINGSET) && (scene->active_keyingset))
711                 return ANIM_scene_get_active_keyingset(scene);
712         else if (IS_AUTOKEY_FLAG(scene, INSERTAVAIL))
713                 return ANIM_builtin_keyingset_get_named(NULL, ANIM_KS_AVAILABLE_ID);
714         else
715                 return ANIM_builtin_keyingset_get_named(NULL, transformKSName);
716 }
717
718 /* Menu of All Keying Sets ----------------------------- */
719
720 /* Dynamically populate an enum of Keying Sets */
721 const EnumPropertyItem *ANIM_keying_sets_enum_itemf(bContext *C, PointerRNA *UNUSED(ptr), PropertyRNA *UNUSED(prop), bool *r_free)
722 {
723         Scene *scene = CTX_data_scene(C);
724         KeyingSet *ks;
725         EnumPropertyItem *item = NULL, item_tmp = {0};
726         int totitem = 0;
727         int i = 0;
728
729         if (C == NULL) {
730                 return DummyRNA_DEFAULT_items;
731         }
732
733         /* active Keying Set
734          * - only include entry if it exists
735          */
736         if (scene->active_keyingset) {
737                 /* active Keying Set */
738                 item_tmp.identifier = "__ACTIVE__";
739                 item_tmp.name = "Active Keying Set";
740                 item_tmp.value = i;
741                 RNA_enum_item_add(&item, &totitem, &item_tmp);
742
743                 /* separator */
744                 RNA_enum_item_add_separator(&item, &totitem);
745         }
746
747         i++;
748
749         /* user-defined Keying Sets
750          * - these are listed in the order in which they were defined for the active scene
751          */
752         if (scene->keyingsets.first) {
753                 for (ks = scene->keyingsets.first; ks; ks = ks->next, i++) {
754                         if (ANIM_keyingset_context_ok_poll(C, ks)) {
755                                 item_tmp.identifier = ks->idname;
756                                 item_tmp.name = ks->name;
757                                 item_tmp.description = ks->description;
758                                 item_tmp.value = i;
759                                 RNA_enum_item_add(&item, &totitem, &item_tmp);
760                         }
761                 }
762
763                 /* separator */
764                 RNA_enum_item_add_separator(&item, &totitem);
765         }
766
767         /* builtin Keying Sets */
768         i = -1;
769         for (ks = builtin_keyingsets.first; ks; ks = ks->next, i--) {
770                 /* only show KeyingSet if context is suitable */
771                 if (ANIM_keyingset_context_ok_poll(C, ks)) {
772                         item_tmp.identifier = ks->idname;
773                         item_tmp.name = ks->name;
774                         item_tmp.description = ks->description;
775                         item_tmp.value = i;
776                         RNA_enum_item_add(&item, &totitem, &item_tmp);
777                 }
778         }
779
780         RNA_enum_item_end(&item, &totitem);
781         *r_free = true;
782
783         return item;
784 }
785
786 /* ******************************************* */
787 /* KEYFRAME MODIFICATION */
788
789 /* Polling API ----------------------------------------------- */
790
791 /* Check if KeyingSet can be used in the current context */
792 bool ANIM_keyingset_context_ok_poll(bContext *C, KeyingSet *ks)
793 {
794         if ((ks->flag & KEYINGSET_ABSOLUTE) == 0) {
795                 KeyingSetInfo *ksi = ANIM_keyingset_info_find_name(ks->typeinfo);
796
797                 /* get the associated 'type info' for this KeyingSet */
798                 if (ksi == NULL)
799                         return 0;
800                 /* TODO: check for missing callbacks! */
801
802                 /* check if it can be used in the current context */
803                 return (ksi->poll(ksi, C));
804         }
805
806         return true;
807 }
808
809 /* Special 'Overrides' Iterator for Relative KeyingSets ------ */
810
811 /* 'Data Sources' for relative Keying Set 'overrides'
812  * - this is basically a wrapper for PointerRNA's in a linked list
813  * - do not allow this to be accessed from outside for now
814  */
815 typedef struct tRKS_DSource {
816         struct tRKS_DSource *next, *prev;
817         PointerRNA ptr;     /* the whole point of this exercise! */
818 } tRKS_DSource;
819
820
821 /* Iterator used for overriding the behavior of iterators defined for
822  * relative Keying Sets, with the main usage of this being operators
823  * requiring Auto Keyframing. Internal Use Only!
824  */
825 static void RKS_ITER_overrides_list(KeyingSetInfo *ksi, bContext *C, KeyingSet *ks, ListBase *dsources)
826 {
827         tRKS_DSource *ds;
828
829         for (ds = dsources->first; ds; ds = ds->next) {
830                 /* run generate callback on this data */
831                 ksi->generate(ksi, C, ks, &ds->ptr);
832         }
833 }
834
835 /* Add new data source for relative Keying Sets */
836 void ANIM_relative_keyingset_add_source(ListBase *dsources, ID *id, StructRNA *srna, void *data)
837 {
838         tRKS_DSource *ds;
839
840         /* sanity checks
841          * - we must have somewhere to output the data
842          * - we must have both srna+data (and with id too optionally), or id by itself only
843          */
844         if (dsources == NULL)
845                 return;
846         if (ELEM(NULL, srna, data) && (id == NULL))
847                 return;
848
849         /* allocate new elem, and add to the list */
850         ds = MEM_callocN(sizeof(tRKS_DSource), "tRKS_DSource");
851         BLI_addtail(dsources, ds);
852
853         /* depending on what data we have, create using ID or full pointer call */
854         if (srna && data)
855                 RNA_pointer_create(id, srna, data, &ds->ptr);
856         else
857                 RNA_id_pointer_create(id, &ds->ptr);
858 }
859
860 /* KeyingSet Operations (Insert/Delete Keyframes) ------------ */
861
862 /* Given a KeyingSet and context info, validate Keying Set's paths.
863  * This is only really necessary with relative/built-in KeyingSets
864  * where their list of paths is dynamically generated based on the
865  * current context info.
866  *
867  * Returns 0 if succeeded, otherwise an error code: eModifyKey_Returns
868  */
869 short ANIM_validate_keyingset(bContext *C, ListBase *dsources, KeyingSet *ks)
870 {
871         /* sanity check */
872         if (ks == NULL)
873                 return 0;
874
875         /* if relative Keying Sets, poll and build up the paths */
876         if ((ks->flag & KEYINGSET_ABSOLUTE) == 0) {
877                 KeyingSetInfo *ksi = ANIM_keyingset_info_find_name(ks->typeinfo);
878
879                 /* clear all existing paths
880                  * NOTE: BKE_keyingset_free() frees all of the paths for the KeyingSet, but not the set itself
881                  */
882                 BKE_keyingset_free(ks);
883
884                 /* get the associated 'type info' for this KeyingSet */
885                 if (ksi == NULL)
886                         return MODIFYKEY_MISSING_TYPEINFO;
887                 /* TODO: check for missing callbacks! */
888
889                 /* check if it can be used in the current context */
890                 if (ksi->poll(ksi, C)) {
891                         /* if a list of data sources are provided, run a special iterator over them,
892                          * otherwise, just continue per normal
893                          */
894                         if (dsources)
895                                 RKS_ITER_overrides_list(ksi, C, ks, dsources);
896                         else
897                                 ksi->iter(ksi, C, ks);
898
899                         /* if we don't have any paths now, then this still qualifies as invalid context */
900                         // FIXME: we need some error conditions (to be retrieved from the iterator why this failed!)
901                         if (BLI_listbase_is_empty(&ks->paths))
902                                 return MODIFYKEY_INVALID_CONTEXT;
903                 }
904                 else {
905                         /* poll callback tells us that KeyingSet is useless in current context */
906                         // FIXME: the poll callback needs to give us more info why
907                         return MODIFYKEY_INVALID_CONTEXT;
908                 }
909         }
910
911         /* succeeded; return 0 to tag error free */
912         return 0;
913 }
914
915 /* Determine which keying flags apply based on the override flags */
916 static short keyingset_apply_keying_flags(const short base_flags, const short overrides, const short own_flags)
917 {
918         /* Pass through all flags by default (i.e. even not explicitly listed ones). */
919         short result = base_flags;
920
921         /* The logic for whether a keying flag applies is as follows:
922          * - If the flag in question is set in "overrides", that means that the
923          *   status of that flag in "own_flags" is used
924          * - If however the flag isn't set, then its value in "base_flags" is used
925          *   instead (i.e. no override)
926          */
927 #define APPLY_KEYINGFLAG_OVERRIDE(kflag) \
928         if (overrides & kflag) {             \
929                 result &= ~kflag;                \
930                 result |= (own_flags & kflag);   \
931         }
932
933         /* Apply the flags one by one...
934          * (See rna_def_common_keying_flags() for the supported flags)
935          */
936         APPLY_KEYINGFLAG_OVERRIDE(INSERTKEY_NEEDED)
937         APPLY_KEYINGFLAG_OVERRIDE(INSERTKEY_MATRIX)
938         APPLY_KEYINGFLAG_OVERRIDE(INSERTKEY_XYZ2RGB)
939
940 #undef APPLY_KEYINGFLAG_OVERRIDE
941
942         return result;
943 }
944
945 /* Given a KeyingSet and context info (if required), modify keyframes for the channels specified
946  * by the KeyingSet. This takes into account many of the different combinations of using KeyingSets.
947  * Returns the number of channels that keyframes were added to
948  */
949 int ANIM_apply_keyingset(bContext *C, ListBase *dsources, bAction *act, KeyingSet *ks, short mode, float cfra)
950 {
951         Depsgraph *depsgraph = CTX_data_depsgraph(C);
952         Main *bmain = CTX_data_main(C);
953         Scene *scene = CTX_data_scene(C);
954         ReportList *reports = CTX_wm_reports(C);
955         KS_Path *ksp;
956         ListBase nla_cache = {NULL, NULL};
957         const short base_kflags = ANIM_get_keyframing_flags(scene, 1);
958         const char *groupname = NULL;
959         short kflag = 0, success = 0;
960         char keytype = scene->toolsettings->keyframe_type;
961
962         /* sanity checks */
963         if (ks == NULL)
964                 return 0;
965
966         /* get flags to use */
967         if (mode == MODIFYKEY_MODE_INSERT) {
968                 /* use context settings as base */
969                 kflag = keyingset_apply_keying_flags(base_kflags, ks->keyingoverride, ks->keyingflag);
970         }
971         else if (mode == MODIFYKEY_MODE_DELETE)
972                 kflag = 0;
973
974         /* if relative Keying Sets, poll and build up the paths */
975         success = ANIM_validate_keyingset(C, dsources, ks);
976
977         if (success != 0) {
978                 /* return error code if failed */
979                 return success;
980         }
981
982         /* apply the paths as specified in the KeyingSet now */
983         for (ksp = ks->paths.first; ksp; ksp = ksp->next) {
984                 int arraylen, i;
985                 short kflag2;
986
987                 /* skip path if no ID pointer is specified */
988                 if (ksp->id == NULL) {
989                         BKE_reportf(reports, RPT_WARNING,
990                                     "Skipping path in keying set, as it has no ID (KS = '%s', path = '%s[%d]')",
991                                     ks->name, ksp->rna_path, ksp->array_index);
992                         continue;
993                 }
994
995                 /* since keying settings can be defined on the paths too, apply the settings for this path first */
996                 kflag2 = keyingset_apply_keying_flags(kflag, ksp->keyingoverride, ksp->keyingflag);
997
998                 /* get pointer to name of group to add channels to */
999                 if (ksp->groupmode == KSP_GROUP_NONE)
1000                         groupname = NULL;
1001                 else if (ksp->groupmode == KSP_GROUP_KSNAME)
1002                         groupname = ks->name;
1003                 else
1004                         groupname = ksp->group;
1005
1006                 /* init arraylen and i - arraylen should be greater than i so that
1007                  * normal non-array entries get keyframed correctly
1008                  */
1009                 i = ksp->array_index;
1010                 arraylen = i;
1011
1012                 /* get length of array if whole array option is enabled */
1013                 if (ksp->flag & KSP_FLAG_WHOLE_ARRAY) {
1014                         PointerRNA id_ptr, ptr;
1015                         PropertyRNA *prop;
1016
1017                         RNA_id_pointer_create(ksp->id, &id_ptr);
1018                         if (RNA_path_resolve_property(&id_ptr, ksp->rna_path, &ptr, &prop)) {
1019                                 arraylen = RNA_property_array_length(&ptr, prop);
1020                                 /* start from start of array, instead of the previously specified index - T48020 */
1021                                 i = 0;
1022                         }
1023                 }
1024
1025                 /* we should do at least one step */
1026                 if (arraylen == i)
1027                         arraylen++;
1028
1029                 /* for each possible index, perform operation
1030                  * - assume that arraylen is greater than index
1031                  */
1032                 for (; i < arraylen; i++) {
1033                         /* action to take depends on mode */
1034                         if (mode == MODIFYKEY_MODE_INSERT)
1035                                 success += insert_keyframe(bmain, depsgraph, reports, ksp->id, act, groupname, ksp->rna_path, i, cfra, keytype, &nla_cache, kflag2);
1036                         else if (mode == MODIFYKEY_MODE_DELETE)
1037                                 success += delete_keyframe(bmain, reports, ksp->id, act, groupname, ksp->rna_path, i, cfra, kflag2);
1038                 }
1039
1040                 /* set recalc-flags */
1041                 switch (GS(ksp->id->name)) {
1042                         case ID_OB: /* Object (or Object-Related) Keyframes */
1043                         {
1044                                 Object *ob = (Object *)ksp->id;
1045
1046                                 // XXX: only object transforms?
1047                                 DEG_id_tag_update(&ob->id, ID_RECALC_TRANSFORM | ID_RECALC_GEOMETRY);
1048                                 break;
1049                         }
1050                         default:
1051                                 DEG_id_tag_update(ksp->id, ID_RECALC_COPY_ON_WRITE);
1052                                 break;
1053                 }
1054
1055                 /* send notifiers for updates (this doesn't require context to work!) */
1056                 WM_main_add_notifier(NC_ANIMATION | ND_KEYFRAME | NA_ADDED, NULL);
1057         }
1058
1059         BKE_animsys_free_nla_keyframing_context_cache(&nla_cache);
1060
1061         /* return the number of channels successfully affected */
1062         return success;
1063 }
1064
1065 /* ************************************************** */