doxygen: editor entry
[blender.git] / source / blender / editors / include / ED_keyframing.h
index 503d71b0d3ec49f5d03b23f6828b20679b45a939..7bab563641a002c8a307436106c1f29a6ab12dd4 100644 (file)
@@ -1,4 +1,4 @@
-/**
+/*
  * $Id$
  *
  * ***** BEGIN GPL LICENSE BLOCK *****
@@ -15,7 +15,7 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software Foundation,
- * Inc., 59 Temple Place * Suite 330, Boston, MA  02111*1307, USA.
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  *
  * The Original Code is Copyright (C) 2008, Blender Foundation
  * This is a new part of Blender (with some old code)
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file ED_keyframing.h
+ *  \ingroup editors
+ */
+
 #ifndef ED_KEYFRAMING_H
 #define ED_KEYFRAMING_H
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 struct ListBase;
 struct ID;
+struct Scene;
 
 struct KeyingSet;
 
@@ -42,12 +51,23 @@ struct bConstraint;
 
 struct bContext;
 struct wmOperatorType;
+struct ReportList;
 
 struct PointerRNA;
 struct PropertyRNA;
+struct EnumPropertyItem;
+
+#include "RNA_types.h"
 
 /* ************ Keyframing Management **************** */
 
+/* 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 
  * Animation Data block, given an ID block where the Animation Data should reside.
  */
@@ -64,13 +84,14 @@ struct FCurve *verify_fcurve(struct bAction *act, const char group[], const char
  *     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_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt);
+int insert_bezt_fcurve(struct FCurve *fcu, struct BezTriple *bezt, short 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)
  */
-void insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
+int insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
 
 /* -------- */
 
@@ -78,9 +99,7 @@ void insert_vert_fcurve(struct FCurve *fcu, float x, float y, short flag);
  *     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 PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
-
-
+short insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float cfra, short flag);
 
 /* -------- */
 
@@ -88,96 +107,146 @@ short insert_keyframe_direct(struct PointerRNA ptr, struct PropertyRNA *prop, st
  *     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 ID *id, struct bAction *act, const char group[], const char rna_path[], int array_index, float cfra, short flag);
+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);
 
 /* 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 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, short flag);
 
-/* Main Keyframe Management operators: 
- *     These handle keyframes management from various spaces. They only make use of
- *     Keying Sets.
- */
-void ANIM_OT_insert_keyframe(struct wmOperatorType *ot);
-void ANIM_OT_delete_keyframe(struct wmOperatorType *ot);
+/* ************ Keying Sets ********************** */
 
-/* Main Keyframe Management operators: 
- *     These handle keyframes management from various spaces. They will handle the menus 
- *     required for each space.
- */
-void ANIM_OT_insert_keyframe_menu(struct wmOperatorType *ot);
-void ANIM_OT_delete_keyframe_menu(struct wmOperatorType *ot); // xxx unimplemented yet
-void ANIM_OT_delete_keyframe_old(struct wmOperatorType *ot); // xxx rename and keep?
+/* forward decl. for this struct which is declared a bit later... */
+struct KeyingSetInfo;
+struct ExtensionRNA;
 
-/* Keyframe managment operators for UI buttons. */
-void ANIM_OT_insert_keyframe_button(struct wmOperatorType *ot);
-void ANIM_OT_delete_keyframe_button(struct wmOperatorType *ot);
+/* Polling Callback for KeyingSets */
+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); 
 
-/* ************ Keying Sets ********************** */
 
-/* temporary struct to gather data combos to keyframe
- * (is used by modify_keyframes for 'relative' KeyingSets, provided via the dsources arg)
- */
-typedef struct bCommonKeySrc {
-       struct bCommonKeySrc *next, *prev;
-               
-               /* general data/destination-source settings */
-       struct ID *id;                                  /* id-block this comes from */
+/* Callback info for 'Procedural' KeyingSets to use */
+typedef struct KeyingSetInfo {
+       struct KeyingSetInfo *next, *prev;
        
-               /* specific cases */
-       struct bPoseChannel *pchan;     
-       struct bConstraint *con;
-} bCommonKeySrc;
+       /* info */
+               /* identifier so that user can hook this up to a KeyingSet */
+       char name[64];
+               /* identifier used for class name, which KeyingSet instances reference as "Typeinfo Name" */
+       char idname[64];
+               /* keying settings */
+       short keyingflag;
+       
+       /* polling callbacks */
+               /* 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 
+                */
+       cbKeyingSet_Iterator iter;
+               /* generator to use to add properties based on the data found by iterator */
+       cbKeyingSet_Generate generate;
+       
+       /* RNA integration */
+       struct ExtensionRNA ext;
+} KeyingSetInfo;
 
 /* -------- */
 
+/* Add another data source for Relative Keying Sets to be evaluated with */
+void ANIM_relative_keyingset_add_source(ListBase *dsources, struct ID *id, struct StructRNA *srna, void *data);
+
+
 /* mode for modify_keyframes */
-enum {
+typedef enum eModifyKey_Modes {
        MODIFYKEY_MODE_INSERT = 0,
        MODIFYKEY_MODE_DELETE,
 } eModifyKey_Modes;
 
-/* Keyframing Helper Call - use the provided Keying Set to Add/Remove Keyframes */
-int modify_keyframes(struct bContext *C, struct ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
+/* return codes for errors (with Relative KeyingSets) */
+typedef enum eModifyKey_Returns {
+               /* context info was invalid for using the Keying Set */
+       MODIFYKEY_INVALID_CONTEXT = -1,
+               /* there isn't any typeinfo for generating paths from context */
+       MODIFYKEY_MISSING_TYPEINFO = -2,
+} eModifyKey_Returns;
 
-/* -------- */
+/* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
+int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, struct KeyingSet *ks, short mode, float cfra);
 
-/* Generate menu of KeyingSets */
-char *ANIM_build_keyingsets_menu(struct ListBase *list, short for_edit);
+/* -------- */
 
 /* Get the first builtin KeyingSet with the given name, which occurs after the given one (or start of list if none given) */
-struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, char name[]);
+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[]);
 
-/* Initialise builtin KeyingSets on startup */
-void init_builtin_keyingsets(void);
+/* for RNA type registrations... */
+void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
+void ANIM_keyingset_info_unregister(const struct bContext *C, KeyingSetInfo *ksi);
+
+/* cleanup on exit */
+void ANIM_keyingset_infos_exit(void);
 
 /* -------- */
 
-/* KeyingSet Editing Operators:
- *     These can add a new KeyingSet and/or add 'destinations' to the KeyingSets,
- *     acting as a means by which they can be added outside the Outliner.
- */
-void ANIM_OT_keyingset_add_new(struct wmOperatorType *ot);
-void ANIM_OT_keyingset_add_destination(struct wmOperatorType *ot);
+/* Get the active KeyingSet for the given scene */
+struct KeyingSet *ANIM_scene_get_active_keyingset(struct Scene *scene);
+
+/* Get the index of the Keying Set provided, for the given Scene */
+int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
+
+/* Get Keying Set to use for Auto-Keyframing some transforms */
+struct KeyingSet *ANIM_get_keyingset_for_autokeying(struct Scene *scene, const char *tranformKSName);
+
+/* Create (and show) a menu containing all the Keying Sets which can be used in the current context */
+void ANIM_keying_sets_menu_setup(struct bContext *C, const char title[], const char op_name[]);
+
+/* Dynamically populate an enum of Keying Sets */
+struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, int *free);
+
+/* Check if KeyingSet can be used in the current context */
+short 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 */
+} eCreateDriverFlags;
+
+/* -------- */
+
+/* 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
  */
-short ANIM_add_driver (struct ID *id, const char rna_path[], int array_index, short flag);
+short 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)
  */
-short ANIM_remove_driver (struct ID *id, const char rna_path[], int array_index, short flag);
+short ANIM_remove_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
+
+/* Main Driver Management API calls:
+ *     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);
 
-/* Driver management operators for UI buttons */
-void ANIM_OT_add_driver_button(struct wmOperatorType *ot);
-void ANIM_OT_remove_driver_button(struct wmOperatorType *ot);
+/* 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 
+ */
+short ANIM_paste_driver(struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 
 /* ************ Auto-Keyframing ********************** */
 /* Notes:
@@ -194,8 +263,15 @@ void ANIM_OT_remove_driver_button(struct wmOperatorType *ot);
 #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 (as userprefs only!) */
-#define IS_AUTOKEY_FLAG(flag)  (U.autokey_flag & AUTOKEY_FLAG_##flag)
+       /* check if a flag is set for auto-keyframing (per scene takes presidence) */
+#define IS_AUTOKEY_FLAG(scene, flag) \
+       ((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);
 
 /* ************ Keyframe Checking ******************** */
 
@@ -208,7 +284,7 @@ short fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
  * 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 frame_to_float(CFRA)
+ *     - frame: the value of this is quite often result of BKE_curframe()
  */
 short id_frame_has_keyframe(struct ID *id, float frame, short filter);
 
@@ -217,7 +293,7 @@ short id_frame_has_keyframe(struct ID *id, float frame, short filter);
  * WARNING: do not alter order of these, as also stored in files
  *     (for v3d->keyflags)
  */
-enum {
+typedef enum eAnimFilterFlags {
                /* general */
        ANIMFILTER_KEYS_LOCAL   = (1<<0),               /* only include locally available anim data */
        ANIMFILTER_KEYS_MUTED   = (1<<1),               /* include muted elements */
@@ -228,4 +304,8 @@ enum {
        ANIMFILTER_KEYS_NOSKEY          = (1<<10),              /* don't include shape keys (for geometry) */
 } eAnimFilterFlags;
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /*  ED_KEYFRAMING_H */