source/blender/editors/include/ED_keyframes_edit.h

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