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