Drivers Code Cleanups and UI Tweaks:
[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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 struct ListBase;
36 struct ID;
37 struct Scene;
38
39 struct KeyingSet;
40
41 struct bAction;
42 struct FCurve;
43 struct BezTriple;
44
45 struct bPoseChannel;
46 struct bConstraint;
47
48 struct bContext;
49 struct wmOperatorType;
50 struct ReportList;
51
52 struct PointerRNA;
53 struct PropertyRNA;
54
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 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 bAction *act, const char group[], const char rna_path[], const int array_index, short add);
75
76 /* -------- */
77
78 /* Lesser Keyframing API call:
79  *      Use this when validation of necessary animation data isn't necessary as it already
80  *      exists, and there is a beztriple that can be directly copied into the array.
81  */
82 int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt, short flag);
83
84 /* Main Keyframing API call: 
85  *      Use this when validation of necessary animation data isn't necessary as it
86  *      already exists. It will insert a keyframe using the current value being keyframed.
87  *      Returns the index at which a keyframe was added (or -1 if failed)
88  */
89 int insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
90
91 /* -------- */
92
93 /* Secondary Keyframing API calls: 
94  *      Use this to insert a keyframe using the current value being keyframed, in the 
95  *      nominated F-Curve (no creation of animation data performed). Returns success.
96  */
97 short insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
98
99 /* -------- */
100
101 /* Main Keyframing API calls: 
102  *      Use this to create any necessary animation data, and then insert a keyframe
103  *      using the current value being keyframed, in the relevant place. Returns success.
104  */
105 short insert_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
106
107 /* Main Keyframing API call: 
108  *      Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
109  */
110 short delete_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
111
112 /* ************ Keying Sets ********************** */
113
114 /* forward decl. for this struct which is declared a bit later... */
115 struct KeyingSetInfo;
116 struct ExtensionRNA;
117
118 /* Polling Callback for KeyingSets */
119 typedef int (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C);
120 /* Context Iterator Callback for KeyingSets */
121 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks);
122 /* Property Specifier Callback for KeyingSets (called from iterators) */
123 typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks, struct PointerRNA *ptr); 
124
125
126 /* Callback info for 'Procedural' KeyingSets to use */
127 typedef struct KeyingSetInfo {
128         struct KeyingSetInfo *next, *prev;
129         
130         /* info */
131                 /* identifier so that user can hook this up to a KeyingSet */
132         char name[64];
133                 /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
134         char idname[64];
135                 /* keying settings */
136         short keyingflag;
137         
138         /* polling callbacks */
139                 /* callback for polling the context for whether the right data is available */
140         cbKeyingSet_Poll poll;
141         
142         /* generate callbacks */
143                 /* iterator to use to go through collections of data in context
144                  *      - this callback is separate from the 'adding' stage, allowing 
145                  *        BuiltIn KeyingSets to be manually specified to use 
146                  */
147         cbKeyingSet_Iterator iter;
148                 /* generator to use to add properties based on the data found by iterator */
149         cbKeyingSet_Generate generate;
150         
151         /* RNA integration */
152         struct ExtensionRNA ext;
153 } KeyingSetInfo;
154
155 /* -------- */
156
157 /* Add another data source for Relative Keying Sets to be evaluated with */
158 void ANIM_relative_keyingset_add_source(ListBase *dsources, struct ID *id, struct StructRNA *srna, void *data);
159
160
161 /* mode for modify_keyframes */
162 typedef enum eModifyKey_Modes {
163         MODIFYKEY_MODE_INSERT = 0,
164         MODIFYKEY_MODE_DELETE,
165 } eModifyKey_Modes;
166
167 /* return codes for errors (with Relative KeyingSets) */
168 typedef enum eModifyKey_Returns {
169                 /* context info was invalid for using the Keying Set */
170         MODIFYKEY_INVALID_CONTEXT = -1,
171                 /* there isn't any typeinfo for generating paths from context */
172         MODIFYKEY_MISSING_TYPEINFO = -2,
173 } eModifyKey_Returns;
174
175 /* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
176 int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
177
178 /* -------- */
179
180 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
181 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
182
183 /* Find KeyingSet type info given a name */
184 KeyingSetInfo *ANIM_keyingset_info_find_named(const char name[]);
185
186 /* for RNA type registrations... */
187 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
188 void ANIM_keyingset_info_unregister(const struct bContext *C, KeyingSetInfo *ksi);
189
190 /* cleanup on exit */
191 void ANIM_keyingset_infos_exit(void);
192
193 /* -------- */
194
195 /* Get the active KeyingSet for the given scene */
196 struct KeyingSet *ANIM_scene_get_active_keyingset(struct Scene *scene);
197
198 /* Get the index of the Keying Set provided, for the given Scene */
199 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
200
201 /* Get Keying Set to use for Auto-Keyframing some transforms */
202 struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene, const char *tranformKSName);
203
204 /* Create (and show) a menu containing all the Keying Sets which can be used in the current context */
205 void ANIM_keying_sets_menu_setup(struct bContext *C, const char title[], const char op_name[]);
206
207 /* Check if KeyingSet can be used in the current context */
208 short ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
209
210 /* ************ Drivers ********************** */
211
212 /* Flags for use by driver creation calls */
213 typedef enum eCreateDriverFlags {
214         CREATEDRIVER_WITH_DEFAULT_DVAR  = (1<<0),       /* create drivers with a default variable for nicer UI */
215 } eCreateDriverFlags;
216
217 /* -------- */
218
219 /* Returns whether there is a driver in the copy/paste buffer to paste */
220 short ANIM_driver_can_paste(void);
221
222 /* Main Driver Management API calls:
223  *      Add a new driver for the specified property on the given ID block
224  */
225 short ANIM_add_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag, int type);
226
227 /* Main Driver Management API calls:
228  *      Remove the driver for the specified property on the given ID block (if available)
229  */
230 short ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
231
232 /* Main Driver Management API calls:
233  *      Make a copy of the driver for the specified property on the given ID block
234  */
235 short ANIM_copy_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
236
237 /* Main Driver Management API calls:
238  *      Add a new driver for the specified property on the given ID block or replace an existing one
239  *      with the driver + driver-curve data from the buffer 
240  */
241 short ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
242
243 /* ************ Auto-Keyframing ********************** */
244 /* Notes:
245  * - All the defines for this (User-Pref settings and Per-Scene settings)
246  *      are defined in DNA_userdef_types.h
247  * - Scene settings take presidence over those for userprefs, with old files
248  *      inheriting userpref settings for the scene settings
249  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
250  *      as userprefs
251  */
252
253 /* Auto-Keying macros for use by various tools */
254         /* check if auto-keyframing is enabled (per scene takes presidence) */
255 #define IS_AUTOKEY_ON(scene)    ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
256         /* check the mode for auto-keyframing (per scene takes presidence)  */
257 #define IS_AUTOKEY_MODE(scene, mode)    ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
258         /* check if a flag is set for auto-keyframing (as userprefs only!) */
259 #define IS_AUTOKEY_FLAG(flag)   (U.autokey_flag & AUTOKEY_FLAG_##flag)
260
261 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
262 int autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
263
264 /* ************ Keyframe Checking ******************** */
265
266 /* Lesser Keyframe Checking API call:
267  *      - Used for the buttons to check for keyframes...
268  */
269 short fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
270
271 /* Main Keyframe Checking API call:
272  * Checks whether a keyframe exists for the given ID-block one the given frame.
273  *  - It is recommended to call this method over the other keyframe-checkers directly,
274  *        in case some detail of the implementation changes...
275  *      - frame: the value of this is quite often result of BKE_curframe()
276  */
277 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
278
279 /* filter flags for id_cfra_has_keyframe 
280  *
281  * WARNING: do not alter order of these, as also stored in files
282  *      (for v3d->keyflags)
283  */
284 typedef enum eAnimFilterFlags {
285                 /* general */
286         ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
287         ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
288         ANIMFILTER_KEYS_ACTIVE  = (1<<2),               /* only include active-subelements */
289         
290                 /* object specific */
291         ANIMFILTER_KEYS_NOMAT           = (1<<9),               /* don't include material keyframes */
292         ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
293 } eAnimFilterFlags;
294
295 #ifdef __cplusplus
296 }
297 #endif
298
299 #endif /*  ED_KEYFRAMING_H */