source/blender/editors/include/ED_keyframes_edit.h

   1 /*
   2  * ***** BEGIN GPL LICENSE BLOCK *****
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * The Original Code is Copyright (C) 2008 Blender Foundation.
  19  * All rights reserved.
  20  *
  21  *
  22  * Contributor(s): Joshua Leung
  23  *
  24  * ***** END GPL LICENSE BLOCK *****
  25  */
  26
  27 /** \file ED_keyframes_edit.h
  28  *  \ingroup editors
  29  */
  30
  31 #ifndef __ED_KEYFRAMES_EDIT_H__
  32 #define __ED_KEYFRAMES_EDIT_H__
  33
  34 struct bAnimContext;
  35 struct bAnimListElem;
  36 struct bDopeSheet;
  37 struct FCurve;
  38 struct BezTriple;
  39 struct Scene;
  40
  41 /* ************************************************ */
  42 /* Common Macros and Defines */
  43
  44 /* --------- Tool Flags ------------ */
  45
  46 /* bezt validation */
  47 typedef enum eEditKeyframes_Validate {
  48         /* Frame range */
  49         BEZT_OK_FRAME = 1,
  50         BEZT_OK_FRAMERANGE,
  51         /* Selection status */
  52         BEZT_OK_SELECTED,
  53         /* Values (y-val) only */
  54         BEZT_OK_VALUE,
  55         BEZT_OK_VALUERANGE,
  56         /* For graph editor keyframes (2D tests) */
  57         BEZT_OK_REGION,
  58         BEZT_OK_REGION_LASSO,
  59         BEZT_OK_REGION_CIRCLE,
  60         /* Only for keyframes a certain Dopesheet channel */
  61         BEZT_OK_CHANNEL_LASSO,
  62         BEZT_OK_CHANNEL_CIRCLE,
  63 } eEditKeyframes_Validate;
  64
  65 /* ------------ */
  66
  67 /* select modes */
  68 typedef enum eEditKeyframes_Select {
  69         /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
  70         SELECT_REPLACE  =   (1 << 0),
  71         /* add ok keyframes to selection */
  72         SELECT_ADD      =   (1 << 1),
  73         /* remove ok keyframes from selection */
  74         SELECT_SUBTRACT =   (1 << 2),
  75         /* flip ok status of keyframes based on key status */
  76         SELECT_INVERT   =   (1 << 3)
  77 } eEditKeyframes_Select;
  78
  79 /* "selection map" building modes */
  80 typedef enum eEditKeyframes_SelMap {
  81         SELMAP_MORE = 0,
  82         SELMAP_LESS
  83 } eEditKeyframes_SelMap;
  84
  85 /* snapping tools */
  86 typedef enum eEditKeyframes_Snap {
  87         SNAP_KEYS_CURFRAME = 1,
  88         SNAP_KEYS_NEARFRAME,
  89         SNAP_KEYS_NEARSEC,
  90         SNAP_KEYS_NEARMARKER,
  91         SNAP_KEYS_HORIZONTAL,
  92         SNAP_KEYS_VALUE,
  93         SNAP_KEYS_TIME,
  94 } eEditKeyframes_Snap;
  95
  96 /* mirroring tools */
  97 typedef enum eEditKeyframes_Mirror {
  98         MIRROR_KEYS_CURFRAME = 1,
  99         MIRROR_KEYS_YAXIS,
 100         MIRROR_KEYS_XAXIS,
 101         MIRROR_KEYS_MARKER,
 102         MIRROR_KEYS_VALUE,
 103         MIRROR_KEYS_TIME,
 104 } eEditKeyframes_Mirror;
 105
 106 /* use with BEZT_OK_REGION_LASSO */
 107 typedef struct KeyframeEdit_LassoData {
 108         rctf *rectf_scaled;
 109         const rctf *rectf_view;
 110         const int (*mcords)[2];
 111         int mcords_tot;
 112 } KeyframeEdit_LassoData;
 113
 114 /* use with BEZT_OK_REGION_CIRCLE */
 115 typedef struct KeyframeEdit_CircleData {
 116         rctf *rectf_scaled;
 117         const rctf *rectf_view;
 118         float mval[2];
 119         float radius_squared;
 120 } KeyframeEdit_CircleData;
 121
 122
 123 /* ************************************************ */
 124 /* Non-Destuctive Editing API (keyframes_edit.c) */
 125
 126 /* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */
 127
 128 /* which verts of a keyframe is active (after polling) */
 129 typedef enum eKeyframeVertOk {
 130         /* 'key' itself is ok */
 131         KEYFRAME_OK_KEY     = (1 << 0),
 132         /* 'handle 1' is ok */
 133         KEYFRAME_OK_H1      = (1 << 1),
 134         /* 'handle 2' is ok */
 135         KEYFRAME_OK_H2      = (1 << 2),
 136         /* all flags */
 137         KEYFRAME_OK_ALL     = (KEYFRAME_OK_KEY | KEYFRAME_OK_H1 | KEYFRAME_OK_H2)
 138 } eKeyframeVertOk;
 139
 140 /* Flags for use during iteration */
 141 typedef enum eKeyframeIterFlags {
 142         /* consider handles in addition to key itself */
 143         KEYFRAME_ITER_INCL_HANDLES  = (1 << 0),
 144
 145         /* Perform NLA time remapping (global -> strip) for the "f1" parameter
 146          * (e.g. used for selection tools on summary tracks)
 147          */
 148         KED_F1_NLA_UNMAP            = (1 << 1),
 149
 150         /* Perform NLA time remapping (global -> strip) for the "f2" parameter */
 151         KED_F2_NLA_UNMAP            = (1 << 2),
 152 } eKeyframeIterFlags;
 153
 154 /* --- Generic Properties for Keyframe Edit Tools ----- */
 155
 156 typedef struct KeyframeEditData {
 157         /* generic properties/data access */
 158         ListBase list;              /* temp list for storing custom list of data to check */
 159         struct Scene *scene;        /* pointer to current scene - many tools need access to cfra/etc.  */
 160         void *data;                 /* pointer to custom data - usually 'Object' but also 'rectf', but could be other types too */
 161         float f1, f2;               /* storage of times/values as 'decimals' */
 162         int i1, i2;                 /* storage of times/values/flags as 'whole' numbers */
 163
 164         /* current iteration data */
 165         struct FCurve *fcu;         /* F-Curve that is being iterated over */
 166         int curIndex;               /* index of current keyframe being iterated over */
 167         float channel_y;            /* y-position of midpoint of the channel (for the dopesheet) */
 168
 169         /* flags */
 170         eKeyframeVertOk curflags;        /* current flags for the keyframe we're reached in the iteration process */
 171         eKeyframeIterFlags iterflags;    /* settings for iteration process */
 172 } KeyframeEditData;
 173
 174 /* ------- Function Pointer Typedefs ---------------- */
 175
 176 /* callback function that refreshes the F-Curve after use */
 177 typedef void (*FcuEditFunc)(struct FCurve *fcu);
 178 /* callback function that operates on the given BezTriple */
 179 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
 180
 181
 182 /* ------- Custom Data Type Defines ------------------ */
 183
 184 /* Custom data for remapping one range to another in a fixed way */
 185 typedef struct KeyframeEditCD_Remap {
 186         float oldMin, oldMax;           /* old range */
 187         float newMin, newMax;           /* new range */
 188 } KeyframeEditCD_Remap;
 189
 190 /* Paste options */
 191 typedef enum eKeyPasteOffset {
 192         /* paste keys starting at current frame */
 193         KEYFRAME_PASTE_OFFSET_CFRA_START,
 194         /* paste keys ending at current frame */
 195         KEYFRAME_PASTE_OFFSET_CFRA_END,
 196         /* paste keys relative to the current frame when copying */
 197         KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
 198         /* paste keys from original time */
 199         KEYFRAME_PASTE_OFFSET_NONE
 200 } eKeyPasteOffset;
 201
 202 typedef enum eKeyMergeMode {
 203         /* overlay existing with new keys */
 204         KEYFRAME_PASTE_MERGE_MIX,
 205         /* replace entire fcurve */
 206         KEYFRAME_PASTE_MERGE_OVER,
 207         /* overwrite keys in pasted range */
 208         KEYFRAME_PASTE_MERGE_OVER_RANGE,
 209         /* overwrite keys in pasted range (use all keyframe start & end for range) */
 210         KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL
 211 } eKeyMergeMode;
 212
 213 /* ---------------- Looping API --------------------- */
 214
 215 /* functions for looping over keyframes */
 216 /* function for working with F-Curve data only (i.e. when filters have been chosen to explicitly use this) */
 217 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
 218 /* function for working with any type (i.e. one of the known types) of animation channel
 219  *  - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
 220  */
 221 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, struct bAnimListElem *ale, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
 222 /* same as above, except bAnimListElem wrapper is not needed...
 223  *  - keytype is eAnim_KeyType
 224  */
 225 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, void *data, int keytype, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb);
 226
 227 /* functions for making sure all keyframes are in good order */
 228 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
 229
 230 /* ----------- BezTriple Callback Getters ---------- */
 231
 232 /* accessories */
 233 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
 234
 235 /* edit */
 236 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
 237 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
 238 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
 239 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
 240 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
 241 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
 242 KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
 243
 244 /* -------- BezTriple Callbacks (Selection Map) ---------- */
 245
 246 /* Get a callback to populate the selection settings map
 247  * requires: ked->custom = char[] of length fcurve->totvert
 248  */
 249 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
 250
 251 /* Change the selection status of the keyframe based on the map entry for this vert
 252  * requires: ked->custom = char[] of length fcurve->totvert
 253  */
 254 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
 255
 256 /* ----------- BezTriple Callback (Assorted Utilities) ---------- */
 257
 258 /* used to calculate the average location of all relevant BezTriples by summing their locations */
 259 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
 260
 261 /* used to extract a set of cfra-elems from the keyframes */
 262 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
 263
 264 /* used to remap times from one range to another
 265  * requires:  ked->custom = KeyframeEditCD_Remap
 266  */
 267 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
 268
 269 /* ------ 1.5-D Region Testing Uitls (Lasso/Circle Select) ------- */
 270 /* XXX: These are temporary, until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
 271
 272 bool keyframe_region_lasso_test(
 273         const KeyframeEdit_LassoData *data_lasso,
 274         const float xy[2]);
 275
 276 bool keyframe_region_circle_test(
 277         const KeyframeEdit_CircleData *data_circle,
 278         const float xy[2]);
 279
 280
 281 /* ************************************************ */
 282 /* Destructive Editing API (keyframes_general.c) */
 283
 284 void delete_fcurve_key(struct FCurve *fcu, int index, bool do_recalc);
 285 bool delete_fcurve_keys(struct FCurve *fcu);
 286 void clear_fcurve_keys(struct FCurve *fcu);
 287 void duplicate_fcurve_keys(struct FCurve *fcu);
 288
 289 void clean_fcurve(struct bAnimContext *ac, struct bAnimListElem *ale, float thresh, bool cleardefault);
 290 void smooth_fcurve(struct FCurve *fcu);
 291 void sample_fcurve(struct FCurve *fcu);
 292
 293 /* ----------- */
 294
 295 void ANIM_fcurves_copybuf_free(void);
 296 short copy_animedit_keys(struct bAnimContext *ac, ListBase *anim_data);
 297 short paste_animedit_keys(struct bAnimContext *ac, ListBase *anim_data,
 298                           const eKeyPasteOffset offset_mode, const eKeyMergeMode merge_mode, bool flip);
 299
 300 /* ************************************************ */
 301
 302 #endif /* __ED_KEYFRAMES_EDIT_H__ */