svn merge -r 21041:21243 https://svn.blender.org/svnroot/bf-blender/branches/blender2...
[blender.git] / source / blender / editors / include / ED_keyframing.h
1 /**
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place * Suite 330, Boston, MA  02111*1307, USA.
19  *
20  * The Original Code is Copyright (C) 2008, Blender Foundation
21  * This is a new part of Blender (with some old code)
22  *
23  * Contributor(s): Joshua Leung
24  *
25  * ***** END GPL LICENSE BLOCK *****
26  */
27
28 #ifndef ED_KEYFRAMING_H
29 #define ED_KEYFRAMING_H
30
31 struct ListBase;
32 struct ID;
33
34 struct KeyingSet;
35
36 struct bAction;
37 struct FCurve;
38 struct BezTriple;
39
40 struct bPoseChannel;
41 struct bConstraint;
42
43 struct bContext;
44 struct wmOperatorType;
45
46 /* ************ Keyframing Management **************** */
47
48 /* Get (or add relevant data to be able to do so) the Active Action for the given 
49  * Animation Data block, given an ID block where the Animation Data should reside.
50  */
51 struct bAction *verify_adt_action(struct ID *id, short add);
52
53 /* Get (or add relevant data to be able to do so) F-Curve from the given Action. 
54  * This assumes that all the destinations are valid.
55  */
56 struct FCurve *verify_fcurve(struct bAction *act, const char group[], const char rna_path[], const int array_index, short add);
57
58 /* -------- */
59
60 /* Lesser Keyframing API call:
61  *      Use this when validation of necessary animation data isn't necessary as it already
62  *      exists, and there is a beztriple that can be directly copied into the array.
63  */
64 int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt);
65
66 /* Main Keyframing API call: 
67  *      Use this when validation of necessary animation data isn't necessary as it
68  *      already exists. It will insert a keyframe using the current value being keyframed.
69  */
70 void insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
71
72 /* -------- */
73
74 /* Main Keyframing API calls: 
75  *      Use this to create any necessary animation data, and then insert a keyframe
76  *      using the current value being keyframed, in the relevant place. Returns success.
77  */
78 short insert_keyframe(struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
79
80 /* Main Keyframing API call: 
81  *      Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
82  */
83 short delete_keyframe(struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
84
85 /* -------- */
86
87 /* Main Keyframe Management operators: 
88  *      These handle keyframes management from various spaces. They only make use of
89  *      Keying Sets.
90  */
91 void ANIM_OT_insert_keyframe(struct wmOperatorType *ot);
92 void ANIM_OT_delete_keyframe(struct wmOperatorType *ot);
93
94 /* Main Keyframe Management operators: 
95  *      These handle keyframes management from various spaces. They will handle the menus 
96  *      required for each space.
97  */
98 void ANIM_OT_insert_keyframe_menu(struct wmOperatorType *ot);
99 void ANIM_OT_delete_keyframe_menu(struct wmOperatorType *ot); // xxx unimplemented yet
100 void ANIM_OT_delete_keyframe_old(struct wmOperatorType *ot); // xxx rename and keep?
101
102 /* Keyframe managment operators for UI buttons. */
103 void ANIM_OT_insert_keyframe_button(struct wmOperatorType *ot);
104 void ANIM_OT_delete_keyframe_button(struct wmOperatorType *ot);
105
106 /* ************ Keying Sets ********************** */
107
108 /* temporary struct to gather data combos to keyframe
109  * (is used by modify_keyframes for 'relative' KeyingSets, provided via the dsources arg)
110  */
111 typedef struct bCommonKeySrc {
112         struct bCommonKeySrc *next, *prev;
113                 
114                 /* general data/destination-source settings */
115         struct ID *id;                                  /* id-block this comes from */
116         
117                 /* specific cases */
118         struct bPoseChannel *pchan;     
119         struct bConstraint *con;
120 } bCommonKeySrc;
121
122 /* -------- */
123
124 /* mode for modify_keyframes */
125 enum {
126         MODIFYKEY_MODE_INSERT = 0,
127         MODIFYKEY_MODE_DELETE,
128 } eModifyKey_Modes;
129
130 /* Keyframing Helper Call - use the provided Keying Set to Add/Remove Keyframes */
131 int modify_keyframes(struct bContext *C, struct ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
132
133 /* -------- */
134
135 /* Generate menu of KeyingSets */
136 char *ANIM_build_keyingsets_menu(struct ListBase *list, short for_edit);
137
138 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
139 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, char name[]);
140
141 /* Initialise builtin KeyingSets on startup */
142 void init_builtin_keyingsets(void);
143
144 /* -------- */
145
146 /* KeyingSet Editing Operators:
147  *      These can add a new KeyingSet and/or add 'destinations' to the KeyingSets,
148  *      acting as a means by which they can be added outside the Outliner.
149  */
150 void ANIM_OT_keyingset_add_new(struct wmOperatorType *ot);
151 void ANIM_OT_keyingset_add_destination(struct wmOperatorType *ot);
152
153 /* ************ Drivers ********************** */
154
155 /* Main Driver Management API calls:
156  *      Add a new driver for the specified property on the given ID block
157  */
158 short ANIM_add_driver (struct ID *id, const char rna_path[], int array_index, short flag);
159
160 /* Main Driver Management API calls:
161  *      Remove the driver for the specified property on the given ID block (if available)
162  */
163 short ANIM_remove_driver (struct ID *id, const char rna_path[], int array_index, short flag);
164
165 /* Driver management operators for UI buttons */
166 void ANIM_OT_add_driver_button(struct wmOperatorType *ot);
167 void ANIM_OT_remove_driver_button(struct wmOperatorType *ot);
168
169 /* ************ Auto-Keyframing ********************** */
170 /* Notes:
171  * - All the defines for this (User-Pref settings and Per-Scene settings)
172  *      are defined in DNA_userdef_types.h
173  * - Scene settings take presidence over those for userprefs, with old files
174  *      inheriting userpref settings for the scene settings
175  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
176  *      as userprefs
177  */
178
179 /* Auto-Keying macros for use by various tools */
180         /* check if auto-keyframing is enabled (per scene takes presidence) */
181 #define IS_AUTOKEY_ON(scene)    ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
182         /* check the mode for auto-keyframing (per scene takes presidence)  */
183 #define IS_AUTOKEY_MODE(scene, mode)    ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
184         /* check if a flag is set for auto-keyframing (as userprefs only!) */
185 #define IS_AUTOKEY_FLAG(flag)   (U.autokey_flag & AUTOKEY_FLAG_##flag)
186
187 /* ************ Keyframe Checking ******************** */
188
189 /* Main Keyframe Checking API call:
190  * Checks whether a keyframe exists for the given ID-block one the given frame.
191  *  - It is recommended to call this method over the other keyframe-checkers directly,
192  *        in case some detail of the implementation changes...
193  *      - frame: the value of this is quite often result of frame_to_float(CFRA)
194  */
195 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
196
197 /* filter flags for id_cfra_has_keyframe 
198  *
199  * WARNING: do not alter order of these, as also stored in files
200  *      (for v3d->keyflags)
201  */
202 enum {
203                 /* general */
204         ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
205         ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
206         ANIMFILTER_KEYS_ACTIVE  = (1<<2),               /* only include active-subelements */
207         
208                 /* object specific */
209         ANIMFILTER_KEYS_NOMAT           = (1<<9),               /* don't include material keyframes */
210         ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
211 } eAnimFilterFlags;
212
213 #endif /*  ED_KEYFRAMING_H */