2.5
[blender.git] / source / blender / editors / include / ED_anim_api.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  * All rights reserved.
22  *
23  * 
24  * Contributor(s): Joshua Leung
25  *
26  * ***** END GPL LICENSE BLOCK *****
27  */
28
29 #ifndef ED_ANIM_API_H
30 #define ED_ANIM_API_H
31
32 struct ID;
33 struct Scene;
34 struct ListBase;
35 struct bContext;
36 struct wmWindowManager;
37 struct ScrArea;
38 struct ARegion;
39 struct View2D;
40 struct gla2DDrawInfo;
41 struct Object;
42 struct bActionGroup;
43 struct Ipo;
44 struct IpoCurve;
45
46 /* ************************************************ */
47 /* ANIMATION CHANNEL FILTERING */
48 /* anim_filter.c */
49
50 /* --------------- Context --------------------- */
51
52 /* This struct defines a structure used for animation-specific 
53  * 'context' information
54  */
55 typedef struct bAnimContext {
56         void *data;                             /* data to be filtered for use in animation editor */
57         short datatype;                 /* type of data eAnimCont_Types */
58         
59         short mode;                             /* editor->mode */
60         short spacetype;                /* sa->spacetype */
61         short regiontype;               /* active region -> type (channels or main) */
62         struct ScrArea *sa;             /* editor */ 
63         struct ARegion *ar;             /* region within editor */
64         
65         struct Scene *scene;    /* active scene */
66         struct Object *obact;   /* active object */
67 } bAnimContext;
68
69 /* Main Data container types */
70 // XXX was ACTCONT_*
71 typedef enum eAnimCont_Types {
72         ANIMCONT_NONE = 0,              /* invalid or no data */
73         ANIMCONT_ACTION,                /* action (bAction) */
74         ANIMCONT_SHAPEKEY,              /* shapekey (Key) */
75         ANIMCONT_GPENCIL,               /* grease pencil (screen) */
76         ANIMCONT_DOPESHEET,             /* dopesheet (bDopesheet) */
77         ANIMCONT_IPO,                   /* single IPO (Ipo) */
78 } eAnimCont_Types;
79
80 /* --------------- Channels -------------------- */
81
82 /* This struct defines a structure used for quick and uniform access for 
83  * channels of animation data
84  */
85 typedef struct bAnimListElem {
86         struct bAnimListElem *next, *prev;
87         
88         void    *data;          /* source data this elem represents */
89         int     type;           /* one of the ANIMTYPE_* values */
90         int             flag;           /* copy of elem's flags for quick access */
91         int     index;          /* copy of adrcode where applicable */
92         
93         void    *key_data;      /* motion data - ipo or ipo-curve */
94         short   datatype;       /* type of motion data to expect */
95         
96         struct ID *id;                          /* ID block (ID_SC, ID_SCE, or ID_OB) that owns the channel */
97         struct bActionGroup *grp;       /* action group that owns the channel (only for Action/Dopesheet) */
98         
99         void    *owner;         /* will either be an action channel or fake ipo-channel (for keys) */
100         short   ownertype;      /* type of owner */
101 } bAnimListElem;
102
103
104 /* Some types for easier type-testing */
105 // XXX was ACTTYPE_*
106 typedef enum eAnim_ChannelType {
107         ANIMTYPE_NONE= 0,
108         ANIMTYPE_SPECIALDATA,
109         
110         ANIMTYPE_OBJECT,
111         ANIMTYPE_GROUP,
112         
113         ANIMTYPE_FILLIPO,
114         ANIMTYPE_FILLCON,
115         
116         ANIMTYPE_FILLACTD,
117         ANIMTYPE_FILLIPOD,
118         ANIMTYPE_FILLCOND,
119         ANIMTYPE_FILLMATD,
120         
121         ANIMTYPE_DSMAT,
122         ANIMTYPE_DSLAM,
123         ANIMTYPE_DSCAM,
124         ANIMTYPE_DSCUR,
125         ANIMTYPE_DSSKEY,
126         
127         ANIMTYPE_ACHAN,
128         ANIMTYPE_CONCHAN,
129         ANIMTYPE_CONCHAN2,
130         ANIMTYPE_ICU,
131         ANIMTYPE_IPO,
132         
133         ANIMTYPE_SHAPEKEY,
134         ANIMTYPE_GPDATABLOCK,
135         ANIMTYPE_GPLAYER,
136 } eAnim_ChannelType;
137
138 /* types of keyframe data in bAnimListElem */
139 typedef enum eAnim_KeyType {
140         ALE_NONE = 0,           /* no keyframe data */
141         ALE_IPO,                        /* IPO block */
142         ALE_ICU,                        /* IPO-Curve block */
143         ALE_GPFRAME,            /* Grease Pencil Frames */
144         
145         // XXX the following are for summaries... should these be kept?
146         ALE_OB,                         /* Object summary */
147         ALE_ACT,                        /* Action summary */
148         ALE_GROUP,                      /* Action Group summary */
149 } eAnim_KeyType;
150
151 /* ----------------- Filtering -------------------- */
152
153 /* filtering flags  - under what circumstances should a channel be added */
154 // XXX was ACTFILTER_*
155 typedef enum eAnimFilter_Flags {
156         ANIMFILTER_VISIBLE              = (1<<0),       /* should channels be visible */
157         ANIMFILTER_SEL                  = (1<<1),       /* should channels be selected */
158         ANIMFILTER_FOREDIT              = (1<<2),       /* does editable status matter */
159         ANIMFILTER_CHANNELS             = (1<<3),       /* do we only care that it is a channel */
160         ANIMFILTER_IPOKEYS              = (1<<4),       /* only channels referencing ipo's */
161         ANIMFILTER_ONLYFCU              = (1<<5),       /* only reference ipo-curves */
162         ANIMFILTER_FORDRAWING   = (1<<6),       /* make list for interface drawing */
163         ANIMFILTER_ACTGROUPED   = (1<<7),       /* belongs to the active actiongroup */
164 } eAnimFilter_Flags;
165
166
167 /* ---------- Flag Checking Macros ------------ */
168
169 /* Dopesheet only */
170         /* 'Object' channels */
171 #define SEL_OBJC(base) ((base->flag & SELECT))
172 #define EXPANDED_OBJC(ob) ((ob->nlaflag & OB_ADS_COLLAPSED)==0)
173         /* 'Sub-object' channels (flags stored in Object block) */
174 #define FILTER_IPO_OBJC(ob) ((ob->nlaflag & OB_ADS_SHOWIPO))
175 #define FILTER_CON_OBJC(ob) ((ob->nlaflag & OB_ADS_SHOWCONS)) 
176 #define FILTER_MAT_OBJC(ob) ((ob->nlaflag & OB_ADS_SHOWMATS))
177         /* 'Sub-object' channels (flags stored in Data block) */
178 #define FILTER_SKE_OBJD(key) ((key->flag & KEYBLOCK_DS_EXPAND))
179 #define FILTER_MAT_OBJD(ma) ((ma->flag & MA_DS_EXPAND))
180 #define FILTER_LAM_OBJD(la) ((la->flag & LA_DS_EXPAND))
181 #define FILTER_CAM_OBJD(ca) ((ca->flag & CAM_DS_EXPAND))
182 #define FILTER_CUR_OBJD(cu) ((cu->flag & CU_DS_EXPAND))
183         /* 'Sub-object/Action' channels (flags stored in Action) */
184 #define SEL_ACTC(actc) ((actc->flag & ACTC_SELECTED))
185 #define EXPANDED_ACTC(actc) ((actc->flag & ACTC_EXPANDED))
186
187 /* Actions (also used for Dopesheet) */
188         /* Action Channel Group */
189 #define EDITABLE_AGRP(agrp) ((agrp->flag & AGRP_PROTECTED)==0)
190 #define EXPANDED_AGRP(agrp) (agrp->flag & AGRP_EXPANDED)
191 #define SEL_AGRP(agrp) ((agrp->flag & AGRP_SELECTED) || (agrp->flag & AGRP_ACTIVE))
192         /* Action Channel Settings */
193 #define VISIBLE_ACHAN(achan) ((achan->flag & ACHAN_HIDDEN)==0)
194 #define EDITABLE_ACHAN(achan) ((VISIBLE_ACHAN(achan)) && ((achan->flag & ACHAN_PROTECTED)==0))
195 #define EXPANDED_ACHAN(achan) ((VISIBLE_ACHAN(achan)) && (achan->flag & ACHAN_EXPANDED))
196 #define SEL_ACHAN(achan) ((achan->flag & ACHAN_SELECTED) || (achan->flag & ACHAN_HILIGHTED))
197 #define FILTER_IPO_ACHAN(achan) ((achan->flag & ACHAN_SHOWIPO))
198 #define FILTER_CON_ACHAN(achan) ((achan->flag & ACHAN_SHOWCONS))
199         /* Constraint Channel Settings */
200 #define EDITABLE_CONCHAN(conchan) ((conchan->flag & CONSTRAINT_CHANNEL_PROTECTED)==0)
201 #define SEL_CONCHAN(conchan) (conchan->flag & CONSTRAINT_CHANNEL_SELECT)
202         /* IPO Curve Channels */
203 #define EDITABLE_ICU(icu) ((icu->flag & IPO_PROTECT)==0)
204 #define SEL_ICU(icu) (icu->flag & IPO_SELECT)
205
206 /* Grease Pencil only */
207         /* Grease Pencil datablock settings */
208 #define EXPANDED_GPD(gpd) (gpd->flag & GP_DATA_EXPAND) 
209         /* Grease Pencil Layer settings */
210 #define EDITABLE_GPL(gpl) ((gpl->flag & GP_LAYER_LOCKED)==0)
211 #define SEL_GPL(gpl) ((gpl->flag & GP_LAYER_ACTIVE) || (gpl->flag & GP_LAYER_SELECT))
212
213 /* -------------- Channel Defines -------------- */
214
215 /* channel heights */
216 #define ACHANNEL_FIRST                  -16
217 #define ACHANNEL_HEIGHT                 16
218 #define ACHANNEL_HEIGHT_HALF    8
219 #define ACHANNEL_SKIP                   2
220 #define ACHANNEL_STEP                   (ACHANNEL_HEIGHT + ACHANNEL_SKIP)
221
222 /* channel widths */
223 #define ACHANNEL_NAMEWIDTH              200
224
225 /* channel toggle-buttons */
226 #define ACHANNEL_BUTTON_WIDTH   16
227
228 /* ---------------- API  -------------------- */
229
230 /* Obtain list of filtered Animation channels to operate on.
231  * Returns the number of channels in the list
232  */
233 int ANIM_animdata_filter(ListBase *anim_data, int filter_mode, void *data, short datatype);
234
235 /* Obtain current anim-data context from Blender Context info.
236  * Returns whether the operation was successful. 
237  */
238 short ANIM_animdata_get_context(const struct bContext *C, bAnimContext *ac);
239
240 /* Obtain current anim-data context (from Animation Editor) given 
241  * that Blender Context info has already been set. 
242  * Returns whether the operation was successful.
243  */
244 short ANIM_animdata_context_getdata(bAnimContext *ac);
245
246 /* ************************************************ */
247 /* ANIMATION CHANNELS LIST */
248 /* anim_channels.c */
249
250 /* ------------------------ API -------------------------- */
251
252 /* Deselect all animation channels */
253 void ANIM_deselect_anim_channels(void *data, short datatype, short test, short sel);
254
255 /* Set the 'active' channel of type channel_type, in the given action */
256 void ANIM_action_set_active_channel(void *data, short datatype, void *channel_data, short channel_type);
257
258 /* --------------- Settings and/or Defines -------------- */
259
260 /* flag-setting behaviour */
261 enum {
262         ACHANNEL_SETFLAG_CLEAR = 0,
263         ACHANNEL_SETFLAG_ADD,
264         ACHANNEL_SETFLAG_TOGGLE
265 } eAnimChannels_SetFlag;
266
267 /* ************************************************ */
268 /* DRAWING API */
269 /* anim_draw.c */
270
271 /* ---------- Current Frame Drawing ---------------- */
272
273 /* flags for Current Frame Drawing */
274 enum {
275                 /* plain time indicator with no special indicators */
276         DRAWCFRA_PLAIN                  = 0,
277                 /* draw box indicating current frame number */
278         DRAWCFRA_SHOW_NUMBOX    = (1<<0),
279                 /* time indication in seconds or frames */
280         DRAWCFRA_UNIT_SECONDS   = (1<<1),
281                 /* show time-offset line */
282         DRAWCFRA_SHOW_TIMEOFS   = (1<<2),
283 } eAnimEditDraw_CurrentFrame; 
284
285 /* main call to draw current-frame indicator in an Animation Editor */
286 void ANIM_draw_cfra(const struct bContext *C, struct View2D *v2d, short flag);
287
288 /* ------------- Preview Range Drawing -------------- */
289
290 /* main call to draw preview range curtains */
291 void ANIM_draw_previewrange(const struct bContext *C, struct View2D *v2d);
292
293 /* ************************************************* */
294 /* ASSORTED TOOLS */
295
296 /* ------------ IPO Adrcode <-> Icons/Names Mapping ------------ */
297 /* anim_ipo_utils.c */
298
299 int geticon_ipo_blocktype(short blocktype);
300 char *getname_ipocurve(struct IpoCurve *icu, struct Object *ob);
301
302 unsigned int ipo_rainbow(int cur, int tot);
303
304
305 /* ------------- NLA-Mapping ----------------------- */
306 /* anim_draw.c */
307
308 /* Obtain the Object providing NLA-scaling for the given channel if applicable */
309 struct Object *ANIM_nla_mapping_get(bAnimContext *ac, bAnimListElem *ale);
310
311 /* Set/clear temporary mapping of coordinates from 'local-action' time to 'global-nla-scaled' time */
312 void ANIM_nla_mapping_draw(struct gla2DDrawInfo *di, struct Object *ob, short restore);
313
314 /* Apply/Unapply NLA mapping to all keyframes in the nominated IPO block */
315 void ANIM_nla_mapping_apply_ipocurve(struct Object *ob, struct IpoCurve *icu, short restore, short only_keys);
316 void ANIM_nla_mapping_apply_ipo(struct Object *ob, struct Ipo *ipo, short restore, short only_keys);
317
318 /* ------------- xxx macros ----------------------- */
319
320 #define BEZSELECTED(bezt) ((bezt->f2 & SELECT) || (bezt->f1 & SELECT) || (bezt->f3 & SELECT))
321
322
323 /* --------- anim_deps.c, animation updates -------- */
324
325         /* generic update flush, reads from Context screen (layers) and scene */
326 void ED_anim_dag_flush_update(const struct bContext *C);
327         /* only flush object */
328 void ED_anim_object_flush_update(const struct bContext *C, struct Object *ob);
329         /* flush + do the actual update for all involved objects */
330 void ED_update_for_newframe(const struct bContext *C, int mute);
331
332 /* pose <-> action syncing */
333 void ANIM_action_to_pose_sync(struct Object *ob);
334 void ANIM_pose_to_action_sync(struct Object *ob, struct ScrArea *sa);
335
336
337 /* what types of animation data was changed (for sending notifiers from animation tools) */
338 enum {
339         ANIM_CHANGED_BOTH= 0,
340         ANIM_CHANGED_KEYFRAMES_VALUES,
341         ANIM_CHANGED_KEYFRAMES_SELECT,
342         ANIM_CHANGED_CHANNELS
343 } eAnimData_Changed;
344
345 /* Send notifiers on behalf of animation editing tools, based on various context info */
346 void ANIM_animdata_send_notifiers(struct bContext *C, bAnimContext *ac, short data_changed);
347
348 /* ************************************************* */
349 /* OPERATORS */
350         
351         /* generic animation channels */
352 void ED_operatortypes_animchannels(void);
353 void ED_keymap_animchannels(struct wmWindowManager *wm);
354
355         /* generic time editing */
356 void ED_operatortypes_anim(void);
357 void ED_keymap_anim(struct wmWindowManager *wm);
358
359 /* ************************************************ */
360
361 #endif /* ED_ANIM_API_H */
362