From bd2b48e98d77c8437b8b0c77582084a3c984e45c Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 10 Dec 2021 21:42:06 +1100 Subject: Cleanup: move public doc-strings into headers for various API's Some doc-strings were skipped because of blank-lines between the doc-string and the symbol and needed to be moved manually. - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. Ref T92709 --- source/blender/editors/include/ED_armature.h | 137 +++++++- source/blender/editors/include/ED_keyframes_edit.h | 128 ++++++-- source/blender/editors/include/ED_keyframing.h | 349 +++++++++++++++------ source/blender/editors/include/ED_markers.h | 63 +++- source/blender/editors/include/ED_screen.h | 4 + source/blender/editors/include/ED_view3d.h | 2 + 6 files changed, 555 insertions(+), 128 deletions(-) (limited to 'source/blender/editors/include') diff --git a/source/blender/editors/include/ED_armature.h b/source/blender/editors/include/ED_armature.h index 868235c36e5..0053bf5c865 100644 --- a/source/blender/editors/include/ED_armature.h +++ b/source/blender/editors/include/ED_armature.h @@ -70,45 +70,91 @@ struct wmOperator; (CHECK_TYPE_INLINE(ebone, EditBone *), \ (((ebone)->flag & BONE_SELECTED) && !((ebone)->flag & BONE_EDITMODE_LOCKED))) -/* used in armature_select.c and pose_select.c */ +/* Used in `armature_select.c` and `pose_select.c`. */ + #define BONE_SELECT_PARENT 0 #define BONE_SELECT_CHILD 1 /* armature_add.c */ + +/** + * Default bone add, returns it selected, but without tail set. + * + * \note should be used everywhere, now it allocates bones still locally in functions. + */ struct EditBone *ED_armature_ebone_add(struct bArmature *arm, const char *name); struct EditBone *ED_armature_ebone_add_primitive(struct Object *obedit_arm, float length, bool view_aligned); /* armature_edit.c */ + +/** + * Adjust bone roll to align Z axis with vector `align_axis` is in local space and is normalized. + */ float ED_armature_ebone_roll_to_vector(const struct EditBone *bone, const float align_axis[3], const bool axis_only); +/** + * \param centermode: 0 == do center, 1 == center new, 2 == center cursor. + * + * \note Exported for use in `editors/object/`. + */ void ED_armature_origin_set( struct Main *bmain, struct Object *ob, const float cursor[3], int centermode, int around); +/** + * See #BKE_armature_transform for object-mode transform. + */ void ED_armature_edit_transform(struct bArmature *arm, const float mat[4][4], const bool do_props); void ED_armature_transform(struct bArmature *arm, const float mat[4][4], const bool do_props); /* armature_naming.c */ + +/** + * Ensure the bone name is unique. + * If bone is already in list, pass it as argument to ignore it. + */ void ED_armature_ebone_unique_name(struct ListBase *ebones, char *name, struct EditBone *bone); + +/** + * Bone Rename (called by UI for renaming a bone). + * Seems messy, but that's what you get with not using pointers but channel names :). + * \warning make sure the original bone was not renamed yet! + */ void ED_armature_bone_rename(struct Main *bmain, struct bArmature *arm, const char *oldnamep, const char *newnamep); +/** + * Renames (by flipping) all selected bones at once. + * + * This way if we are flipping related bones (e.g., Bone.L, Bone.R) at the same time + * all the bones are safely renamed, without conflicting with each other. + * + * \param arm: Armature the bones belong to + * \param bones_names: List of bone conflict elements (#LinkData pointing to names). + * \param do_strip_numbers: if set, try to get rid of dot-numbers at end of bone names. + */ void ED_armature_bones_flip_names(struct Main *bmain, struct bArmature *arm, struct ListBase *bones_names, const bool do_strip_numbers); /* armature_ops.c */ + void ED_operatortypes_armature(void); void ED_operatormacros_armature(void); void ED_keymap_armature(struct wmKeyConfig *keyconf); /* armature_relations.c */ + +/** + * Join armature exec is exported for use in object->join objects operator. + */ int ED_armature_join_objects_exec(struct bContext *C, struct wmOperator *op); /* armature_select.c */ + struct Base *ED_armature_base_and_ebone_from_select_buffer(struct Base **bases, uint bases_len, int hit, @@ -121,6 +167,9 @@ struct Base *ED_armature_base_and_pchan_from_select_buffer(struct Base **bases, uint bases_len, int hit, struct bPoseChannel **r_pchan); +/** + * For callers that don't need the pose channel. + */ struct Base *ED_armature_base_and_bone_from_select_buffer(struct Base **bases, uint bases_len, int hit, @@ -137,11 +186,27 @@ bool ED_armature_edit_select_pick_bone(struct bContext *C, bool extend, bool deselect, bool toggle); +/** + * Bone selection picking for armature edit-mode in the view3d. + */ bool ED_armature_edit_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); +/** + * Perform a selection operation on elements which have been 'touched', + * use for lasso & border select but can be used elsewhere too. + * + * Tagging is done via #EditBone.temp.i using: #BONESEL_ROOT, #BONESEL_TIP, #BONESEL_BONE + * And optionally ignoring end-points using the #BONESEL_ROOT, #BONESEL_TIP right shifted 16 bits. + * (used when the values are clipped outside the view). + * + * \param sel_op: #eSelectOp type. + * + * \note Visibility checks must be done by the caller. + */ bool ED_armature_edit_select_op_from_tagged(struct bArmature *arm, const int sel_op); /* armature_skinning.c */ + #define ARM_GROUPS_NAME 1 #define ARM_GROUPS_ENVELOPE 2 #define ARM_GROUPS_AUTO 3 @@ -154,40 +219,74 @@ void ED_object_vgroup_calc_from_armature(struct ReportList *reports, const bool mirror); /* editarmature_undo.c */ + +/** Export for ED_undo_sys. */ void ED_armature_undosys_type(struct UndoType *ut); /* armature_utils.c */ + +/** Sync selection to parent for connected children. */ void ED_armature_edit_sync_selection(struct ListBase *edbo); void ED_armature_edit_validate_active(struct bArmature *arm); +/** + * Update the layers_used variable after bones are moved between layer + * \note Used to be done in drawing code in 2.7, but that won't work with + * Copy-on-Write, as drawing uses evaluated copies. + */ void ED_armature_edit_refresh_layer_used(struct bArmature *arm); +/** + * \param clear_connected: When false caller is responsible for keeping the flag in a valid state. + */ void ED_armature_ebone_remove_ex(struct bArmature *arm, struct EditBone *exBone, bool clear_connected); void ED_armature_ebone_remove(struct bArmature *arm, struct EditBone *exBone); bool ED_armature_ebone_is_child_recursive(struct EditBone *ebone_parent, struct EditBone *ebone_child); +/** + * Finds the first parent shared by \a ebone_child + * + * \param ebone_child: Children bones to search + * \param ebone_child_tot: Size of the ebone_child array + * \return The shared parent or NULL. + */ struct EditBone *ED_armature_ebone_find_shared_parent(struct EditBone *ebone_child[], const unsigned int ebone_child_tot); void ED_armature_ebone_to_mat3(struct EditBone *ebone, float r_mat[3][3]); void ED_armature_ebone_to_mat4(struct EditBone *ebone, float r_mat[4][4]); void ED_armature_ebone_from_mat3(struct EditBone *ebone, const float mat[3][3]); void ED_armature_ebone_from_mat4(struct EditBone *ebone, const float mat[4][4]); +/** + * Return a pointer to the bone of the given name + */ struct EditBone *ED_armature_ebone_find_name(const struct ListBase *edbo, const char *name); +/** + * \see #BKE_pose_channel_get_mirrored (pose-mode, matching function) + */ struct EditBone *ED_armature_ebone_get_mirrored(const struct ListBase *edbo, struct EditBone *ebo); void ED_armature_ebone_transform_mirror_update(struct bArmature *arm, struct EditBone *ebo, bool check_select); +/** + * If edit-bone (partial) selected, copy data. + * context; edit-mode armature, with mirror editing enabled. + */ void ED_armature_edit_transform_mirror_update(struct Object *obedit); +/** Put edit-mode back in Object. */ void ED_armature_from_edit(struct Main *bmain, struct bArmature *arm); +/** Put armature in edit-mode. */ void ED_armature_to_edit(struct bArmature *arm); void ED_armature_edit_free(struct bArmature *arm); void ED_armature_ebone_listbase_temp_clear(struct ListBase *lb); + +/** + * Free's bones and their properties. + */ void ED_armature_ebone_listbase_free(struct ListBase *lb, const bool do_id_user); void ED_armature_ebone_listbase_copy(struct ListBase *lb_dst, struct ListBase *lb_src, const bool do_id_user); -/* low level selection functions which handle */ int ED_armature_ebone_selectflag_get(const struct EditBone *ebone); void ED_armature_ebone_selectflag_set(struct EditBone *ebone, int flag); void ED_armature_ebone_select_set(struct EditBone *ebone, bool select); @@ -198,21 +297,29 @@ void ED_armature_ebone_selectflag_disable(struct EditBone *ebone, int flag); struct Object *ED_pose_object_from_context(struct bContext *C); bool ED_object_posemode_exit_ex(struct Main *bmain, struct Object *ob); bool ED_object_posemode_exit(struct bContext *C, struct Object *ob); +/** This function is used to process the necessary updates for. */ bool ED_object_posemode_enter_ex(struct Main *bmain, struct Object *ob); bool ED_object_posemode_enter(struct bContext *C, struct Object *ob); -/* Corresponds to eAnimvizCalcRange. */ +/** Corresponds to #eAnimvizCalcRange. */ typedef enum ePosePathCalcRange { POSE_PATH_CALC_RANGE_CURRENT_FRAME, POSE_PATH_CALC_RANGE_CHANGED, POSE_PATH_CALC_RANGE_FULL, } ePosePathCalcRange; +/** + * For the object with pose/action: update paths for those that have got them + * This should selectively update paths that exist... + * + * To be called from various tools that do incremental updates. + */ void ED_pose_recalculate_paths(struct bContext *C, struct Scene *scene, struct Object *ob, ePosePathCalcRange range); /* pose_select.c */ + void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer, struct View3D *v3d, struct Object *ob, @@ -220,6 +327,10 @@ void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer, bool extend, bool deselect, bool toggle); +/** + * Called for mode-less pose selection. + * assumes the active object is still on old situation. + */ bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer, struct View3D *v3d, struct Base *base, @@ -229,6 +340,14 @@ bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer, bool deselect, bool toggle, bool do_nearest); +/** + * While in weight-paint mode, a single pose may be active as well. + * While not common, it's possible we have multiple armatures deforming a mesh. + * + * This function de-selects all other objects, and selects the new base. + * It can't be set to the active object because we need + * to keep this set to the weight paint object. + */ void ED_armature_pose_select_in_wpaint_mode(struct ViewLayer *view_layer, struct Base *base_select); bool ED_pose_deselect_all_multi_ex(struct Base **bases, @@ -236,8 +355,16 @@ bool ED_pose_deselect_all_multi_ex(struct Base **bases, int select_mode, const bool ignore_visibility); bool ED_pose_deselect_all_multi(struct bContext *C, int select_mode, const bool ignore_visibility); +/** + * 'select_mode' is usual SEL_SELECT/SEL_DESELECT/SEL_TOGGLE/SEL_INVERT. + * When true, 'ignore_visibility' makes this func also affect invisible bones + * (hidden or on hidden layers). + */ bool ED_pose_deselect_all(struct Object *ob, int select_mode, const bool ignore_visibility); void ED_pose_bone_select_tag_update(struct Object *ob); +/** + * Utility method for changing the selection status of a bone. + */ void ED_pose_bone_select(struct Object *ob, struct bPoseChannel *pchan, bool select); /* meshlaplacian.c */ @@ -249,7 +376,9 @@ void ED_mesh_deform_bind_callback(struct MeshDeformModifierData *mmd, /* Pose backups, pose_backup.c */ struct PoseBackup; -/* Create a backup of those bones that are animated in the given action. */ +/** + * Create a backup of those bones that are animated in the given action. + */ struct PoseBackup *ED_pose_backup_create_selected_bones( const struct Object *ob, const struct bAction *action) ATTR_WARN_UNUSED_RESULT; struct PoseBackup *ED_pose_backup_create_all_bones( diff --git a/source/blender/editors/include/ED_keyframes_edit.h b/source/blender/editors/include/ED_keyframes_edit.h index e29ff3ed890..76ba2ebf4a6 100644 --- a/source/blender/editors/include/ED_keyframes_edit.h +++ b/source/blender/editors/include/ED_keyframes_edit.h @@ -39,7 +39,9 @@ struct bDopeSheet; /* ************************************************ */ /* Common Macros and Defines */ -/* --------- Tool Flags ------------ */ +/* -------------------------------------------------------------------- */ +/** \name Tool Flags + * \{ */ /* bezt validation */ typedef enum eEditKeyframes_Validate { @@ -60,7 +62,7 @@ typedef enum eEditKeyframes_Validate { BEZT_OK_CHANNEL_CIRCLE, } eEditKeyframes_Validate; -/* ------------ */ +/** \} */ /* select modes */ typedef enum eEditKeyframes_Select { @@ -120,7 +122,9 @@ typedef struct KeyframeEdit_CircleData { /* ************************************************ */ /* Non-Destructive Editing API (keyframes_edit.c) */ -/* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */ +/* -------------------------------------------------------------------- */ +/** \name Defines for 'OK' polls + KeyframeEditData Flags + * \{ */ /* which verts of a keyframe is active (after polling) */ typedef enum eKeyframeVertOk { @@ -154,7 +158,11 @@ typedef enum eKeyframeIterFlags { KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE = (1 << 3), } eKeyframeIterFlags; -/* --- Generic Properties for Keyframe Edit Tools ----- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Generic Properties for Keyframe Edit Tools + * \{ */ typedef struct KeyframeEditData { /* generic properties/data access */ @@ -184,14 +192,22 @@ typedef struct KeyframeEditData { eKeyframeIterFlags iterflags; } KeyframeEditData; -/* ------- Function Pointer Typedefs ---------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Function Pointer Typedefs + * \{ */ /* callback function that refreshes the F-Curve after use */ typedef void (*FcuEditFunc)(struct FCurve *fcu); /* callback function that operates on the given BezTriple */ typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt); -/* ------- Custom Data Type Defines ------------------ */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Custom Data Type Defines + * \{ */ /* Custom data for remapping one range to another in a fixed way */ typedef struct KeyframeEditCD_Remap { @@ -222,18 +238,29 @@ typedef enum eKeyMergeMode { KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL, } eKeyMergeMode; -/* ---------------- Looping API --------------------- */ +/** \} */ -/* functions for looping over keyframes */ -/* function for working with F-Curve data only - * (i.e. when filters have been chosen to explicitly use this) */ +/* -------------------------------------------------------------------- */ +/** \name Looping API + * + * Functions for looping over keyframes. + * \{ */ + +/** + * This function is used to loop over BezTriples in the given F-Curve, applying a given + * operation on them, and optionally applies an F-Curve validation function afterwards. + * + * function for working with F-Curve data only + * (i.e. when filters have been chosen to explicitly use this). + */ short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* function for working with any type (i.e. one of the known types) of animation channel - * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG) +/** + * Function for working with any type (i.e. one of the known types) of animation channel + * \param filterflag: is bDopeSheet->flag (#DOPESHEET_FILTERFLAG). */ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, @@ -241,8 +268,9 @@ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* same as above, except bAnimListElem wrapper is not needed... - * - keytype is eAnim_KeyType +/** + * Same as above, except bAnimListElem wrapper is not needed... + * \param keytype: is eAnim_KeyType. */ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, @@ -252,55 +280,92 @@ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* Calls callback_fn() for each keyframe in each fcurve in the filtered animation context. - * Assumes the callback updates keys. */ +/** + * Calls callback_fn() for each keyframe in each fcurve in the filtered animation context. + * Assumes the callback updates keys. + */ void ANIM_animdata_keyframe_callback(struct bAnimContext *ac, eAnimFilter_Flags filter, KeyframeEditFunc callback_fn); -/* functions for making sure all keyframes are in good order */ +/** + * Functions for making sure all keyframes are in good order. + */ void ANIM_editkeyframes_refresh(struct bAnimContext *ac); -/* ----------- BezTriple Callback Getters ---------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callback Getters + * \{ */ /* accessories */ KeyframeEditFunc ANIM_editkeyframes_ok(short mode); /* edit */ KeyframeEditFunc ANIM_editkeyframes_snap(short mode); +/** + * \note for markers and 'value', the values to use must be supplied as the first float value. + */ KeyframeEditFunc ANIM_editkeyframes_mirror(short mode); KeyframeEditFunc ANIM_editkeyframes_select(short mode); +/** + * Set all selected Bezier Handles to a single type. + */ KeyframeEditFunc ANIM_editkeyframes_handles(short mode); +/** + * Set the interpolation type of the selected BezTriples in each F-Curve to the specified one. + */ KeyframeEditFunc ANIM_editkeyframes_ipo(short mode); KeyframeEditFunc ANIM_editkeyframes_keytype(short mode); KeyframeEditFunc ANIM_editkeyframes_easing(short mode); -/* -------- BezTriple Callbacks (Selection Map) ---------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callbacks (Selection Map) + * \{ */ -/* Get a callback to populate the selection settings map - * requires: ked->custom = char[] of length fcurve->totvert +/** + * Get a callback to populate the selection settings map + * requires: ked->custom = char[] of length fcurve->totvert. */ KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode); -/* Change the selection status of the keyframe based on the map entry for this vert - * requires: ked->custom = char[] of length fcurve->totvert +/** + * Change the selection status of the keyframe based on the map entry for this vert + * requires: ked->custom = char[] of length fcurve->totvert. */ short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt); -/* ----------- BezTriple Callback (Assorted Utilities) ---------- */ +/** \} */ -/* used to calculate the average location of all relevant BezTriples by summing their locations */ +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callback (Assorted Utilities) + * \{ */ + +/** + * Used to calculate the average location of all relevant BezTriples by summing their locations. + */ short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt); -/* used to extract a set of cfra-elems from the keyframes */ +/** + * Used to extract a set of cfra-elems from the keyframes. + */ short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt); -/* used to remap times from one range to another - * requires: ked->custom = KeyframeEditCD_Remap +/** + * Used to remap times from one range to another. + * requires: `ked->custom = KeyframeEditCD_Remap`. */ void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt); -/* ------ 1.5-D Region Testing Utilities (Lasso/Circle Select) ------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name 1.5-D Region Testing Utilities (Lasso/Circle Select) + * \{ */ + /* XXX: These are temporary, * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */ @@ -321,6 +386,9 @@ void clean_fcurve(struct bAnimContext *ac, float thresh, bool cleardefault); bool decimate_fcurve(struct bAnimListElem *ale, float remove_ratio, float error_sq_max); +/** + * Use a weighted moving-means method to reduce intensity of fluctuations. + */ void smooth_fcurve(struct FCurve *fcu); void sample_fcurve(struct FCurve *fcu); @@ -336,6 +404,8 @@ short paste_animedit_keys(struct bAnimContext *ac, /* ************************************************ */ +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_keyframing.h b/source/blender/editors/include/ED_keyframing.h index 673f629d6ef..d539c7b688c 100644 --- a/source/blender/editors/include/ED_keyframing.h +++ b/source/blender/editors/include/ED_keyframing.h @@ -53,22 +53,28 @@ struct PropertyRNA; struct NlaKeyframingContext; -/* ************ Keyframing Management **************** */ +/* -------------------------------------------------------------------- */ +/** \name Key-Framing Management + * \{ */ -/* Get the active settings for keyframing settings from context (specifically the given scene) - * - use_autokey_mode: include settings from keyframing mode in the result (i.e. replace only). +/** + * Get the active settings for key-framing settings from context (specifically the given scene) + * \param use_autokey_mode: include settings from key-framing mode in the result + * (i.e. replace only). */ eInsertKeyFlags ANIM_get_keyframing_flags(struct Scene *scene, const bool use_autokey_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 *ED_id_action_ensure(struct Main *bmain, struct ID *id); -/* 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. +/** + * Get (or add relevant data to be able to do so) F-Curve from the Active Action, + * for the given Animation Data block. This assumes that all the destinations are valid. */ struct FCurve *ED_action_fcurve_ensure(struct Main *bmain, struct bAction *act, @@ -77,15 +83,21 @@ struct FCurve *ED_action_fcurve_ensure(struct Main *bmain, const char rna_path[], const int array_index); +/** + * Find the F-Curve from the Active Action, + * for the given Animation Data block. This assumes that all the destinations are valid. + */ struct FCurve *ED_action_fcurve_find(struct bAction *act, const char rna_path[], const int array_index); /* -------- */ -/* Lesser Keyframing API call: - * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes, - * but also through RNA when editing an ID prop, see T37103). +/** + * \brief Lesser Key-framing API call. + * + * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes, + * but also through RNA when editing an ID prop, see T37103). */ void update_autoflags_fcurve(struct FCurve *fcu, struct bContext *C, @@ -94,16 +106,34 @@ void update_autoflags_fcurve(struct FCurve *fcu, /* -------- */ -/* 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. +/** + * \brief Lesser Key-framing 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. + * + * This function adds a given #BezTriple to an F-Curve. It will allocate + * memory for the array if needed, and will insert the #BezTriple into a + * suitable place in chronological order. + * + * \note any recalculate of the F-Curve that needs to be done will need to be done by the caller. */ 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) +/** + * \brief Main Key-framing 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). + * + * This function is a wrapper for #insert_bezt_fcurve(), and should be used when + * adding a new keyframe to a curve, when the keyframe doesn't exist anywhere else yet. + * It returns the index at which the keyframe was added. + * + * \param keyframe_type: The type of keyframe (#eBezTriple_KeyframeType). + * \param flag: Optional flags (#eInsertKeyFlags) for controlling how keys get added + * and/or whether updates get done. */ int insert_vert_fcurve(struct FCurve *fcu, float x, @@ -113,9 +143,21 @@ int insert_vert_fcurve(struct FCurve *fcu, /* -------- */ -/* 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. +/** + * \brief Secondary Insert Key-framing API call. + * + * Use this when validation of necessary animation data is not necessary, + * since an RNA-pointer to the necessary data being keyframed, + * and a pointer to the F-Curve to use have both been provided. + * + * This function can't keyframe quaternion channels on some NLA strip types. + * + * \param keytype: The "keyframe type" (eBezTriple_KeyframeType), as shown in the Dope Sheet. + * + * \param flag: Used for special settings that alter the behavior of the keyframe insertion. + * These include the 'visual' key-framing modes, quick refresh, + * and extra keyframe filtering. + * \return Success. */ bool insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, @@ -128,9 +170,17 @@ bool insert_keyframe_direct(struct ReportList *reports, /* -------- */ -/* Main Keyframing API calls: +/** + * \brief Main Insert Key-framing API call. + * * 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. + * using the current value being keyframed, in the relevant place. + * + * \param flag: Used for special settings that alter the behavior of the keyframe insertion. + * These include the 'visual' key-framing modes, quick refresh, and extra keyframe filtering. + * + * \param array_index: The index to key or -1 keys all array indices. + * \return The number of key-frames inserted. */ int insert_keyframe(struct Main *bmain, struct ReportList *reports, @@ -144,9 +194,13 @@ int insert_keyframe(struct Main *bmain, struct ListBase *nla_cache, eInsertKeyFlags flag); -/* Main Keyframing API call: +/** + * \brief Main Delete Key-Framing API call. + * * Use this to delete keyframe on current frame for relevant channel. - * Will perform checks just in case. */ + * Will perform checks just in case. + * \return The number of key-frames deleted. + */ int delete_keyframe(struct Main *bmain, struct ReportList *reports, struct ID *id, @@ -155,7 +209,11 @@ int delete_keyframe(struct Main *bmain, int array_index, float cfra); -/* ************ Keying Sets ********************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Keying Sets + * \{ */ /* forward decl. for this struct which is declared a bit later... */ struct ExtensionRNA; @@ -206,7 +264,9 @@ typedef struct KeyingSetInfo { /* -------- */ -/* Add another data source for Relative Keying Sets to be evaluated with */ +/** + * 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, @@ -226,13 +286,28 @@ typedef enum eModifyKey_Returns { MODIFYKEY_MISSING_TYPEINFO = -2, } eModifyKey_Returns; -/* poll the current KeyingSet, updating its set of paths - * (if "builtin"/"relative") for context changes */ +/** + * Given a #KeyingSet and context info, validate Keying Set's paths. + * This is only really necessary with relative/built-in KeyingSets + * where their list of paths is dynamically generated based on the + * current context info. + * + * \return 0 if succeeded, otherwise an error code: #eModifyKey_Returns. + */ eModifyKey_Returns ANIM_validate_keyingset(struct bContext *C, ListBase *dsources, struct KeyingSet *ks); -/* use the specified KeyingSet to add/remove various Keyframes on the specified frame */ +/** + * Use the specified #KeyingSet and context info (if required) + * to add/remove various Keyframes on the specified frame. + * + * Modify keyframes for the channels specified by the KeyingSet. + * This takes into account many of the different combinations of using KeyingSets. + * + * \returns the number of channels that key-frames were added or + * an #eModifyKey_Returns value (always a negative number). + */ int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, @@ -242,49 +317,88 @@ int ANIM_apply_keyingset(struct bContext *C, /* -------- */ -/* Get the first builtin KeyingSet with the given name, which occurs after the given one - * (or start of list if none given) */ +/** + * Find builtin #KeyingSet by name. + * + * \return 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, const char name[]); -/* Find KeyingSet type info given a name */ +/** + * Find KeyingSet type info given a name. + */ KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]); -/* Find a given ID in the KeyingSet */ +/** + * Check if the ID appears in the paths specified by the #KeyingSet. + */ bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id); -/* for RNA type registrations... */ +/** + * Add the given KeyingSetInfo to the list of type infos, + * and create an appropriate builtin set too. + */ void ANIM_keyingset_info_register(KeyingSetInfo *ksi); +/** + * Remove the given #KeyingSetInfo from the list of type infos, + * and also remove the builtin set if appropriate. + */ void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi); /* cleanup on exit */ +/* --------------- */ + void ANIM_keyingset_infos_exit(void); /* -------- */ -/* Get the active KeyingSet for the given scene */ +/** + * Get the active Keying Set for the given scene. + */ struct KeyingSet *ANIM_scene_get_active_keyingset(const struct Scene *scene); -/* Get the index of the Keying Set provided, for the given 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 */ +/** + * Get Keying Set to use for Auto-Key-Framing some transforms. + */ struct KeyingSet *ANIM_get_keyingset_for_autokeying(const struct Scene *scene, const char *transformKSName); -/* Dynamically populate an enum of Keying Sets */ +/** + * Dynamically populate an enum of Keying Sets. + */ const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, bool *r_free); -/* Use to get the keying set from the int value used by enums. */ +/** + * Get the keying set from enum values generated in #ANIM_keying_sets_enum_itemf. + * + * Type is the Keying Set the user specified to use when calling the operator: + * \param type: + * - == 0: use scene's active Keying Set. + * - > 0: use a user-defined Keying Set from the active scene. + * - < 0: use a builtin Keying Set. + */ KeyingSet *ANIM_keyingset_get_from_enum_type(struct Scene *scene, int type); KeyingSet *ANIM_keyingset_get_from_idname(struct Scene *scene, const char *idname); -/* Check if KeyingSet can be used in the current context */ +/** + * Check if #KeyingSet can be used in the current context. + */ bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks); -/* ************ Drivers ********************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Drivers + * \{ */ /* Flags for use by driver creation calls */ typedef enum eCreateDriverFlags { @@ -311,7 +425,10 @@ typedef enum eCreateDriver_MappingTypes { CREATEDRIVER_MAPPING_NONE_ALL = 4, } eCreateDriver_MappingTypes; -/* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */ +/** + * Mapping Types enum for operators. + * \note Used by #ANIM_OT_driver_button_add and #UI_OT_eyedropper_driver. + */ extern EnumPropertyItem prop_driver_create_mapping_types[]; /* -------- */ @@ -323,7 +440,11 @@ typedef enum eDriverFCurveCreationMode { DRIVER_FCURVE_EMPTY = 3 /* Add without data, for pasting. */ } eDriverFCurveCreationMode; -/* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools, +/** + * Get (or add relevant data to be able to do so) F-Curve from the driver stack, + * for the given Animation Data block. This assumes that all the destinations are valid. + * + * \note This low-level function shouldn't be used directly for most tools, * although there are special cases where this approach is preferable. */ struct FCurve *verify_driver_fcurve(struct ID *id, @@ -337,16 +458,18 @@ struct FCurve *alloc_driver_fcurve(const char rna_path[], /* -------- */ -/* 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. +/** + * \brief 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 + * \param flag: eCreateDriverFlags + * \param driver_type: eDriver_Types + * \param mapping_type: eCreateDriver_MappingTypes */ int ANIM_add_driver_with_target(struct ReportList *reports, struct ID *dst_id, @@ -361,8 +484,10 @@ int ANIM_add_driver_with_target(struct ReportList *reports, /* -------- */ -/* Main Driver Management API calls: - * Add a new driver for the specified property on the given ID block +/** + * \brief Main Driver Management API calls. + * + * Add a new driver for the specified property on the given ID block */ int ANIM_add_driver(struct ReportList *reports, struct ID *id, @@ -371,90 +496,128 @@ int ANIM_add_driver(struct ReportList *reports, short flag, int type); -/* Main Driver Management API calls: - * Remove the driver for the specified property on the given ID block (if available) +/** + * \brief Main Driver Management API calls. + * + * Remove the driver for the specified property on the given ID block (if available). */ 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 */ +/** + * Clear copy-paste buffer for drivers. + * \note This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ANIM_drivers_copybuf_free(void); -/* Clear copy-paste buffer for driver variable sets */ +/** + * Clear copy-paste buffer for driver variable sets. + * \note This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ANIM_driver_vars_copybuf_free(void); /* -------- */ -/* Returns whether there is a driver in the copy/paste buffer to paste */ +/** + * 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 +/** + * \brief Main Driver Management API calls. + * + * Make a copy of the driver for the specified property on the given ID block. */ bool ANIM_copy_driver( struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); -/* Main Driver Management API calls: +/** + * \brief 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 + * with the driver + driver-curve data from the buffer. */ 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 */ +/** + * 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 */ +/** + * 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 */ +/** + * Paste the variables in the buffer to the given FCurve. + */ bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace); /* -------- */ -/* Create a driver & variable that reads the specified property, - * and store it in the buffers for Paste Driver and Paste Variables. */ +/** + * Create a driver & variable that reads the specified property, + * and store it in the buffers for Paste Driver and Paste Variables. + */ void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const char *var_name); -/* ************ Auto-Keyframing ********************** */ -/* Notes: +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Auto-Key-Framing + * + * Notes: * - All the defines for this (User-Pref settings and Per-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 - */ + * - Scene settings take precedence over those for user-preferences, with old files + * inheriting user-preferences settings for the scene settings + * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored as user-preferences. + * \{ */ -/* Auto-Keying macros for use by various tools */ -/* check if auto-keyframing is enabled (per scene takes precedence) */ +/* Auto-Keying macros for use by various tools. */ + +/** Check if auto-key-framing 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). */ +/** 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) */ +/** Check if a flag is set for auto-key-framing (per scene takes precedence). */ #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 */ +/** + * Auto-keyframing feature - checks for whether anything should be done for the current frame. + */ bool autokeyframe_cfra_can_key(const struct Scene *scene, struct ID *id); -/* ************ Keyframe Checking ******************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Keyframe Checking + * \{ */ -/* Lesser Keyframe Checking API call: - * - Used for the buttons to check for keyframes... +/** + * \brief Lesser Keyframe Checking API call. + * + * Checks if some F-Curve has a keyframe for a given frame. + * \note Used for the buttons to check for keyframes. */ bool fcurve_frame_has_keyframe(const struct FCurve *fcu, float frame, short filter); -/* Lesser Keyframe Checking API call: +/** + * \brief Lesser Keyframe Checking API call. + * * - Returns whether the current value of a given property differs from the interpolated value. * - Used for button drawing. */ @@ -464,18 +627,19 @@ bool fcurve_is_changed(struct PointerRNA ptr, const struct AnimationEvalContext *anim_eval_context); /** - * Main Keyframe Checking API call: + * \brief 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_scene_ctime_get() + * It is recommended to call this method over the other keyframe-checkers directly, + * in case some detail of the implementation changes... + * \param frame: The value of this is quite often result of #BKE_scene_ctime_get() */ bool id_frame_has_keyframe(struct ID *id, float frame, short filter); -/* filter flags for id_cfra_has_keyframe +/** + * Filter flags for #id_frame_has_keyframe. * - * WARNING: do not alter order of these, as also stored in files - * (for v3d->keyflags) + * \warning do not alter order of these, as also stored in files (for `v3d->keyflags`). */ typedef enum eAnimFilterFlags { /* general */ @@ -488,7 +652,8 @@ typedef enum eAnimFilterFlags { ANIMFILTER_KEYS_NOSKEY = (1 << 10), /* don't include shape keys (for geometry) */ } eAnimFilterFlags; -/* utility funcs for auto keyframe */ +/* Utility functions for auto key-frame. */ + bool ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, @@ -498,6 +663,9 @@ bool ED_autokeyframe_pchan(struct bContext *C, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks); +/** + * Use for auto-key-framing from the UI. + */ bool ED_autokeyframe_property(struct bContext *C, struct Scene *scene, PointerRNA *ptr, @@ -506,7 +674,8 @@ bool ED_autokeyframe_property(struct bContext *C, float cfra); /* Names for builtin keying sets so we don't confuse these with labels/text, - * defined in python script: keyingsets_builtins.py */ + * defined in python script: `keyingsets_builtins.py`. */ + #define ANIM_KS_LOCATION_ID "Location" #define ANIM_KS_ROTATION_ID "Rotation" #define ANIM_KS_SCALING_ID "Scaling" @@ -516,6 +685,8 @@ bool ED_autokeyframe_property(struct bContext *C, #define ANIM_KS_WHOLE_CHARACTER_ID "WholeCharacter" #define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID "WholeCharacterSelected" +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_markers.h b/source/blender/editors/include/ED_markers.h index 8c10a8e36fd..8e6961ffd6f 100644 --- a/source/blender/editors/include/ED_markers.h +++ b/source/blender/editors/include/ED_markers.h @@ -33,7 +33,9 @@ struct bAnimContext; struct bContext; struct wmKeyConfig; -/* Drawing API ------------------------------ */ +/* -------------------------------------------------------------------- */ +/** \name Drawing API + * \{ */ /* flags for drawing markers */ enum { @@ -42,37 +44,86 @@ enum { DRAW_MARKERS_MARGIN = (1 << 2), }; +/* Draw Scene-Markers in time window */ void ED_markers_draw(const struct bContext *C, int flag); -/* Backend API ----------------------------- */ +/** \} */ +/* -------------------------------------------------------------------- */ +/** \name Backend API + * \{ */ + +/** + * Public API for getting markers from context. + */ ListBase *ED_context_get_markers(const struct bContext *C); +/** + * Public API for getting markers from "animation" context. + */ ListBase *ED_animcontext_get_markers(const struct bAnimContext *ac); +/** + * Apply some transformation to markers after the fact + * + * \param markers: List of markers to affect - this may or may not be the scene markers list, + * so don't assume anything. + * \param scene: Current scene (for getting current frame) + * \param mode: (TfmMode) transform mode that this transform is for + * \param value: From the transform code, this is `t->vec[0]` + * (which is delta transform for grab/extend, and scale factor for scale) + * \param side: (B/L/R) for 'extend' functionality, which side of current frame to use + */ int ED_markers_post_apply_transform( ListBase *markers, struct Scene *scene, int mode, float value, char side); +/** + * Get the marker that is closest to this point. + * XXX: for select, the min_dist should be small. + */ struct TimeMarker *ED_markers_find_nearest_marker(ListBase *markers, float x); +/** + * Return the time of the marker that occurs on a frame closest to the given time. + */ int ED_markers_find_nearest_marker_time(ListBase *markers, float x); void ED_markers_get_minmax(ListBase *markers, short sel, float *first, float *last); +/** + * This function makes a list of all the markers. The only_sel + * argument is used to specify whether only the selected markers + * are added. + */ void ED_markers_make_cfra_list(ListBase *markers, ListBase *lb, short sel); void ED_markers_deselect_all(ListBase *markers, int action); +/** + * Get the first selected marker. + */ struct TimeMarker *ED_markers_get_first_selected(ListBase *markers); -/* Operators ------------------------------ */ +/** \} */ -/* called in screen_ops.c:ED_operatortypes_screen() */ +/* -------------------------------------------------------------------- */ +/** \name Operators + * \{ */ + +/** + * Called in screen_ops.c:ED_operatortypes_screen(). + */ void ED_operatortypes_marker(void); -/* called in screen_ops.c:ED_keymap_screen() */ +/** + * Called in screen_ops.c:ED_keymap_screen(). + */ void ED_keymap_marker(struct wmKeyConfig *keyconf); -/* debugging only */ +/** + * Debugging only: print debugging prints of list of markers. + */ void debug_markers_print_list(struct ListBase *markers); +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_screen.h b/source/blender/editors/include/ED_screen.h index 76bbc899aba..c65ef3e397d 100644 --- a/source/blender/editors/include/ED_screen.h +++ b/source/blender/editors/include/ED_screen.h @@ -388,6 +388,10 @@ void ED_screens_navigation_bar_tools_menu_create(struct bContext *C, */ bool ED_screen_stereo3d_required(const struct bScreen *screen, const struct Scene *scene); Scene *ED_screen_scene_find(const struct bScreen *screen, const struct wmWindowManager *wm); +/** + * Find the scene displayed in \a screen. + * \note Assumes \a screen to be visible/active! + */ Scene *ED_screen_scene_find_with_window(const struct bScreen *screen, const struct wmWindowManager *wm, struct wmWindow **r_window); diff --git a/source/blender/editors/include/ED_view3d.h b/source/blender/editors/include/ED_view3d.h index 16f84ddc3cc..11a8b11c35a 100644 --- a/source/blender/editors/include/ED_view3d.h +++ b/source/blender/editors/include/ED_view3d.h @@ -108,6 +108,8 @@ bool ED_view3d_has_workbench_in_texture_color(const struct Scene *scene, const struct Object *ob, const struct View3D *v3d); /** + * Cursor position in `r_cursor_co`, result in `r_cursor_co`, `mval` in region coords. + * * \note cannot use `event->mval` here, called by #object_add(). */ void ED_view3d_cursor3d_position(struct bContext *C, -- cgit v1.2.3