svn merge https://svn.blender.org/svnroot/bf-blender/trunk/blender -r22205:22290
[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 struct Scene;
34
35 struct KeyingSet;
36
37 struct bAction;
38 struct FCurve;
39 struct BezTriple;
40
41 struct bPoseChannel;
42 struct bConstraint;
43
44 struct bContext;
45 struct wmOperatorType;
46
47 struct PointerRNA;
48 struct PropertyRNA;
49
50 /* ************ Keyframing Management **************** */
51
52 /* Get (or add relevant data to be able to do so) the Active Action for the given 
53  * Animation Data block, given an ID block where the Animation Data should reside.
54  */
55 struct bAction *verify_adt_action(struct ID *id, short add);
56
57 /* Get (or add relevant data to be able to do so) F-Curve from the given Action. 
58  * This assumes that all the destinations are valid.
59  */
60 struct FCurve *verify_fcurve(struct bAction *act, const char group[], const char rna_path[], const int array_index, short add);
61
62 /* -------- */
63
64 /* Lesser Keyframing API call:
65  *      Use this when validation of necessary animation data isn't necessary as it already
66  *      exists, and there is a beztriple that can be directly copied into the array.
67  */
68 int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt);
69
70 /* Main Keyframing API call: 
71  *      Use this when validation of necessary animation data isn't necessary as it
72  *      already exists. It will insert a keyframe using the current value being keyframed.
73  */
74 void insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
75
76 /* -------- */
77
78 /* Secondary Keyframing API calls: 
79  *      Use this to insert a keyframe using the current value being keyframed, in the 
80  *      nominated F-Curve (no creation of animation data performed). Returns success.
81  */
82 short insert_keyframe_direct(struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
83
84
85
86 /* -------- */
87
88 /* Main Keyframing API calls: 
89  *      Use this to create any necessary animation data, and then insert a keyframe
90  *      using the current value being keyframed, in the relevant place. Returns success.
91  */
92 short insert_keyframe(struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
93
94 /* Main Keyframing API call: 
95  *      Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
96  */
97 short delete_keyframe(struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
98
99 /* -------- */
100
101 /* Main Keyframe Management operators: 
102  *      These handle keyframes management from various spaces. They only make use of
103  *      Keying Sets.
104  */
105 void ANIM_OT_insert_keyframe(struct wmOperatorType *ot);
106 void ANIM_OT_delete_keyframe(struct wmOperatorType *ot);
107
108 /* Main Keyframe Management operators: 
109  *      These handle keyframes management from various spaces. They will handle the menus 
110  *      required for each space.
111  */
112 void ANIM_OT_insert_keyframe_menu(struct wmOperatorType *ot);
113 void ANIM_OT_delete_keyframe_v3d(struct wmOperatorType *ot);
114
115 /* Keyframe managment operators for UI buttons. */
116 void ANIM_OT_insert_keyframe_button(struct wmOperatorType *ot);
117 void ANIM_OT_delete_keyframe_button(struct wmOperatorType *ot);
118
119 /* ************ Keying Sets ********************** */
120
121 /* temporary struct to gather data combos to keyframe
122  * (is used by modify_keyframes for 'relative' KeyingSets, provided via the dsources arg)
123  */
124 typedef struct bCommonKeySrc {
125         struct bCommonKeySrc *next, *prev;
126                 
127                 /* general data/destination-source settings */
128         struct ID *id;                                  /* id-block this comes from */
129         
130                 /* specific cases */
131         struct bPoseChannel *pchan;     
132         struct bConstraint *con;
133 } bCommonKeySrc;
134
135 /* -------- */
136
137 /* mode for modify_keyframes */
138 enum {
139         MODIFYKEY_MODE_INSERT = 0,
140         MODIFYKEY_MODE_DELETE,
141 } eModifyKey_Modes;
142
143 /* Keyframing Helper Call - use the provided Keying Set to Add/Remove Keyframes */
144 int modify_keyframes(struct bContext *C, struct ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
145
146 /* -------- */
147
148 /* Generate menu of KeyingSets */
149 char *ANIM_build_keyingsets_menu(struct ListBase *list, short for_edit);
150
151 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
152 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, char name[]);
153
154 /* Initialise builtin KeyingSets on startup */
155 void init_builtin_keyingsets(void);
156
157 /* -------- */
158
159 /* KeyingSet Editing Operators:
160  *      These can add a new KeyingSet and/or add 'destinations' to the KeyingSets,
161  *      acting as a means by which they can be added outside the Outliner.
162  */
163 void ANIM_OT_keyingset_add_new(struct wmOperatorType *ot);
164 void ANIM_OT_keyingset_add_destination(struct wmOperatorType *ot);
165
166 /* ************ Drivers ********************** */
167
168 /* Main Driver Management API calls:
169  *      Add a new driver for the specified property on the given ID block
170  */
171 short ANIM_add_driver (struct ID *id, const char rna_path[], int array_index, short flag, int type);
172
173 /* Main Driver Management API calls:
174  *      Remove the driver for the specified property on the given ID block (if available)
175  */
176 short ANIM_remove_driver (struct ID *id, const char rna_path[], int array_index, short flag);
177
178 /* Driver management operators for UI buttons */
179 void ANIM_OT_add_driver_button(struct wmOperatorType *ot);
180 void ANIM_OT_remove_driver_button(struct wmOperatorType *ot);
181
182 /* ************ Auto-Keyframing ********************** */
183 /* Notes:
184  * - All the defines for this (User-Pref settings and Per-Scene settings)
185  *      are defined in DNA_userdef_types.h
186  * - Scene settings take presidence over those for userprefs, with old files
187  *      inheriting userpref settings for the scene settings
188  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
189  *      as userprefs
190  */
191
192 /* Auto-Keying macros for use by various tools */
193         /* check if auto-keyframing is enabled (per scene takes presidence) */
194 #define IS_AUTOKEY_ON(scene)    ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
195         /* check the mode for auto-keyframing (per scene takes presidence)  */
196 #define IS_AUTOKEY_MODE(scene, mode)    ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
197         /* check if a flag is set for auto-keyframing (as userprefs only!) */
198 #define IS_AUTOKEY_FLAG(flag)   (U.autokey_flag & AUTOKEY_FLAG_##flag)
199
200 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
201 int autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
202
203 /* ************ Keyframe Checking ******************** */
204
205 /* Lesser Keyframe Checking API call:
206  *      - Used for the buttons to check for keyframes...
207  */
208 short fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
209
210 /* Main Keyframe Checking API call:
211  * Checks whether a keyframe exists for the given ID-block one the given frame.
212  *  - It is recommended to call this method over the other keyframe-checkers directly,
213  *        in case some detail of the implementation changes...
214  *      - frame: the value of this is quite often result of frame_to_float(CFRA)
215  */
216 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
217
218 /* filter flags for id_cfra_has_keyframe 
219  *
220  * WARNING: do not alter order of these, as also stored in files
221  *      (for v3d->keyflags)
222  */
223 enum {
224                 /* general */
225         ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
226         ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
227         ANIMFILTER_KEYS_ACTIVE  = (1<<2),               /* only include active-subelements */
228         
229                 /* object specific */
230         ANIMFILTER_KEYS_NOMAT           = (1<<9),               /* don't include material keyframes */
231         ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
232 } eAnimFilterFlags;
233
234 #endif /*  ED_KEYFRAMING_H */