Merge branch 'master' into blender2.8
[blender.git] / source / blender / editors / include / ED_keyframing.h
index afb1419..9c33f83 100644 (file)
@@ -46,72 +46,83 @@ struct FCurve;
 struct BezTriple;
 
 struct bPoseChannel;
-struct bConstraint;
 
 struct bContext;
-struct wmOperatorType;
 struct ReportList;
 
+struct Depsgraph;
+
 struct PointerRNA;
 struct PropertyRNA;
 struct EnumPropertyItem;
 
+#include "DNA_anim_types.h"
 #include "RNA_types.h"
 
 /* ************ Keyframing Management **************** */
 
-/* Get the active settings for keyframing settings from context (specifically the given scene) 
+/* Get the active settings for keyframing settings from context (specifically the given scene)
  *     - incl_mode: include settings from keyframing mode in the result (i.e. replace only)
  */
 short ANIM_get_keyframing_flags(struct Scene *scene, short incl_mode);
 
 /* -------- */
 
-/* Get (or add relevant data to be able to do so) the Active Action for the given 
+/* Get (or add relevant data to be able to do so) the Active Action for the given
  * Animation Data block, given an ID block where the Animation Data should reside.
  */
 struct bAction *verify_adt_action(struct ID *id, short add);
 
-/* Get (or add relevant data to be able to do so) F-Curve from the given Action. 
+/* Get (or add relevant data to be able to do so) F-Curve from the given Action.
  * This assumes that all the destinations are valid.
  */
-struct FCurve *verify_fcurve(struct bAction *act, const char group[], const char rna_path[], const int array_index, short add);
+struct FCurve *verify_fcurve(struct bAction *act, const char group[], struct PointerRNA *ptr,
+                             const char rna_path[], const int array_index, short add);
 
 /* -------- */
 
 /* Lesser Keyframing API call:
- *     Use this when validation of necessary animation data isn't necessary as it already
- *     exists, and there is a beztriple that can be directly copied into the array.
+ *  Update integer/discrete flags of the FCurve (used when creating/inserting keyframes,
+ *  but also through RNA when editing an ID prop, see T37103).
  */
-int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt, short flag);
+void update_autoflags_fcurve(struct FCurve *fcu, struct bContext *C, struct ReportList *reports,
+                             struct PointerRNA *ptr);
+
+/* -------- */
 
-/* Main Keyframing API call: 
- *     Use this when validation of necessary animation data isn't necessary as it
- *     already exists. It will insert a keyframe using the current value being keyframed.
- *     Returns the index at which a keyframe was added (or -1 if failed)
+/* Lesser Keyframing API call:
+ *  Use this when validation of necessary animation data isn't necessary as it already
+ *  exists, and there is a beztriple that can be directly copied into the array.
  */
-int insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
+int insert_bezt_fcurve(struct FCurve *fcu, const struct BezTriple *bezt, eInsertKeyFlags flag);
+
+/* Main Keyframing API call:
+ *  Use this when validation of necessary animation data isn't necessary as it
+ *  already exists. It will insert a keyframe using the current value being keyframed.
+ *  Returns the index at which a keyframe was added (or -1 if failed)
+ */
+int insert_vert_fcurve(struct FCurve *fcu, float x, float y, eBezTriple_KeyframeType keytype, eInsertKeyFlags flag);
 
 /* -------- */
 
-/* Secondary Keyframing API calls: 
- *     Use this to insert a keyframe using the current value being keyframed, in the 
+/* Secondary Keyframing API calls:
+ *     Use this to insert a keyframe using the current value being keyframed, in the
  *     nominated F-Curve (no creation of animation data performed). Returns success.
  */
-short insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
+bool insert_keyframe_direct(struct Depsgraph *depsgraph, struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, eBezTriple_KeyframeType keytype, eInsertKeyFlags flag);
 
 /* -------- */
 
-/* Main Keyframing API calls: 
+/* Main Keyframing API calls:
  *     Use this to create any necessary animation data, and then insert a keyframe
  *     using the current value being keyframed, in the relevant place. Returns success.
  */
-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);
+short insert_keyframe(struct Depsgraph *depsgraph, struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, eBezTriple_KeyframeType keytype, eInsertKeyFlags flag);
 
-/* Main Keyframing API call: 
- *     Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
+/* Main Keyframing API call:
+ *  Use this to delete keyframe on current frame for relevant channel. Will perform checks just in case.
  */
-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);
+short delete_keyframe(struct ReportList *reports, struct ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, eInsertKeyFlags flag);
 
 /* ************ Keying Sets ********************** */
 
@@ -124,36 +135,36 @@ typedef int (*cbKeyingSet_Poll)(struct KeyingSetInfo *ksi, struct bContext *C);
 /* Context Iterator Callback for KeyingSets */
 typedef void (*cbKeyingSet_Iterator)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks);
 /* Property Specifier Callback for KeyingSets (called from iterators) */
-typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks, struct PointerRNA *ptr); 
+typedef void (*cbKeyingSet_Generate)(struct KeyingSetInfo *ksi, struct bContext *C, struct KeyingSet *ks, struct PointerRNA *ptr);
 
 
 /* Callback info for 'Procedural' KeyingSets to use */
 typedef struct KeyingSetInfo {
        struct KeyingSetInfo *next, *prev;
-       
+
        /* info */
-               /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
+       /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
        char idname[64];
-               /* identifier so that user can hook this up to a KeyingSet (used as label). */
+       /* identifier so that user can hook this up to a KeyingSet (used as label). */
        char name[64];
-               /* short help/description. */
+       /* short help/description. */
        char description[240]; /* RNA_DYN_DESCR_MAX */
-               /* keying settings */
+       /* keying settings */
        short keyingflag;
-       
+
        /* polling callbacks */
-               /* callback for polling the context for whether the right data is available */
+       /* callback for polling the context for whether the right data is available */
        cbKeyingSet_Poll poll;
-       
+
        /* generate callbacks */
-               /* iterator to use to go through collections of data in context
-                *      - this callback is separate from the 'adding' stage, allowing 
-                *        BuiltIn KeyingSets to be manually specified to use 
-                */
+       /* iterator to use to go through collections of data in context
+        *  - this callback is separate from the 'adding' stage, allowing
+        *    BuiltIn KeyingSets to be manually specified to use
+        */
        cbKeyingSet_Iterator iter;
-               /* generator to use to add properties based on the data found by iterator */
+       /* generator to use to add properties based on the data found by iterator */
        cbKeyingSet_Generate generate;
-       
+
        /* RNA integration */
        struct ExtensionRNA ext;
 } KeyingSetInfo;
@@ -172,9 +183,9 @@ typedef enum eModifyKey_Modes {
 
 /* return codes for errors (with Relative KeyingSets) */
 typedef enum eModifyKey_Returns {
-               /* context info was invalid for using the Keying Set */
+       /* context info was invalid for using the Keying Set */
        MODIFYKEY_INVALID_CONTEXT = -1,
-               /* there isn't any typeinfo for generating paths from context */
+       /* there isn't any typeinfo for generating paths from context */
        MODIFYKEY_MISSING_TYPEINFO = -2,
 } eModifyKey_Returns;
 
@@ -190,7 +201,10 @@ int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction
 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
 
 /* Find KeyingSet type info given a name */
-KeyingSetInfo *ANIM_keyingset_info_find_named(const char name[]);
+KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]);
+
+/* Find a given ID in the KeyingSet */
+bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id);
 
 /* for RNA type registrations... */
 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
@@ -211,18 +225,32 @@ int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
 struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene, const char *tranformKSName);
 
 /* Dynamically populate an enum of Keying Sets */
-struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, int *free);
+const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, bool *r_free);
 
 /* Check if KeyingSet can be used in the current context */
-short ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
+bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
 
 /* ************ Drivers ********************** */
 
 /* Flags for use by driver creation calls */
 typedef enum eCreateDriverFlags {
-       CREATEDRIVER_WITH_DEFAULT_DVAR  = (1<<0),       /* create drivers with a default variable for nicer UI */
+       CREATEDRIVER_WITH_DEFAULT_DVAR  = (1 << 0),   /* create drivers with a default variable for nicer UI */
+       CREATEDRIVER_WITH_FMODIFIER     = (1 << 1),   /* create drivers with Generator FModifier (for backwards compat) */
 } eCreateDriverFlags;
 
+/* Heuristic to use for connecting target properties to driven ones */
+typedef enum eCreateDriver_MappingTypes {
+       CREATEDRIVER_MAPPING_1_N        = 0,           /* 1 to Many - Use the specified index, and drive all elements with it */
+       CREATEDRIVER_MAPPING_1_1        = 1,           /* 1 to 1 - Only for the specified index on each side */
+       CREATEDRIVER_MAPPING_N_N        = 2,           /* Many to Many - Match up the indices one by one (only for drivers on vectors/arrays) */
+
+       CREATEDRIVER_MAPPING_NONE       = 3,           /* None (Single Prop)    - Do not create driver with any targets; these will get added later instead */
+       CREATEDRIVER_MAPPING_NONE_ALL   = 4,           /* None (All Properties) - Do not create driver with any targets; these will get added later instead */
+} eCreateDriver_MappingTypes;
+
+/* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */
+extern EnumPropertyItem prop_driver_create_mapping_types[];
+
 /* -------- */
 
 /* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools,
@@ -232,89 +260,129 @@ struct FCurve *verify_driver_fcurve(struct ID *id, const char rna_path[], const
 
 /* -------- */
 
-/* Returns whether there is a driver in the copy/paste buffer to paste */
-short ANIM_driver_can_paste(void);
+/* Main Driver Management API calls:
+ *  Add a new driver for the specified property on the given ID block,
+ *  and make it be driven by the specified target.
+ *
+ * This is intended to be used in conjunction with a modal "eyedropper"
+ * for picking the variable that is going to be used to drive this one.
+ *
+ * - flag: eCreateDriverFlags
+ * - driver_type: eDriver_Types
+ * - mapping_type: eCreateDriver_MappingTypes
+ */
+int ANIM_add_driver_with_target(
+        struct ReportList *reports,
+        struct ID *dst_id, const char dst_path[], int dst_index,
+        struct ID *src_id, const char src_path[], int src_index,
+        short flag, int driver_type, short mapping_type);
+
+/* -------- */
 
 /* Main Driver Management API calls:
- *     Add a new driver for the specified property on the given ID block
+ *  Add a new driver for the specified property on the given ID block
  */
-short ANIM_add_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag, int type);
+int ANIM_add_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag, int type);
 
 /* Main Driver Management API calls:
- *     Remove the driver for the specified property on the given ID block (if available)
+ *  Remove the driver for the specified property on the given ID block (if available)
  */
-short ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+bool ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+
+/* -------- */
+
+/* Clear copy-paste buffer for drivers */
+void ANIM_drivers_copybuf_free(void);
+
+/* Clear copy-paste buffer for driver variable sets */
+void ANIM_driver_vars_copybuf_free(void);
+
+/* -------- */
+
+/* Returns whether there is a driver in the copy/paste buffer to paste */
+bool ANIM_driver_can_paste(void);
 
 /* Main Driver Management API calls:
- *     Make a copy of the driver for the specified property on the given ID block
+ *  Make a copy of the driver for the specified property on the given ID block
  */
-short ANIM_copy_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+bool ANIM_copy_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 
 /* Main Driver Management API calls:
- *     Add a new driver for the specified property on the given ID block or replace an existing one
- *     with the driver + driver-curve data from the buffer 
+ *  Add a new driver for the specified property on the given ID block or replace an existing one
+ *     with the driver + driver-curve data from the buffer
  */
-short ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+bool ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+
+/* -------- */
+
+/* Checks if there are driver variables in the copy/paste buffer */
+bool ANIM_driver_vars_can_paste(void);
+
+/* Copy the given driver's variables to the buffer */
+bool ANIM_driver_vars_copy(struct ReportList *reports, struct FCurve *fcu);
+
+/* Paste the variables in the buffer to the given FCurve */
+bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace);
 
 /* ************ Auto-Keyframing ********************** */
 /* Notes:
  * - All the defines for this (User-Pref settings and Per-Scene settings)
- *     are defined in DNA_userdef_types.h
- * - Scene settings take presidence over those for userprefs, with old files
- *     inheriting userpref settings for the scene settings
+ *  are defined in DNA_userdef_types.h
+ * - Scene settings take precedence over those for userprefs, with old files
+ *  inheriting userpref settings for the scene settings
  * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
- *     as userprefs
+ *  as userprefs
  */
 
 /* Auto-Keying macros for use by various tools */
-       /* check if auto-keyframing is enabled (per scene takes presidence) */
-#define IS_AUTOKEY_ON(scene)   ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
-       /* check the mode for auto-keyframing (per scene takes presidence)  */
-#define IS_AUTOKEY_MODE(scene, mode)   ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
-       /* check if a flag is set for auto-keyframing (per scene takes presidence) */
+/* check if auto-keyframing is enabled (per scene takes precedence) */
+#define IS_AUTOKEY_ON(scene)  ((scene) ? (scene->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
+/* check the mode for auto-keyframing (per scene takes precedence)  */
+#define IS_AUTOKEY_MODE(scene, mode)  ((scene) ? (scene->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : (U.autokey_mode == AUTOKEY_MODE_##mode))
+/* check if a flag is set for auto-keyframing (per scene takes precedence) */
 #define IS_AUTOKEY_FLAG(scene, flag) \
-       ((scene)? \
+       ((scene) ? \
                ((scene->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || (U.autokey_flag & AUTOKEY_FLAG_##flag)) \
         : \
                (U.autokey_flag & AUTOKEY_FLAG_##flag))
 
 /* auto-keyframing feature - checks for whether anything should be done for the current frame */
-int autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
+bool autokeyframe_cfra_can_key(struct Scene *scene, struct ID *id);
 
 /* ************ Keyframe Checking ******************** */
 
 /* Lesser Keyframe Checking API call:
  *     - Used for the buttons to check for keyframes...
  */
-short fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
+bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
 
 /* Main Keyframe Checking API call:
  * Checks whether a keyframe exists for the given ID-block one the given frame.
  *  - It is recommended to call this method over the other keyframe-checkers directly,
- *       in case some detail of the implementation changes...
- *     - frame: the value of this is quite often result of BKE_curframe()
+ *    in case some detail of the implementation changes...
+ *     - frame: the value of this is quite often result of BKE_scene_frame_get()
  */
-short id_frame_has_keyframe(struct ID *id, float frame, short filter);
+bool id_frame_has_keyframe(struct ID *id, float frame, short filter);
 
-/* filter flags for id_cfra_has_keyframe 
+/* filter flags for id_cfra_has_keyframe
  *
  * WARNING: do not alter order of these, as also stored in files
  *     (for v3d->keyflags)
  */
 typedef enum eAnimFilterFlags {
-               /* general */
-       ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
-       ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
-       ANIMFILTER_KEYS_ACTIVE  = (1<<2),               /* only include active-subelements */
-       
-               /* object specific */
-       ANIMFILTER_KEYS_NOMAT           = (1<<9),               /* don't include material keyframes */
-       ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
+       /* general */
+       ANIMFILTER_KEYS_LOCAL   = (1 << 0),       /* only include locally available anim data */
+       ANIMFILTER_KEYS_MUTED   = (1 << 1),       /* include muted elements */
+       ANIMFILTER_KEYS_ACTIVE  = (1 << 2),       /* only include active-subelements */
+
+       /* object specific */
+       ANIMFILTER_KEYS_NOMAT   = (1 << 9),   /* don't include material keyframes */
+       ANIMFILTER_KEYS_NOSKEY  = (1 << 10),  /* don't include shape keys (for geometry) */
 } eAnimFilterFlags;
 
 /* utility funcs for auto keyframe */
-int ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, struct KeyingSet *ks);
-int ED_autokeyframe_pchan(struct bContext *C, struct Scene *scene, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks);
+bool ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, struct KeyingSet *ks);
+bool ED_autokeyframe_pchan(struct bContext *C, struct Scene *scene, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks);
 
 /* Names for builtin keying sets so we don't confuse these with labels/text,
  * defined in python script: keyingsets_builtins.py */
@@ -324,6 +392,7 @@ int ED_autokeyframe_pchan(struct bContext *C, struct Scene *scene, struct Object
 #define ANIM_KS_LOC_ROT_SCALE_ID    "LocRotScale"
 #define ANIM_KS_AVAILABLE_ID        "Available"
 #define ANIM_KS_WHOLE_CHARACTER_ID  "WholeCharacter"
+#define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID  "WholeCharacterSelected"
 
 #ifdef __cplusplus
 }