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