Blender V2.61 - r43446

ED_keyframes_edit.h

Go to the documentation of this file.
00001 /*
00002  * ***** BEGIN GPL LICENSE BLOCK *****
00003  *
00004  * This program is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU General Public License
00006  * as published by the Free Software Foundation; either version 2
00007  * of the License, or (at your option) any later version. 
00008  *
00009  * This program is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  * GNU General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU General Public License
00015  * along with this program; if not, write to the Free Software Foundation,
00016  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00017  *
00018  * The Original Code is Copyright (C) 2008 Blender Foundation.
00019  * All rights reserved.
00020  *
00021  * 
00022  * Contributor(s): Joshua Leung
00023  *
00024  * ***** END GPL LICENSE BLOCK *****
00025  */
00026 
00031 #ifndef ED_KEYFRAMES_EDIT_H
00032 #define ED_KEYFRAMES_EDIT_H
00033 
00034 struct bAnimContext;
00035 struct bAnimListElem;
00036 struct bDopeSheet;
00037 struct FCurve;
00038 struct BezTriple;
00039 struct Scene;
00040 
00041 /* ************************************************ */
00042 /* Common Macros and Defines */
00043 
00044 /* --------- BezTriple Selection ------------- */
00045 
00046 #define BEZ_SEL(bezt)       { (bezt)->f1 |=  SELECT; (bezt)->f2 |=  SELECT; (bezt)->f3 |=  SELECT; }
00047 #define BEZ_DESEL(bezt)     { (bezt)->f1 &= ~SELECT; (bezt)->f2 &= ~SELECT; (bezt)->f3 &= ~SELECT; }
00048 #define BEZ_INVSEL(bezt)    { (bezt)->f1 ^=  SELECT; (bezt)->f2 ^=  SELECT; (bezt)->f3 ^=  SELECT; }
00049 
00050 /* --------- Tool Flags ------------ */
00051 
00052 /* bezt validation */
00053 typedef enum eEditKeyframes_Validate {
00054     BEZT_OK_FRAME   = 1,
00055     BEZT_OK_FRAMERANGE,
00056     BEZT_OK_SELECTED,
00057     BEZT_OK_VALUE,
00058     BEZT_OK_VALUERANGE,
00059     BEZT_OK_REGION
00060 } eEditKeyframes_Validate;
00061 
00062 /* ------------ */
00063 
00064 /* select modes */
00065 typedef enum eEditKeyframes_Select {
00066         /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
00067     SELECT_REPLACE  =   (1<<0),
00068         /* add ok keyframes to selection */
00069     SELECT_ADD      =   (1<<1),
00070         /* remove ok keyframes from selection */
00071     SELECT_SUBTRACT =   (1<<2),
00072         /* flip ok status of keyframes based on key status */
00073     SELECT_INVERT   =   (1<<3)
00074 } eEditKeyframes_Select;
00075 
00076 /* "selection map" building modes */
00077 typedef enum eEditKeyframes_SelMap {
00078     SELMAP_MORE = 0,
00079     SELMAP_LESS
00080 } eEditKeyframes_SelMap;
00081 
00082 /* snapping tools */
00083 typedef enum eEditKeyframes_Snap {
00084     SNAP_KEYS_CURFRAME = 1,
00085     SNAP_KEYS_NEARFRAME,
00086     SNAP_KEYS_NEARSEC,
00087     SNAP_KEYS_NEARMARKER,
00088     SNAP_KEYS_HORIZONTAL,
00089     SNAP_KEYS_VALUE
00090 } eEditKeyframes_Snap;
00091 
00092 /* mirroring tools */
00093 typedef enum eEditKeyframes_Mirror {
00094     MIRROR_KEYS_CURFRAME = 1,
00095     MIRROR_KEYS_YAXIS,
00096     MIRROR_KEYS_XAXIS,
00097     MIRROR_KEYS_MARKER,
00098     MIRROR_KEYS_VALUE
00099 } eEditKeyframes_Mirror;
00100 
00101 /* ************************************************ */
00102 /* Non-Destuctive Editing API (keyframes_edit.c) */
00103 
00104 /* --- Generic Properties for Keyframe Edit Tools ----- */
00105 
00106 typedef struct KeyframeEditData {
00107         /* generic properties/data access */
00108     ListBase list;              /* temp list for storing custom list of data to check */
00109     struct Scene *scene;        /* pointer to current scene - many tools need access to cfra/etc.  */
00110     void *data;                 /* pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
00111     float f1, f2;               /* storage of times/values as 'decimals' */
00112     int i1, i2;                 /* storage of times/values/flags as 'whole' numbers */
00113     
00114         /* current iteration data */
00115     struct FCurve *fcu;         /* F-Curve that is being iterated over */
00116     int curIndex;               /* index of current keyframe being iterated over */
00117     
00118         /* flags */
00119     short curflags;             /* current flags for the keyframe we're reached in the iteration process */
00120     short iterflags;            /* settings for iteration process */ // XXX: unused...
00121 } KeyframeEditData;
00122 
00123 /* ------- Function Pointer Typedefs ---------------- */
00124 
00125     /* callback function that refreshes the F-Curve after use */
00126 typedef void (*FcuEditFunc)(struct FCurve *fcu);
00127     /* callback function that operates on the given BezTriple */
00128 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
00129 
00130 /* ---------- Defines for 'OK' polls ----------------- */
00131 
00132 /* which verts of a keyframe is active (after polling) */
00133 typedef enum eKeyframeVertOk {
00134         /* 'key' itself is ok */
00135     KEYFRAME_OK_KEY     = (1<<0),
00136         /* 'handle 1' is ok */
00137     KEYFRAME_OK_H1      = (1<<1),
00138         /* 'handle 2' is ok */
00139     KEYFRAME_OK_H2      = (1<<2),
00140         /* all flags */
00141     KEYFRAME_OK_ALL     = (KEYFRAME_OK_KEY|KEYFRAME_OK_H1|KEYFRAME_OK_H2)
00142 } eKeyframeVertOk;
00143 
00144 /* Flags for use during iteration */
00145 typedef enum eKeyframeIterFlags {
00146         /* consider handles in addition to key itself */
00147     KEYFRAME_ITER_INCL_HANDLES  = (1<<0),
00148 } eKeyframeIterFlags;   
00149 
00150 /* ------- Custom Data Type Defines ------------------ */
00151 
00152 /* Custom data for remapping one range to another in a fixed way */
00153 typedef struct KeyframeEditCD_Remap {
00154     float oldMin, oldMax;           /* old range */
00155     float newMin, newMax;           /* new range */
00156 } KeyframeEditCD_Remap;
00157 
00158 /* Paste options */
00159 typedef enum eKeyPasteOffset {
00160         /* paste keys starting at current frame */
00161     KEYFRAME_PASTE_OFFSET_CFRA_START,
00162         /* paste keys ending at current frame */
00163     KEYFRAME_PASTE_OFFSET_CFRA_END,
00164         /* paste keys relative to the current frame when copying */
00165     KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
00166         /* paste keys from original time */
00167     KEYFRAME_PASTE_OFFSET_NONE
00168 } eKeyPasteOffset;
00169 
00170 typedef enum eKeyMergeMode {
00171         /* overlay existing with new keys */
00172     KEYFRAME_PASTE_MERGE_MIX,
00173         /* replace entire fcurve */
00174     KEYFRAME_PASTE_MERGE_OVER,
00175         /* overwrite keys in pasted range */
00176     KEYFRAME_PASTE_MERGE_OVER_RANGE,
00177         /* overwrite keys in pasted range (use all keyframe start & end for range) */
00178     KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL
00179 } eKeyMergeMode;
00180 
00181 /* ---------------- Looping API --------------------- */
00182 
00183 /* functions for looping over keyframes */
00184     /* function for working with F-Curve data only (i.e. when filters have been chosen to explicitly use this) */
00185 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
00186     /* function for working with any type (i.e. one of the known types) of animation channel 
00187      *  - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
00188      */
00189 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, struct bAnimListElem *ale, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
00190     /* same as above, except bAnimListElem wrapper is not needed... 
00191      *  - keytype is eAnim_KeyType
00192      */
00193 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, void *data, int keytype, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
00194 
00195 /* functions for making sure all keyframes are in good order */
00196 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
00197 
00198 /* ----------- BezTriple Callback Getters ---------- */
00199 
00200 /* accessories */
00201 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
00202 
00203 /* edit */
00204 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
00205 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
00206 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
00207 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
00208 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
00209 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
00210 
00211 /* -------- BezTriple Callbacks (Selection Map) ---------- */
00212 
00213 /* Get a callback to populate the selection settings map  
00214  * requires: ked->custom = char[] of length fcurve->totvert 
00215  */
00216 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
00217 
00218 /* Change the selection status of the keyframe based on the map entry for this vert
00219  * requires: ked->custom = char[] of length fcurve->totvert
00220  */
00221 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
00222 
00223 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
00224 
00225 /* used to calculate the the average location of all relevant BezTriples by summing their locations */
00226 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
00227 
00228 /* used to extract a set of cfra-elems from the keyframes */
00229 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
00230 
00231 /* used to remap times from one range to another
00232  * requires:  ked->custom = KeyframeEditCD_Remap    
00233  */
00234 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
00235 
00236 /* ************************************************ */
00237 /* Destructive Editing API (keyframes_general.c) */
00238 
00239 void delete_fcurve_key(struct FCurve *fcu, int index, short do_recalc);
00240 void delete_fcurve_keys(struct FCurve *fcu);
00241 void clear_fcurve_keys(struct FCurve *fcu);
00242 void duplicate_fcurve_keys(struct FCurve *fcu);
00243 
00244 void clean_fcurve(struct FCurve *fcu, float thresh);
00245 void smooth_fcurve(struct FCurve *fcu);
00246 void sample_fcurve(struct FCurve *fcu);
00247 
00248 /* ----------- */
00249 
00250 void free_anim_copybuf(void);
00251 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
00252 short paste_animedit_keys(struct bAnimContext *ac, ListBase *anim_data,
00253     const eKeyPasteOffset offset_mode, const eKeyMergeMode merge_mode);
00254 
00255 /* ************************************************ */
00256 
00257 #endif /* ED_KEYFRAMES_EDIT_H */