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 * This is a new part of Blender (with some old code) 18 */ 19 20 /** \file 21 * \ingroup editors 22 */ 23 24 #pragma once 25 26 #include "DNA_anim_types.h" 27 #include "RNA_types.h" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 struct ID; 34 struct ListBase; 35 struct Main; 36 struct Scene; 37 38 struct KeyingSet; 39 40 struct AnimationEvalContext; 41 struct BezTriple; 42 struct FCurve; 43 struct bAction; 44 45 struct bPoseChannel; 46 47 struct ReportList; 48 struct bContext; 49 50 struct EnumPropertyItem; 51 struct PointerRNA; 52 struct PropertyRNA; 53 54 struct NlaKeyframingContext; 55 56 /* ************ Keyframing Management **************** */ 57 58 /* Get the active settings for keyframing settings from context (specifically the given scene) 59 * - use_autokey_mode: include settings from keyframing mode in the result (i.e. replace only). 60 */ 61 eInsertKeyFlags ANIM_get_keyframing_flags(struct Scene *scene, const bool use_autokey_mode); 62 63 /* -------- */ 64 65 /* Get (or add relevant data to be able to do so) the Active Action for the given 66 * Animation Data block, given an ID block where the Animation Data should reside. 67 */ 68 struct bAction *ED_id_action_ensure(struct Main *bmain, struct ID *id); 69 70 /* Get (or add relevant data to be able to do so) F-Curve from the given Action. 71 * This assumes that all the destinations are valid. 72 */ 73 struct FCurve *ED_action_fcurve_ensure(struct Main *bmain, 74 struct bAction *act, 75 const char group[], 76 struct PointerRNA *ptr, 77 const char rna_path[], 78 const int array_index); 79 80 struct FCurve *ED_action_fcurve_find(struct bAction *act, 81 const char rna_path[], 82 const int array_index); 83 84 /* -------- */ 85 86 /* Lesser Keyframing API call: 87 * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes, 88 * but also through RNA when editing an ID prop, see T37103). 89 */ 90 void update_autoflags_fcurve(struct FCurve *fcu, 91 struct bContext *C, 92 struct ReportList *reports, 93 struct PointerRNA *ptr); 94 95 /* -------- */ 96 97 /* Lesser Keyframing API call: 98 * Use this when validation of necessary animation data isn't necessary as it already 99 * exists, and there is a beztriple that can be directly copied into the array. 100 */ 101 int insert_bezt_fcurve(struct FCurve *fcu, const struct BezTriple *bezt, eInsertKeyFlags flag); 102 103 /* Main Keyframing API call: 104 * Use this when validation of necessary animation data isn't necessary as it 105 * already exists. It will insert a keyframe using the current value being keyframed. 106 * Returns the index at which a keyframe was added (or -1 if failed) 107 */ 108 int insert_vert_fcurve(struct FCurve *fcu, 109 float x, 110 float y, 111 eBezTriple_KeyframeType keyframe_type, 112 eInsertKeyFlags flag); 113 114 /* -------- */ 115 116 /* Secondary Keyframing API calls: 117 * Use this to insert a keyframe using the current value being keyframed, in the 118 * nominated F-Curve (no creation of animation data performed). Returns success. 119 */ 120 bool insert_keyframe_direct(struct ReportList *reports, 121 struct PointerRNA ptr, 122 struct PropertyRNA *prop, 123 struct FCurve *fcu, 124 const struct AnimationEvalContext *anim_eval_context, 125 eBezTriple_KeyframeType keytype, 126 struct NlaKeyframingContext *nla, 127 eInsertKeyFlags flag); 128 129 /* -------- */ 130 131 /* Main Keyframing API calls: 132 * Use this to create any necessary animation data, and then insert a keyframe 133 * using the current value being keyframed, in the relevant place. Returns success. 134 */ 135 int insert_keyframe(struct Main *bmain, 136 struct ReportList *reports, 137 struct ID *id, 138 struct bAction *act, 139 const char group[], 140 const char rna_path[], 141 int array_index, 142 const struct AnimationEvalContext *anim_eval_context, 143 eBezTriple_KeyframeType keytype, 144 struct ListBase *nla_cache, 145 eInsertKeyFlags flag); 146 147 /* Main Keyframing API call: 148 * Use this to delete keyframe on current frame for relevant channel. 149 * Will perform checks just in case. */ 150 int delete_keyframe(struct Main *bmain, 151 struct ReportList *reports, 152 struct ID *id, 153 struct bAction *act, 154 const char rna_path[], 155 int array_index, 156 float cfra); 157 158 /* ************ Keying Sets ********************** */ 159 160 /* forward decl. for this struct which is declared a bit later... */ 161 struct ExtensionRNA; 162 struct KeyingSetInfo; 163 164 /* Polling Callback for KeyingSets */ 165 typedef bool (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C); 166 /* Context Iterator Callback for KeyingSets */ 167 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi, 168 struct bContext *C, 169 struct KeyingSet *ks); 170 /* Property Specifier Callback for KeyingSets (called from iterators) */ 171 typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, 172 struct bContext *C, 173 struct KeyingSet *ks, 174 struct PointerRNA *ptr); 175 176 /* Callback info for 'Procedural' KeyingSets to use */ 177 typedef struct KeyingSetInfo { 178 struct KeyingSetInfo *next, *prev; 179 180 /* info */ 181 /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */ 182 char idname[64]; 183 /* identifier so that user can hook this up to a KeyingSet (used as label). */ 184 char name[64]; 185 /* short help/description. */ 186 char description[240]; /* RNA_DYN_DESCR_MAX */ 187 /* keying settings */ 188 short keyingflag; 189 190 /* polling callbacks */ 191 /* callback for polling the context for whether the right data is available */ 192 cbKeyingSet_Poll poll; 193 194 /* generate callbacks */ 195 /* iterator to use to go through collections of data in context 196 * - this callback is separate from the 'adding' stage, allowing 197 * BuiltIn KeyingSets to be manually specified to use 198 */ 199 cbKeyingSet_Iterator iter; 200 /* generator to use to add properties based on the data found by iterator */ 201 cbKeyingSet_Generate generate; 202 203 /* RNA integration */ 204 struct ExtensionRNA rna_ext; 205 } KeyingSetInfo; 206 207 /* -------- */ 208 209 /* Add another data source for Relative Keying Sets to be evaluated with */ 210 void ANIM_relative_keyingset_add_source(ListBase *dsources, 211 struct ID *id, 212 struct StructRNA *srna, 213 void *data); 214 215 /* mode for modify_keyframes */ 216 typedef enum eModifyKey_Modes { 217 MODIFYKEY_MODE_INSERT = 0, 218 MODIFYKEY_MODE_DELETE, 219 } eModifyKey_Modes; 220 221 /* return codes for errors (with Relative KeyingSets) */ 222 typedef enum eModifyKey_Returns { 223 /* context info was invalid for using the Keying Set */ 224 MODIFYKEY_INVALID_CONTEXT = -1, 225 /* there isn't any typeinfo for generating paths from context */ 226 MODIFYKEY_MISSING_TYPEINFO = -2, 227 } eModifyKey_Returns; 228 229 /* poll the current KeyingSet, updating its set of paths 230 * (if "builtin"/"relative") for context changes */ 231 eModifyKey_Returns ANIM_validate_keyingset(struct bContext *C, 232 ListBase *dsources, 233 struct KeyingSet *ks); 234 235 /* use the specified KeyingSet to add/remove various Keyframes on the specified frame */ 236 int ANIM_apply_keyingset(struct bContext *C, 237 ListBase *dsources, 238 struct bAction *act, 239 struct KeyingSet *ks, 240 short mode, 241 float cfra); 242 243 /* -------- */ 244 245 /* Get the first builtin KeyingSet with the given name, which occurs after the given one 246 * (or start of list if none given) */ 247 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]); 248 249 /* Find KeyingSet type info given a name */ 250 KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]); 251 252 /* Find a given ID in the KeyingSet */ 253 bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id); 254 255 /* for RNA type registrations... */ 256 void ANIM_keyingset_info_register(KeyingSetInfo *ksi); 257 void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi); 258 259 /* cleanup on exit */ 260 void ANIM_keyingset_infos_exit(void); 261 262 /* -------- */ 263 264 /* Get the active KeyingSet for the given scene */ 265 struct KeyingSet *ANIM_scene_get_active_keyingset(const struct Scene *scene); 266 267 /* Get the index of the Keying Set provided, for the given Scene */ 268 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks); 269 270 /* Get Keying Set to use for Auto-Keyframing some transforms */ 271 struct KeyingSet *ANIM_get_keyingset_for_autokeying(const struct Scene *scene, 272 const char *transformKSName); 273 274 /* Dynamically populate an enum of Keying Sets */ 275 const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, 276 struct PointerRNA *ptr, 277 struct PropertyRNA *prop, 278 bool *r_free); 279 280 /* Use to get the keying set from the int value used by enums. */ 281 KeyingSet *ANIM_keyingset_get_from_enum_type(struct Scene *scene, int type); 282 KeyingSet *ANIM_keyingset_get_from_idname(struct Scene *scene, const char *idname); 283 284 /* Check if KeyingSet can be used in the current context */ 285 bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks); 286 287 /* ************ Drivers ********************** */ 288 289 /* Flags for use by driver creation calls */ 290 typedef enum eCreateDriverFlags { 291 /** create drivers with a default variable for nicer UI */ 292 CREATEDRIVER_WITH_DEFAULT_DVAR = (1 << 0), 293 /** create drivers with Generator FModifier (for backwards compat) */ 294 CREATEDRIVER_WITH_FMODIFIER = (1 << 1), 295 } eCreateDriverFlags; 296 297 /* Heuristic to use for connecting target properties to driven ones */ 298 typedef enum eCreateDriver_MappingTypes { 299 /** 1 to Many - Use the specified index, and drive all elements with it */ 300 CREATEDRIVER_MAPPING_1_N = 0, 301 /** 1 to 1 - Only for the specified index on each side */ 302 CREATEDRIVER_MAPPING_1_1 = 1, 303 /** Many to Many - Match up the indices one by one (only for drivers on vectors/arrays) */ 304 CREATEDRIVER_MAPPING_N_N = 2, 305 306 /** None (Single Prop): 307 * Do not create driver with any targets; these will get added later instead */ 308 CREATEDRIVER_MAPPING_NONE = 3, 309 /** None (All Properties): 310 * Do not create driver with any targets; these will get added later instead */ 311 CREATEDRIVER_MAPPING_NONE_ALL = 4, 312 } eCreateDriver_MappingTypes; 313 314 /* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */ 315 extern EnumPropertyItem prop_driver_create_mapping_types[]; 316 317 /* -------- */ 318 319 typedef enum eDriverFCurveCreationMode { 320 DRIVER_FCURVE_LOOKUP_ONLY = 0, /* Don't add anything if not found. */ 321 DRIVER_FCURVE_KEYFRAMES = 1, /* Add with keyframes, for visual tweaking. */ 322 DRIVER_FCURVE_GENERATOR = 2, /* Add with generator, for script backwards compatibility. */ 323 DRIVER_FCURVE_EMPTY = 3 /* Add without data, for pasting. */ 324 } eDriverFCurveCreationMode; 325 326 /* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools, 327 * although there are special cases where this approach is preferable. 328 */ 329 struct FCurve *verify_driver_fcurve(struct ID *id, 330 const char rna_path[], 331 const int array_index, 332 eDriverFCurveCreationMode creation_mode); 333 334 struct FCurve *alloc_driver_fcurve(const char rna_path[], 335 const int array_index, 336 eDriverFCurveCreationMode creation_mode); 337 338 /* -------- */ 339 340 /* Main Driver Management API calls: 341 * Add a new driver for the specified property on the given ID block, 342 * and make it be driven by the specified target. 343 * 344 * This is intended to be used in conjunction with a modal "eyedropper" 345 * for picking the variable that is going to be used to drive this one. 346 * 347 * - flag: eCreateDriverFlags 348 * - driver_type: eDriver_Types 349 * - mapping_type: eCreateDriver_MappingTypes 350 */ 351 int ANIM_add_driver_with_target(struct ReportList *reports, 352 struct ID *dst_id, 353 const char dst_path[], 354 int dst_index, 355 struct ID *src_id, 356 const char src_path[], 357 int src_index, 358 short flag, 359 int driver_type, 360 short mapping_type); 361 362 /* -------- */ 363 364 /* Main Driver Management API calls: 365 * Add a new driver for the specified property on the given ID block 366 */ 367 int ANIM_add_driver(struct ReportList *reports, 368 struct ID *id, 369 const char rna_path[], 370 int array_index, 371 short flag, 372 int type); 373 374 /* Main Driver Management API calls: 375 * Remove the driver for the specified property on the given ID block (if available) 376 */ 377 bool ANIM_remove_driver( 378 struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); 379 380 /* -------- */ 381 382 /* Clear copy-paste buffer for drivers */ 383 void ANIM_drivers_copybuf_free(void); 384 385 /* Clear copy-paste buffer for driver variable sets */ 386 void ANIM_driver_vars_copybuf_free(void); 387 388 /* -------- */ 389 390 /* Returns whether there is a driver in the copy/paste buffer to paste */ 391 bool ANIM_driver_can_paste(void); 392 393 /* Main Driver Management API calls: 394 * Make a copy of the driver for the specified property on the given ID block 395 */ 396 bool ANIM_copy_driver( 397 struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); 398 399 /* Main Driver Management API calls: 400 * Add a new driver for the specified property on the given ID block or replace an existing one 401 * with the driver + driver-curve data from the buffer 402 */ 403 bool ANIM_paste_driver( 404 struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); 405 406 /* -------- */ 407 408 /* Checks if there are driver variables in the copy/paste buffer */ 409 bool ANIM_driver_vars_can_paste(void); 410 411 /* Copy the given driver's variables to the buffer */ 412 bool ANIM_driver_vars_copy(struct ReportList *reports, struct FCurve *fcu); 413 414 /* Paste the variables in the buffer to the given FCurve */ 415 bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace); 416 417 /* -------- */ 418 419 /* Create a driver & variable that reads the specified property, 420 * and store it in the buffers for Paste Driver and Paste Variables. */ 421 void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const char *var_name); 422 423 /* ************ Auto-Keyframing ********************** */ 424 /* Notes: 425 * - All the defines for this (User-Pref settings and Per-Scene settings) 426 * are defined in DNA_userdef_types.h 427 * - Scene settings take precedence over those for userprefs, with old files 428 * inheriting userpref settings for the scene settings 429 * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored 430 * as userprefs 431 */ 432 433 /* Auto-Keying macros for use by various tools */ 434 /* check if auto-keyframing is enabled (per scene takes precedence) */ 435 #define IS_AUTOKEY_ON(scene) \ 436 ((scene) ? ((scene)->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON)) 437 /* check the mode for auto-keyframing (per scene takes precedence) */ 438 #define IS_AUTOKEY_MODE(scene, mode) \ 439 ((scene) ? ((scene)->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : \ 440 (U.autokey_mode == AUTOKEY_MODE_##mode)) 441 /* check if a flag is set for auto-keyframing (per scene takes precedence) */ 442 #define IS_AUTOKEY_FLAG(scene, flag) \ 443 ((scene) ? (((scene)->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || \ 444 (U.autokey_flag & AUTOKEY_FLAG_##flag)) : \ 445 (U.autokey_flag & AUTOKEY_FLAG_##flag)) 446 447 /* auto-keyframing feature - checks for whether anything should be done for the current frame */ 448 bool autokeyframe_cfra_can_key(const struct Scene *scene, struct ID *id); 449 450 /* ************ Keyframe Checking ******************** */ 451 452 /* Lesser Keyframe Checking API call: 453 * - Used for the buttons to check for keyframes... 454 */ 455 bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter); 456 457 /* Lesser Keyframe Checking API call: 458 * - Returns whether the current value of a given property differs from the interpolated value. 459 * - Used for button drawing. 460 */ 461 bool fcurve_is_changed(struct PointerRNA ptr, 462 struct PropertyRNA *prop, 463 struct FCurve *fcu, 464 const struct AnimationEvalContext *anim_eval_context); 465 466 /** 467 * Main Keyframe Checking API call: 468 * Checks whether a keyframe exists for the given ID-block one the given frame. 469 * - It is recommended to call this method over the other keyframe-checkers directly, 470 * in case some detail of the implementation changes... 471 * - frame: the value of this is quite often result of #BKE_scene_frame_get() 472 */ 473 bool id_frame_has_keyframe(struct ID *id, float frame, short filter); 474 475 /* filter flags for id_cfra_has_keyframe 476 * 477 * WARNING: do not alter order of these, as also stored in files 478 * (for v3d->keyflags) 479 */ 480 typedef enum eAnimFilterFlags { 481 /* general */ 482 ANIMFILTER_KEYS_LOCAL = (1 << 0), /* only include locally available anim data */ 483 ANIMFILTER_KEYS_MUTED = (1 << 1), /* include muted elements */ 484 ANIMFILTER_KEYS_ACTIVE = (1 << 2), /* only include active-subelements */ 485 486 /* object specific */ 487 ANIMFILTER_KEYS_NOMAT = (1 << 9), /* don't include material keyframes */ 488 ANIMFILTER_KEYS_NOSKEY = (1 << 10), /* don't include shape keys (for geometry) */ 489 } eAnimFilterFlags; 490 491 /* utility funcs for auto keyframe */ 492 bool ED_autokeyframe_object(struct bContext *C, 493 struct Scene *scene, 494 struct Object *ob, 495 struct KeyingSet *ks); 496 bool ED_autokeyframe_pchan(struct bContext *C, 497 struct Scene *scene, 498 struct Object *ob, 499 struct bPoseChannel *pchan, 500 struct KeyingSet *ks); 501 bool ED_autokeyframe_property(struct bContext *C, 502 struct Scene *scene, 503 PointerRNA *ptr, 504 PropertyRNA *prop, 505 int rnaindex, 506 float cfra); 507 508 /* Names for builtin keying sets so we don't confuse these with labels/text, 509 * defined in python script: keyingsets_builtins.py */ 510 #define ANIM_KS_LOCATION_ID "Location" 511 #define ANIM_KS_ROTATION_ID "Rotation" 512 #define ANIM_KS_SCALING_ID "Scaling" 513 #define ANIM_KS_LOC_ROT_SCALE_ID "LocRotScale" 514 #define ANIM_KS_AVAILABLE_ID "Available" 515 #define ANIM_KS_WHOLE_CHARACTER_ID "WholeCharacter" 516 #define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID "WholeCharacterSelected" 517 518 #ifdef __cplusplus 519 } 520 #endif 521