source/blender/editors/include/ED_keyframing.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  * This is a new part of Blender (with some old code)
  20  *
  21  * Contributor(s): Joshua Leung
  22  *
  23  * ***** END GPL LICENSE BLOCK *****
  24  */
  25
  26 /** \file ED_keyframing.h
  27  *  \ingroup editors
  28  */
  29
  30 #ifndef __ED_KEYFRAMING_H__
  31 #define __ED_KEYFRAMING_H__
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 struct Main;
  38 struct ListBase;
  39 struct ID;
  40 struct Scene;
  41
  42 struct KeyingSet;
  43
  44 struct bAction;
  45 struct FCurve;
  46 struct BezTriple;
  47
  48 struct bPoseChannel;
  49 struct bConstraint;
  50
  51 struct bContext;
  52 struct wmOperatorType;
  53 struct ReportList;
  54
  55 struct PointerRNA;
  56 struct PropertyRNA;
  57 struct EnumPropertyItem;
  58
  59 #include "RNA_types.h"
  60
  61 /* ************ Keyframing Management **************** */
  62
  63 /* Get the active settings for keyframing settings from context (specifically the given scene)
  64  *      - incl_mode: include settings from keyframing mode in the result (i.e. replace only)
  65  */
  66 short ANIM_get_keyframing_flags(struct Scene *scene, short incl_mode);
  67
  68 /* -------- */
  69
  70 /* Get (or add relevant data to be able to do so) the Active Action for the given
  71  * Animation Data block, given an ID block where the Animation Data should reside.
  72  */
  73 struct bAction *verify_adt_action(struct ID *id, short add);
  74
  75 /* Get (or add relevant data to be able to do so) F-Curve from the given Action.
  76  * This assumes that all the destinations are valid.
  77  */
  78 struct FCurve *verify_fcurve(struct bAction *act, const char group[], struct PointerRNA *ptr,
  79                              const char rna_path[], const int array_index, short add);
  80
  81 /* -------- */
  82
  83 /* Lesser Keyframing API call:
  84  *  Update integer/discrete flags of the FCurve (used when creating/inserting keyframes,
  85  *  but also through RNA when editing an ID prop, see T37103).
  86  */
  87 void update_autoflags_fcurve(struct FCurve *fcu, struct bContext *C, struct ReportList *reports,
  88                              struct PointerRNA *ptr);
  89
  90 /* -------- */
  91
  92 /* Lesser Keyframing API call:
  93  *  Use this when validation of necessary animation data isn't necessary as it already
  94  *  exists, and there is a beztriple that can be directly copied into the array.
  95  */
  96 int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt, short flag);
  97
  98 /* Main Keyframing API call:
  99  *  Use this when validation of necessary animation data isn't necessary as it
 100  *  already exists. It will insert a keyframe using the current value being keyframed.
 101  *  Returns the index at which a keyframe was added (or -1 if failed)
 102  */
 103 int insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
 104
 105 /* -------- */
 106
 107 /* Secondary Keyframing API calls:
 108  *      Use this to insert a keyframe using the current value being keyframed, in the
 109  *      nominated F-Curve (no creation of animation data performed). Returns success.
 110  */
 111 short insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
 112
 113 /* -------- */
 114
 115 /* Main Keyframing API calls:
 116  *      Use this to create any necessary animation data, and then insert a keyframe
 117  *      using the current value being keyframed, in the relevant place. Returns success.
 118  */
 119 short insert_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
 120
 121 /* Main Keyframing API call:
 122  *  Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
 123  */
 124 short delete_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
 125
 126 /* ************ Keying Sets ********************** */
 127
 128 /* forward decl. for this struct which is declared a bit later... */
 129 struct KeyingSetInfo;
 130 struct ExtensionRNA;
 131
 132 /* Polling Callback for KeyingSets */
 133 typedef int (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C);
 134 /* Context Iterator Callback for KeyingSets */
 135 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks);
 136 /* Property Specifier Callback for KeyingSets (called from iterators) */
 137 typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks, struct PointerRNA *ptr);
 138
 139
 140 /* Callback info for 'Procedural' KeyingSets to use */
 141 typedef struct KeyingSetInfo {
 142         struct KeyingSetInfo *next, *prev;
 143
 144         /* info */
 145         /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
 146         char idname[64];
 147         /* identifier so that user can hook this up to a KeyingSet (used as label). */
 148         char name[64];
 149         /* short help/description. */
 150         char description[240]; /* RNA_DYN_DESCR_MAX */
 151         /* keying settings */
 152         short keyingflag;
 153
 154         /* polling callbacks */
 155         /* callback for polling the context for whether the right data is available */
 156         cbKeyingSet_Poll poll;
 157
 158         /* generate callbacks */
 159         /* iterator to use to go through collections of data in context
 160          *  - this callback is separate from the 'adding' stage, allowing
 161          *    BuiltIn KeyingSets to be manually specified to use
 162          */
 163         cbKeyingSet_Iterator iter;
 164         /* generator to use to add properties based on the data found by iterator */
 165         cbKeyingSet_Generate generate;
 166
 167         /* RNA integration */
 168         struct ExtensionRNA ext;
 169 } KeyingSetInfo;
 170
 171 /* -------- */
 172
 173 /* Add another data source for Relative Keying Sets to be evaluated with */
 174 void ANIM_relative_keyingset_add_source(ListBase *dsources, struct ID *id, struct StructRNA *srna, void *data);
 175
 176
 177 /* mode for modify_keyframes */
 178 typedef enum eModifyKey_Modes {
 179         MODIFYKEY_MODE_INSERT = 0,
 180         MODIFYKEY_MODE_DELETE,
 181 } eModifyKey_Modes;
 182
 183 /* return codes for errors (with Relative KeyingSets) */
 184 typedef enum eModifyKey_Returns {
 185         /* context info was invalid for using the Keying Set */
 186         MODIFYKEY_INVALID_CONTEXT = -1,
 187         /* there isn't any typeinfo for generating paths from context */
 188         MODIFYKEY_MISSING_TYPEINFO = -2,
 189 } eModifyKey_Returns;
 190
 191 /* poll the current KeyingSet, updating it's set of paths (if "builtin"/"relative") for context changes */
 192 short ANIM_validate_keyingset(struct bContext *C, ListBase *dsources, struct KeyingSet *ks);
 193
 194 /* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
 195 int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
 196
 197 /* -------- */
 198
 199 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
 200 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
 201
 202 /* Find KeyingSet type info given a name */
 203 KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]);
 204
 205 /* for RNA type registrations... */
 206 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
 207 void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi);
 208
 209 /* cleanup on exit */
 210 void ANIM_keyingset_infos_exit(void);
 211
 212 /* -------- */
 213
 214 /* Get the active KeyingSet for the given scene */
 215 struct KeyingSet *ANIM_scene_get_active_keyingset(struct Scene *scene);
 216
 217 /* Get the index of the Keying Set provided, for the given Scene */
 218 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
 219
 220 /* Get Keying Set to use for Auto-Keyframing some transforms */
 221 struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene, const char *tranformKSName);
 222
 223 /* Dynamically populate an enum of Keying Sets */
 224 struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, bool *r_free);
 225
 226 /* Check if KeyingSet can be used in the current context */
 227 short ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
 228
 229 /* ************ Drivers ********************** */
 230
 231 /* Flags for use by driver creation calls */
 232 typedef enum eCreateDriverFlags {
 233         CREATEDRIVER_WITH_DEFAULT_DVAR  = (1 << 0),   /* create drivers with a default variable for nicer UI */
 234         CREATEDRIVER_WITH_FMODIFIER     = (1 << 1),   /* create drivers with Generator FModifier (for backwards compat) */
 235 } eCreateDriverFlags;
 236
 237 /* -------- */
 238
 239 /* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools,
 240  * although there are special cases where this approach is preferable.
 241  */
 242 struct FCurve *verify_driver_fcurve(struct ID *id, const char rna_path[], const int array_index, short add);
 243
 244 /* -------- */
 245
 246 /* Returns whether there is a driver in the copy/paste buffer to paste */
 247 short ANIM_driver_can_paste(void);
 248
 249 /* Main Driver Management API calls:
 250  *  Add a new driver for the specified property on the given ID block
 251  */
 252 short ANIM_add_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag, int type);
 253
 254 /* Main Driver Management API calls:
 255  *  Remove the driver for the specified property on the given ID block (if available)
 256  */
 257 short ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 258
 259 /* Main Driver Management API calls:
 260  *  Make a copy of the driver for the specified property on the given ID block
 261  */
 262 short ANIM_copy_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 263
 264 /* Main Driver Management API calls:
 265  *  Add a new driver for the specified property on the given ID block or replace an existing one
 266  *      with the driver + driver-curve data from the buffer
 267  */
 268 short ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 269
 270 /* ************ Auto-Keyframing ********************** */
 271 /* Notes:
 272  * - All the defines for this (User-Pref settings and Per-Scene settings)
 273  *  are defined in DNA_userdef_types.h
 274  * - Scene settings take presidence over those for userprefs, with old files
 275  *  inheriting userpref settings for the scene settings
 276  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
 277  *  as userprefs
 278  */
 279
 280 /* Auto-Keying macros for use by various tools */
 281 /* check if auto-keyframing is enabled (per scene takes presidence) */
 282 #define IS_AUTOKEY_ON(scene)  ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
 283 /* check the mode for auto-keyframing (per scene takes presidence)  */
 284 #define IS_AUTOKEY_MODE(scene, mode)  ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
 285 /* check if a flag is set for auto-keyframing (per scene takes presidence) */
 286 #define IS_AUTOKEY_FLAG(scene, flag) \
 287         ((scene) ? \
 288                 ((scene->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || (U.autokey_flag & AUTOKEY_FLAG_##flag)) \
 289          : \
 290                 (U.autokey_flag & AUTOKEY_FLAG_##flag))
 291
 292 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
 293 int autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
 294
 295 /* ************ Keyframe Checking ******************** */
 296
 297 /* Lesser Keyframe Checking API call:
 298  *      - Used for the buttons to check for keyframes...
 299  */
 300 bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
 301
 302 /* Main Keyframe Checking API call:
 303  * Checks whether a keyframe exists for the given ID-block one the given frame.
 304  *  - It is recommended to call this method over the other keyframe-checkers directly,
 305  *    in case some detail of the implementation changes...
 306  *      - frame: the value of this is quite often result of BKE_scene_frame_get()
 307  */
 308 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
 309
 310 /* filter flags for id_cfra_has_keyframe
 311  *
 312  * WARNING: do not alter order of these, as also stored in files
 313  *      (for v3d->keyflags)
 314  */
 315 typedef enum eAnimFilterFlags {
 316         /* general */
 317         ANIMFILTER_KEYS_LOCAL   = (1 << 0),       /* only include locally available anim data */
 318         ANIMFILTER_KEYS_MUTED   = (1 << 1),       /* include muted elements */
 319         ANIMFILTER_KEYS_ACTIVE  = (1 << 2),       /* only include active-subelements */
 320
 321         /* object specific */
 322         ANIMFILTER_KEYS_NOMAT   = (1 << 9),   /* don't include material keyframes */
 323         ANIMFILTER_KEYS_NOSKEY  = (1 << 10),  /* don't include shape keys (for geometry) */
 324 } eAnimFilterFlags;
 325
 326 /* utility funcs for auto keyframe */
 327 int ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, struct KeyingSet *ks);
 328 int ED_autokeyframe_pchan(struct bContext *C, struct Scene *scene, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks);
 329
 330 /* Names for builtin keying sets so we don't confuse these with labels/text,
 331  * defined in python script: keyingsets_builtins.py */
 332 #define ANIM_KS_LOCATION_ID         "Location"
 333 #define ANIM_KS_ROTATION_ID         "Rotation"
 334 #define ANIM_KS_SCALING_ID          "Scaling"
 335 #define ANIM_KS_LOC_ROT_SCALE_ID    "LocRotScale"
 336 #define ANIM_KS_AVAILABLE_ID        "Available"
 337 #define ANIM_KS_WHOLE_CHARACTER_ID  "WholeCharacter"
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif
 342
 343 #endif /*  __ED_KEYFRAMING_H__ */