diff options
Diffstat (limited to 'source/blender/editors')
28 files changed, 670 insertions, 524 deletions
diff --git a/source/blender/editors/animation/anim_markers.c b/source/blender/editors/animation/anim_markers.c index e12433f4d4c..baf3eaae8e2 100644 --- a/source/blender/editors/animation/anim_markers.c +++ b/source/blender/editors/animation/anim_markers.c @@ -99,13 +99,11 @@ static ListBase *context_get_markers(Scene *scene, ScrArea *area) /* ............. */ -/* public API for getting markers from context */ ListBase *ED_context_get_markers(const bContext *C) { return context_get_markers(CTX_data_scene(C), CTX_wm_area(C)); } -/* public API for getting markers from "animation" context */ ListBase *ED_animcontext_get_markers(const bAnimContext *ac) { if (ac) { @@ -116,17 +114,6 @@ ListBase *ED_animcontext_get_markers(const 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, Scene *scene, int mode, float value, char side) { @@ -168,8 +155,6 @@ int ED_markers_post_apply_transform( /* --------------------------------- */ -/* Get the marker that is closest to this point */ -/* XXX for select, the min_dist should be small */ TimeMarker *ED_markers_find_nearest_marker(ListBase *markers, float x) { TimeMarker *marker, *nearest = NULL; @@ -189,7 +174,6 @@ TimeMarker *ED_markers_find_nearest_marker(ListBase *markers, float x) return nearest; } -/* 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) { TimeMarker *nearest = ED_markers_find_nearest_marker(markers, x); @@ -323,10 +307,6 @@ static void add_marker_to_cfra_elem(ListBase *lb, TimeMarker *marker, short only cen->sel = marker->flag; } -/* 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 only_sel) { TimeMarker *marker; @@ -375,7 +355,6 @@ void ED_markers_deselect_all(ListBase *markers, int action) /* --------------------------------- */ -/* Get the first selected marker */ TimeMarker *ED_markers_get_first_selected(ListBase *markers) { TimeMarker *marker; @@ -393,12 +372,11 @@ TimeMarker *ED_markers_get_first_selected(ListBase *markers) /* --------------------------------- */ -/* Print debugging prints of list of markers - * BSI's: do NOT make static or put in if-defs as "unused code". - * That's too much trouble when we need to use for quick debugging! - */ void debug_markers_print_list(ListBase *markers) { + /* NOTE: do NOT make static or put in if-defs as "unused code". + * That's too much trouble when we need to use for quick debugging! */ + TimeMarker *marker; if (markers == NULL) { @@ -564,7 +542,6 @@ static void get_marker_clip_frame_range(View2D *v2d, float xscale, int r_range[2 r_range[1] = v2d->cur.xmax + font_width_max; } -/* Draw Scene-Markers in time window */ void ED_markers_draw(const bContext *C, int flag) { ListBase *markers = ED_context_get_markers(C); @@ -1699,7 +1676,6 @@ static void MARKER_OT_camera_bind(wmOperatorType *ot) /* ************************** registration **********************************/ -/* called in screen_ops.c:ED_operatortypes_screen() */ void ED_operatortypes_marker(void) { WM_operatortype_append(MARKER_OT_add); @@ -1716,7 +1692,6 @@ void ED_operatortypes_marker(void) #endif } -/* called in screen_ops.c:ED_keymap_screen() */ void ED_keymap_marker(wmKeyConfig *keyconf) { WM_keymap_ensure(keyconf, "Markers", 0, 0); diff --git a/source/blender/editors/animation/drivers.c b/source/blender/editors/animation/drivers.c index dbf379971fa..f509898f2ee 100644 --- a/source/blender/editors/animation/drivers.c +++ b/source/blender/editors/animation/drivers.c @@ -61,9 +61,6 @@ /* ************************************************** */ /* Animation Data Validation */ -/* 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. - */ FCurve *verify_driver_fcurve(ID *id, const char rna_path[], const int array_index, @@ -295,17 +292,6 @@ static int add_driver_with_target(ReportList *UNUSED(reports), return (fcu != NULL); } -/* 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(ReportList *reports, ID *dst_id, const char dst_path[], @@ -420,10 +406,6 @@ int ANIM_add_driver_with_target(ReportList *reports, /* --------------------------------- */ -/** - * Main Driver Management API calls: - * Add a new driver for the specified property on the given ID block - */ int ANIM_add_driver( ReportList *reports, ID *id, const char rna_path[], int array_index, short flag, int type) { @@ -546,9 +528,6 @@ int ANIM_add_driver( return done_tot; } -/* Main Driver Management API calls: - * Remove the driver for the specified property on the given ID block (if available) - */ bool ANIM_remove_driver(ReportList *UNUSED(reports), ID *id, const char rna_path[], @@ -603,7 +582,6 @@ bool ANIM_remove_driver(ReportList *UNUSED(reports), /* Copy/Paste Buffer for Driver Data... */ static FCurve *channeldriver_copypaste_buf = NULL; -/* This function frees any MEM_calloc'ed copy/paste buffer data */ void ANIM_drivers_copybuf_free(void) { /* free the buffer F-Curve if it exists, as if it were just another F-Curve */ @@ -613,7 +591,6 @@ void ANIM_drivers_copybuf_free(void) channeldriver_copypaste_buf = NULL; } -/* Checks if there is a driver in the copy/paste buffer */ bool ANIM_driver_can_paste(void) { return (channeldriver_copypaste_buf != NULL); @@ -621,9 +598,6 @@ 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 - */ bool ANIM_copy_driver( ReportList *reports, ID *id, const char rna_path[], int array_index, short UNUSED(flag)) { @@ -672,10 +646,6 @@ bool ANIM_copy_driver( return 0; } -/* 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 - */ bool ANIM_paste_driver( ReportList *reports, ID *id, const char rna_path[], int array_index, short UNUSED(flag)) { @@ -733,7 +703,6 @@ bool ANIM_paste_driver( /* Copy/Paste Buffer for Driver Variables... */ static ListBase driver_vars_copybuf = {NULL, NULL}; -/* This function frees any MEM_calloc'ed copy/paste buffer data */ void ANIM_driver_vars_copybuf_free(void) { /* Free the driver variables kept in the buffer */ @@ -750,7 +719,6 @@ void ANIM_driver_vars_copybuf_free(void) BLI_listbase_clear(&driver_vars_copybuf); } -/* Checks if there are driver variables in the copy/paste buffer */ bool ANIM_driver_vars_can_paste(void) { return (BLI_listbase_is_empty(&driver_vars_copybuf) == false); @@ -758,7 +726,6 @@ bool ANIM_driver_vars_can_paste(void) /* -------------------------------------------------- */ -/* Copy the given driver's variables to the buffer */ bool ANIM_driver_vars_copy(ReportList *reports, FCurve *fcu) { /* sanity checks */ @@ -781,7 +748,6 @@ bool ANIM_driver_vars_copy(ReportList *reports, FCurve *fcu) return (BLI_listbase_is_empty(&driver_vars_copybuf) == false); } -/* Paste the variables in the buffer to the given FCurve */ bool ANIM_driver_vars_paste(ReportList *reports, FCurve *fcu, bool replace) { ChannelDriver *driver = (fcu) ? fcu->driver : NULL; @@ -837,8 +803,6 @@ bool ANIM_driver_vars_paste(ReportList *reports, 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. */ void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const char *var_name) { /* Clear copy/paste buffer first (for consistency with other copy/paste buffers). */ @@ -882,13 +846,8 @@ void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const ch /* Add Driver - Enum Defines ------------------------- */ -/** - * Mapping Types enum for operators. - * \note Used by #ANIM_OT_driver_button_add and #UI_OT_eyedropper_driver. - * - * XXX: These names need reviewing. - */ EnumPropertyItem prop_driver_create_mapping_types[] = { + /* XXX: These names need reviewing. */ {CREATEDRIVER_MAPPING_1_N, "SINGLE_MANY", 0, diff --git a/source/blender/editors/animation/keyframes_edit.c b/source/blender/editors/animation/keyframes_edit.c index 0923d490110..145d67b7810 100644 --- a/source/blender/editors/animation/keyframes_edit.c +++ b/source/blender/editors/animation/keyframes_edit.c @@ -67,10 +67,6 @@ /* --------------------------- Base Functions ------------------------------------ */ -/* 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. - */ -/* TODO: make this function work on samples too. */ short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, FCurve *fcu, KeyframeEditFunc key_ok, @@ -378,7 +374,6 @@ static short summary_keyframes_loop(KeyframeEditData *ked, /* --- */ -/* This function is used to apply operation to all keyframes, regardless of the type */ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, bDopeSheet *ads, bAnimListElem *ale, @@ -416,8 +411,6 @@ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, return 0; } -/* This function is used to apply operation to all keyframes, - * regardless of the type without needed an AnimListElem wrapper */ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, bDopeSheet *ads, void *data, @@ -477,8 +470,6 @@ void ANIM_animdata_keyframe_callback(bAnimContext *ac, /* ************************************************************************** */ /* Keyframe Integrity Tools */ -/* Rearrange keyframes if some are out of order */ -/* used to be recalc_*_ipos() where * was object or action */ void ANIM_editkeyframes_refresh(bAnimContext *ac) { ListBase anim_data = {NULL, NULL}; @@ -620,9 +611,6 @@ static short ok_bezier_region(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/** - * Called from #ok_bezier_region_lasso and #ok_bezier_channel_lasso - */ bool keyframe_region_lasso_test(const KeyframeEdit_LassoData *data_lasso, const float xy[2]) { if (BLI_rctf_isect_pt_v(data_lasso->rectf_scaled, xy)) { @@ -683,9 +671,6 @@ static short ok_bezier_channel_lasso(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/** - * Called from #ok_bezier_region_circle and #ok_bezier_channel_circle - */ bool keyframe_region_circle_test(const KeyframeEdit_CircleData *data_circle, const float xy[2]) { if (BLI_rctf_isect_pt_v(data_circle->rectf_scaled, xy)) { @@ -787,10 +772,6 @@ KeyframeEditFunc ANIM_editkeyframes_ok(short mode) /* ******************************************* */ /* Assorted Utility Functions */ -/** - * Helper callback for <animeditor>_cfrasnap_exec() -> - * used to help get the average time of all selected beztriples - */ short bezt_calc_average(KeyframeEditData *ked, BezTriple *bezt) { /* only if selected */ @@ -810,8 +791,6 @@ short bezt_calc_average(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/* helper callback for columnselect_<animeditor>_keys() -> populate - * list CfraElems with frame numbers from selected beztriples */ short bezt_to_cfraelem(KeyframeEditData *ked, BezTriple *bezt) { /* only if selected */ @@ -825,9 +804,6 @@ short bezt_to_cfraelem(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/* used to remap times from one range to another - * requires: ked->data = KeyframeEditCD_Remap - */ void bezt_remap_times(KeyframeEditData *ked, BezTriple *bezt) { KeyframeEditCD_Remap *rmap = (KeyframeEditCD_Remap *)ked->data; @@ -1024,8 +1000,6 @@ static short mirror_bezier_value(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/* NOTE: for markers and 'value', the values to use must be supplied as the first float value. */ -/* calchandles_fcurve */ KeyframeEditFunc ANIM_editkeyframes_mirror(short mode) { switch (mode) { @@ -1183,8 +1157,6 @@ static short set_bezier_free(KeyframeEditData *UNUSED(ked), BezTriple *bezt) return 0; } -/* Set all selected Bezier Handles to a single type */ -/* calchandles_fcurve */ KeyframeEditFunc ANIM_editkeyframes_handles(short mode) { switch (mode) { @@ -1311,8 +1283,6 @@ static short set_bezt_sine(KeyframeEditData *UNUSED(ked), BezTriple *bezt) return 0; } -/* Set the interpolation type of the selected BezTriples in each F-Curve to the specified one */ -/* ANIM_editkeyframes_ipocurve_ipotype() ! */ KeyframeEditFunc ANIM_editkeyframes_ipo(short mode) { switch (mode) { @@ -1391,7 +1361,6 @@ static short set_keytype_moving_hold(KeyframeEditData *UNUSED(ked), BezTriple *b return 0; } -/* Set the interpolation type of the selected BezTriples in each F-Curve to the specified one */ KeyframeEditFunc ANIM_editkeyframes_keytype(short mode) { switch (mode) { @@ -1447,7 +1416,6 @@ static short set_easingtype_easeauto(KeyframeEditData *UNUSED(ked), BezTriple *b return 0; } -/* Set the easing type of the selected BezTriples in each F-Curve to the specified one */ KeyframeEditFunc ANIM_editkeyframes_easing(short mode) { switch (mode) { @@ -1638,7 +1606,6 @@ static short selmap_build_bezier_less(KeyframeEditData *ked, BezTriple *bezt) return 0; } -/* Get callback for building selection map */ KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode) { switch (mode) { @@ -1653,7 +1620,6 @@ KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode) /* ----------- */ -/* flush selection map values to the given beztriple */ short bezt_selmap_flush(KeyframeEditData *ked, BezTriple *bezt) { const char *map = ked->data; diff --git a/source/blender/editors/animation/keyframes_general.c b/source/blender/editors/animation/keyframes_general.c index 03862405e75..dc5d71b5a1e 100644 --- a/source/blender/editors/animation/keyframes_general.c +++ b/source/blender/editors/animation/keyframes_general.c @@ -63,11 +63,6 @@ /* **************************************************** */ -/** - * Only delete the nominated keyframe from provided F-Curve. - * Not recommended to be used many times successively. For that - * there is #delete_fcurve_keys(). - */ void delete_fcurve_key(FCurve *fcu, int index, bool do_recalc) { /* sanity check */ @@ -101,7 +96,6 @@ void delete_fcurve_key(FCurve *fcu, int index, bool do_recalc) } } -/* Delete selected keyframes in given F-Curve */ bool delete_fcurve_keys(FCurve *fcu) { bool changed = false; @@ -140,7 +134,6 @@ void clear_fcurve_keys(FCurve *fcu) /* ---------------- */ -/* duplicate selected keyframes for the given F-Curve */ void duplicate_fcurve_keys(FCurve *fcu) { /* this can only work when there is an F-Curve, and also when there are some BezTriples */ @@ -176,10 +169,6 @@ void duplicate_fcurve_keys(FCurve *fcu) /* **************************************************** */ /* Various Tools */ -/** - * Basic F-Curve 'cleanup' function that removes 'double points' and unnecessary keyframes on - * linear-segments only optionally clears up curve if one keyframe with default value remains. - */ void clean_fcurve(struct bAnimContext *ac, bAnimListElem *ale, float thresh, bool cleardefault) { FCurve *fcu = (FCurve *)ale->key_data; @@ -429,13 +418,6 @@ static void decimate_fcurve_segment(FCurve *fcu, target_fcurve_verts); } -/** - * F-Curve 'decimate' function that removes a certain ratio of curve - * points that will affect the curves overall shape the least. - * If you want to remove based on a error margin, set remove_ratio to 1 and - * simply specify the desired error_sq_max. Otherwise, set the error margin to - * FLT_MAX. - */ bool decimate_fcurve(bAnimListElem *ale, float remove_ratio, float error_sq_max) { FCurve *fcu = (FCurve *)ale->key_data; @@ -495,8 +477,6 @@ typedef struct tSmooth_Bezt { float y1, y2, y3; /* averaged before/new/after y-values */ } tSmooth_Bezt; -/* Use a weighted moving-means method to reduce intensity of fluctuations */ -/* TODO: introduce scaling factor for weighting falloff */ void smooth_fcurve(FCurve *fcu) { int totSel = 0; @@ -600,7 +580,6 @@ typedef struct TempFrameValCache { float frame, val; } TempFrameValCache; -/* Evaluates the curves between each selected keyframe on each frame, and keys the value. */ void sample_fcurve(FCurve *fcu) { BezTriple *bezt, *start = NULL, *end = NULL; @@ -709,7 +688,6 @@ typedef struct tAnimCopybufItem { bool is_bone; /* special flag for armature bones */ } tAnimCopybufItem; -/* This function frees any MEM_calloc'ed copy/paste buffer data */ void ANIM_fcurves_copybuf_free(void) { tAnimCopybufItem *aci, *acn; @@ -740,7 +718,6 @@ void ANIM_fcurves_copybuf_free(void) /* ------------------- */ -/* This function adds data to the keyframes copy/paste buffer, freeing existing data first */ short copy_animedit_keys(bAnimContext *ac, ListBase *anim_data) { bAnimListElem *ale; @@ -1099,8 +1076,6 @@ static void paste_animedit_keys_fcurve( calchandles_fcurve(fcu); } -/* ------------------- */ - const EnumPropertyItem rna_enum_keyframe_paste_offset_items[] = { {KEYFRAME_PASTE_OFFSET_CFRA_START, "START", @@ -1133,11 +1108,6 @@ const EnumPropertyItem rna_enum_keyframe_paste_merge_items[] = { {0, NULL, 0, NULL, NULL}, }; -/** - * This function pastes data from the keyframes copy/paste buffer - * - * \return Status code is whether the method FAILED to do anything - */ short paste_animedit_keys(bAnimContext *ac, ListBase *anim_data, const eKeyPasteOffset offset_mode, diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c index 95d1ca1e7a6..25d2f6c510b 100644 --- a/source/blender/editors/animation/keyframing.c +++ b/source/blender/editors/animation/keyframing.c @@ -91,7 +91,6 @@ static int delete_key_using_keying_set(bContext *C, wmOperator *op, KeyingSet *k /* ************************************************** */ /* Keyframing Setting Wrangling */ -/* Get the active settings for keyframing settings from context (specifically the given scene) */ eInsertKeyFlags ANIM_get_keyframing_flags(Scene *scene, const bool use_autokey_mode) { eInsertKeyFlags flag = INSERTKEY_NOFLAGS; @@ -133,9 +132,6 @@ eInsertKeyFlags ANIM_get_keyframing_flags(Scene *scene, const bool use_autokey_m /* ******************************************* */ /* Animation Data Validation */ -/* 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. - */ bAction *ED_id_action_ensure(Main *bmain, ID *id) { AnimData *adt; @@ -177,10 +173,6 @@ bAction *ED_id_action_ensure(Main *bmain, ID *id) return adt->action; } -/** - * Find the F-Curve from the Active Action, - * for the given Animation Data block. This assumes that all the destinations are valid. - */ FCurve *ED_action_fcurve_find(struct bAction *act, const char rna_path[], const int array_index) { /* Sanity checks. */ @@ -190,10 +182,6 @@ FCurve *ED_action_fcurve_find(struct bAction *act, const char rna_path[], const return BKE_fcurve_find(&act->curves, rna_path, array_index); } -/** - * 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. - */ FCurve *ED_action_fcurve_ensure(struct Main *bmain, struct bAction *act, const char group[], @@ -295,9 +283,6 @@ static void update_autoflags_fcurve_direct(FCurve *fcu, PropertyRNA *prop) } } -/* 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(FCurve *fcu, bContext *C, ReportList *reports, PointerRNA *ptr) { PointerRNA tmp_ptr; @@ -433,13 +418,6 @@ static void replace_bezt_keyframe_ypos(BezTriple *dst, const BezTriple *bezt) /* TODO: perform some other operations? */ } -/* 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(FCurve *fcu, const BezTriple *bezt, eInsertKeyFlags flag) { int i = 0; @@ -575,15 +553,6 @@ static void subdivide_nonauto_handles(const FCurve *fcu, bezt->h1 = bezt->h2 = HD_ALIGN; } -/** - * 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( FCurve *fcu, float x, float y, eBezTriple_KeyframeType keyframe_type, eInsertKeyFlags flag) { @@ -1273,19 +1242,6 @@ static bool insert_keyframe_value(ReportList *reports, return insert_vert_fcurve(fcu, cfra, curval, keytype, flag) >= 0; } -/* Secondary Keyframing 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. - * - * keytype is the "keyframe type" (eBezTriple_KeyframeType), as shown in the Dope Sheet. - * - * The flag argument is used for special settings that alter the behavior of - * the keyframe insertion. These include the 'visual' keyframing modes, quick refresh, - * and extra keyframe filtering. - */ bool insert_keyframe_direct(ReportList *reports, PointerRNA ptr, PropertyRNA *prop, @@ -1453,19 +1409,6 @@ static AnimationEvalContext nla_time_remap(const AnimationEvalContext *anim_eval return *anim_eval_context; } -/** - * Main Keyframing API call - * - * Use this when validation of necessary animation data is necessary, since it may not exist yet. - * - * The flag argument is used for special settings that alter the behavior of - * the keyframe insertion. These include the 'visual' keyframing modes, quick refresh, - * and extra keyframe filtering. - * - * index of -1 keys all array indices - * - * \return The number of key-frames inserted. - */ int insert_keyframe(Main *bmain, ReportList *reports, ID *id, @@ -1692,9 +1635,6 @@ static void deg_tag_after_keyframe_delete(Main *bmain, ID *id, AnimData *adt) } } -/** - * \return The number of key-frames deleted. - */ int delete_keyframe(Main *bmain, ReportList *reports, ID *id, @@ -2016,7 +1956,6 @@ void ANIM_OT_keyframe_insert(wmOperatorType *ot) ot->prop = prop; } -/* Clone of 'ANIM_OT_keyframe_insert' which uses a name for the keying set instead of an enum. */ void ANIM_OT_keyframe_insert_by_name(wmOperatorType *ot) { PropertyRNA *prop; @@ -2811,7 +2750,6 @@ bool autokeyframe_cfra_can_key(const Scene *scene, ID *id) /* --------------- API/Per-Datablock Handling ------------------- */ -/* Checks if some F-Curve has a keyframe for a given frame */ bool fcurve_frame_has_keyframe(const FCurve *fcu, float frame, short filter) { /* quick sanity check */ @@ -2838,7 +2776,6 @@ bool fcurve_frame_has_keyframe(const FCurve *fcu, float frame, short filter) return false; } -/* Returns whether the current value of a given property differs from the interpolated value. */ bool fcurve_is_changed(PointerRNA ptr, PropertyRNA *prop, FCurve *fcu, @@ -2967,7 +2904,6 @@ static bool object_frame_has_keyframe(Object *ob, float frame, short filter) /* --------------- API ------------------- */ -/* Checks whether a keyframe exists for the given ID-block one the given frame */ bool id_frame_has_keyframe(ID *id, float frame, short filter) { /* sanity checks */ @@ -3043,9 +2979,6 @@ bool ED_autokeyframe_pchan( return false; } -/** - * Use for auto-keyframing from the UI. - */ bool ED_autokeyframe_property( bContext *C, Scene *scene, PointerRNA *ptr, PropertyRNA *prop, int rnaindex, float cfra) { diff --git a/source/blender/editors/animation/keyingsets.c b/source/blender/editors/animation/keyingsets.c index e1fd3b07f46..59bb60d8fa0 100644 --- a/source/blender/editors/animation/keyingsets.c +++ b/source/blender/editors/animation/keyingsets.c @@ -529,12 +529,10 @@ void ANIM_OT_keying_set_active_set(wmOperatorType *ot) /* Keying Set Type Info declarations */ static ListBase keyingset_type_infos = {NULL, NULL}; -/* Built-In Keying Sets (referencing type information). */ ListBase builtin_keyingsets = {NULL, NULL}; /* --------------- */ -/* Find KeyingSet type info given a name. */ KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]) { /* sanity checks */ @@ -546,7 +544,6 @@ KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]) return BLI_findstring(&keyingset_type_infos, name, offsetof(KeyingSetInfo, idname)); } -/* Find builtin KeyingSet by name. */ KeyingSet *ANIM_builtin_keyingset_get_named(KeyingSet *prevKS, const char name[]) { KeyingSet *ks, *first = NULL; @@ -582,8 +579,6 @@ KeyingSet *ANIM_builtin_keyingset_get_named(KeyingSet *prevKS, const char name[] /* --------------- */ -/* Add the given KeyingSetInfo to the list of type infos, - * and create an appropriate builtin set too. */ void ANIM_keyingset_info_register(KeyingSetInfo *ksi) { KeyingSet *ks; @@ -603,8 +598,6 @@ void ANIM_keyingset_info_register(KeyingSetInfo *ksi) BLI_addtail(&keyingset_type_infos, ksi); } -/* Remove the given KeyingSetInfo from the list of type infos, - * and also remove the builtin set if appropriate. */ void ANIM_keyingset_info_unregister(Main *bmain, KeyingSetInfo *ksi) { KeyingSet *ks, *ksn; @@ -633,8 +626,6 @@ void ANIM_keyingset_info_unregister(Main *bmain, KeyingSetInfo *ksi) BLI_freelinkN(&keyingset_type_infos, ksi); } -/* --------------- */ - void ANIM_keyingset_infos_exit(void) { KeyingSetInfo *ksi, *next; @@ -654,7 +645,6 @@ void ANIM_keyingset_infos_exit(void) BKE_keyingsets_free(&builtin_keyingsets); } -/* Check if the ID appears in the paths specified by the KeyingSet */ bool ANIM_keyingset_find_id(KeyingSet *ks, ID *id) { /* sanity checks */ @@ -670,7 +660,6 @@ bool ANIM_keyingset_find_id(KeyingSet *ks, ID *id) /* Getters for Active/Indices ----------------------------- */ -/* Get the active Keying Set for the Scene provided */ KeyingSet *ANIM_scene_get_active_keyingset(const Scene *scene) { /* if no scene, we've got no hope of finding the Keying Set */ @@ -689,7 +678,6 @@ KeyingSet *ANIM_scene_get_active_keyingset(const Scene *scene) return BLI_findlink(&builtin_keyingsets, (-scene->active_keyingset) - 1); } -/* Get the index of the Keying Set provided, for the given Scene */ int ANIM_scene_get_keyingset_index(Scene *scene, KeyingSet *ks) { int index; @@ -721,7 +709,6 @@ int ANIM_scene_get_keyingset_index(Scene *scene, KeyingSet *ks) return 0; } -/* Get Keying Set to use for Auto-Keyframing some transforms */ KeyingSet *ANIM_get_keyingset_for_autokeying(const Scene *scene, const char *transformKSName) { /* get KeyingSet to use @@ -739,7 +726,6 @@ KeyingSet *ANIM_get_keyingset_for_autokeying(const Scene *scene, const char *tra /* Menu of All Keying Sets ----------------------------- */ -/* Dynamically populate an enum of Keying Sets */ const EnumPropertyItem *ANIM_keying_sets_enum_itemf(bContext *C, PointerRNA *UNUSED(ptr), PropertyRNA *UNUSED(prop), @@ -808,14 +794,6 @@ const EnumPropertyItem *ANIM_keying_sets_enum_itemf(bContext *C, return item; } -/** - * 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: - * - type == 0: use scene's active Keying Set - * - type > 0: use a user-defined Keying Set from the active scene - * - type < 0: use a builtin Keying Set - */ KeyingSet *ANIM_keyingset_get_from_enum_type(Scene *scene, int type) { KeyingSet *ks = NULL; @@ -847,7 +825,6 @@ KeyingSet *ANIM_keyingset_get_from_idname(Scene *scene, const char *idname) /* Polling API ----------------------------------------------- */ -/* Check if KeyingSet can be used in the current context */ bool ANIM_keyingset_context_ok_poll(bContext *C, KeyingSet *ks) { if ((ks->flag & KEYINGSET_ABSOLUTE) == 0) { @@ -894,7 +871,6 @@ static void RKS_ITER_overrides_list(KeyingSetInfo *ksi, } } -/* Add new data source for relative Keying Sets */ void ANIM_relative_keyingset_add_source(ListBase *dsources, ID *id, StructRNA *srna, void *data) { tRKS_DSource *ds; @@ -925,14 +901,6 @@ void ANIM_relative_keyingset_add_source(ListBase *dsources, ID *id, StructRNA *s /* KeyingSet Operations (Insert/Delete Keyframes) ------------ */ -/** - * 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. - * - * Returns 0 if succeeded, otherwise an error code: eModifyKey_Returns - */ eModifyKey_Returns ANIM_validate_keyingset(bContext *C, ListBase *dsources, KeyingSet *ks) { /* sanity check */ @@ -1017,14 +985,6 @@ static eInsertKeyFlags keyingset_apply_keying_flags(const eInsertKeyFlags base_f return result; } -/** - * Given a KeyingSet and context info (if required), - * 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( bContext *C, ListBase *dsources, bAction *act, KeyingSet *ks, short mode, float cfra) { diff --git a/source/blender/editors/armature/armature_add.c b/source/blender/editors/armature/armature_add.c index 21a5c6c2865..02ecfdb4ea6 100644 --- a/source/blender/editors/armature/armature_add.c +++ b/source/blender/editors/armature/armature_add.c @@ -64,8 +64,6 @@ /* *************** Adding stuff in editmode *************** */ -/* default bone add, returns it selected, but without tail set */ -/* XXX should be used everywhere, now it mallocs bones still locally in functions */ EditBone *ED_armature_ebone_add(bArmature *arm, const char *name) { EditBone *bone = MEM_callocN(sizeof(EditBone), "eBone"); @@ -274,7 +272,6 @@ void ARMATURE_OT_click_extrude(wmOperatorType *ot) /* props */ } -/* adds an EditBone between the nominated locations (should be in the right space) */ EditBone *add_points_bone(Object *obedit, float head[3], float tail[3]) { EditBone *ebo; @@ -302,7 +299,6 @@ static EditBone *get_named_editbone(ListBase *edbo, const char *name) return NULL; } -/* Call this before doing any duplications. */ void preEditBoneDuplicate(ListBase *editbones) { /* clear temp */ @@ -1317,9 +1313,10 @@ static int armature_symmetrize_exec(bContext *C, wmOperator *op) return OPERATOR_FINISHED; } -/* following conventions from #MESH_OT_symmetrize */ void ARMATURE_OT_symmetrize(wmOperatorType *ot) { + /* NOTE: following conventions from #MESH_OT_symmetrize */ + /* subset of 'rna_enum_symmetrize_direction_items' */ static const EnumPropertyItem arm_symmetrize_direction_items[] = { {-1, "NEGATIVE_X", 0, "-X to +X", ""}, diff --git a/source/blender/editors/armature/armature_edit.c b/source/blender/editors/armature/armature_edit.c index fd5ae6c7099..b709980cabe 100644 --- a/source/blender/editors/armature/armature_edit.c +++ b/source/blender/editors/armature/armature_edit.c @@ -66,9 +66,6 @@ /* NOTE: these functions are exported to the Object module to be called from the tools there */ -/** - * See #BKE_armature_transform for object-mode transform. - */ void ED_armature_edit_transform(bArmature *arm, const float mat[4][4], const bool do_props) { EditBone *ebone; @@ -116,8 +113,6 @@ void ED_armature_transform(bArmature *arm, const float mat[4][4], const bool do_ } } -/* exported for use in editors/object/ */ -/* 0 == do center, 1 == center new, 2 == center cursor */ void ED_armature_origin_set( Main *bmain, Object *ob, const float cursor[3], int centermode, int around) { @@ -186,9 +181,6 @@ void ED_armature_origin_set( /** \name Bone Roll Calculate Operator * \{ */ -/* adjust bone roll to align Z axis with vector - * vec is in local space and is normalized - */ float ED_armature_ebone_roll_to_vector(const EditBone *bone, const float align_axis[3], const bool axis_only) diff --git a/source/blender/editors/armature/armature_intern.h b/source/blender/editors/armature/armature_intern.h index 3a6761ba915..77607cedcb1 100644 --- a/source/blender/editors/armature/armature_intern.h +++ b/source/blender/editors/armature/armature_intern.h @@ -39,8 +39,10 @@ struct bArmature; struct LinkData; struct ListBase; -/* ******************************************************* */ -/* Armature EditMode Operators */ +/* -------------------------------------------------------------------- */ +/** \name Armature EditMode Operators + * \{ */ + void ARMATURE_OT_bone_primitive_add(struct wmOperatorType *ot); void ARMATURE_OT_align(struct wmOperatorType *ot); @@ -82,8 +84,12 @@ void ARMATURE_OT_layers_show_all(struct wmOperatorType *ot); void ARMATURE_OT_armature_layers(struct wmOperatorType *ot); void ARMATURE_OT_bone_layers(struct wmOperatorType *ot); -/* ******************************************************* */ -/* Pose-Mode Operators */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Pose-Mode Operators + * \{ */ + void POSE_OT_hide(struct wmOperatorType *ot); void POSE_OT_reveal(struct wmOperatorType *ot); @@ -131,8 +137,12 @@ void POSE_OT_quaternions_flip(struct wmOperatorType *ot); void POSE_OT_bone_layers(struct wmOperatorType *ot); -/* ******************************************************* */ -/* Pose Tool Utilities (for PoseLib, Pose Sliding, etc.) */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Pose Tool Utilities (for PoseLib, Pose Sliding, etc.) + * \{ */ + /* pose_utils.c */ /* Temporary data linking PoseChannels with the F-Curves they affect */ @@ -173,21 +183,39 @@ typedef struct tPChanFCurveLink { /* ----------- */ +/** Returns a valid pose armature for this object, else returns NULL. */ struct Object *poseAnim_object_get(struct Object *ob_); +/** Get sets of F-Curves providing transforms for the bones in the Pose. */ void poseAnim_mapping_get(struct bContext *C, ListBase *pfLinks); +/** Free F-Curve <-> PoseChannel links. */ void poseAnim_mapping_free(ListBase *pfLinks); +/** + * Helper for apply() / reset() - refresh the data. + */ void poseAnim_mapping_refresh(struct bContext *C, struct Scene *scene, struct Object *ob); +/** + * Reset changes made to current pose. + */ void poseAnim_mapping_reset(ListBase *pfLinks); +/** Perform auto-key-framing after changes were made + confirmed. */ void poseAnim_mapping_autoKeyframe(struct bContext *C, struct Scene *scene, ListBase *pfLinks, float cframe); +/** + * Find the next F-Curve for a PoseChannel with matching path... + * - path is not just the pfl rna_path, since that path doesn't have property info yet. + */ LinkData *poseAnim_mapping_getNextFCurve(ListBase *fcuLinks, LinkData *prev, const char *path); -/* ******************************************************* */ -/* PoseLib */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name PoseLib + * \{ */ + /* pose_lib.c */ void POSELIB_OT_new(struct wmOperatorType *ot); @@ -207,8 +235,12 @@ void POSELIB_OT_apply_pose(struct wmOperatorType *ot); void POSELIB_OT_apply_pose_asset(struct wmOperatorType *ot); void POSELIB_OT_blend_pose_asset(struct wmOperatorType *ot); -/* ******************************************************* */ -/* Pose Sliding Tools */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Pose Sliding Tools + * \{ */ + /* pose_slide.c */ void POSE_OT_push(struct wmOperatorType *ot); @@ -220,8 +252,11 @@ void POSE_OT_blend_to_neighbors(struct wmOperatorType *ot); void POSE_OT_propagate(struct wmOperatorType *ot); -/* ******************************************************* */ -/* Various Armature Edit/Pose Editing API's */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Various Armature Edit/Pose Editing API's + * \{ */ /* Ideally, many of these defines would not be needed as everything would be strictly * self-contained within each file, @@ -232,7 +267,9 @@ struct EditBone *make_boneList(struct ListBase *edbo, struct ListBase *bones, struct Bone *actBone); -/* duplicate method */ +/* Duplicate method. */ + +/** Call this before doing any duplications. */ void preEditBoneDuplicate(struct ListBase *editbones); void postEditBoneDuplicate(struct ListBase *editbones, struct Object *ob); struct EditBone *duplicateEditBone(struct EditBone *cur_bone, @@ -240,20 +277,29 @@ struct EditBone *duplicateEditBone(struct EditBone *cur_bone, struct ListBase *editbones, struct Object *ob); -/* duplicate method (cross objects) */ -/* editbones is the target list */ +/* Duplicate method (cross objects). */ + +/** + * \param editbones: The target list. + */ struct EditBone *duplicateEditBoneObjects(struct EditBone *cur_bone, const char *name, struct ListBase *editbones, struct Object *src_ob, struct Object *dst_ob); +/** Adds an EditBone between the nominated locations (should be in the right space). */ struct EditBone *add_points_bone(struct Object *obedit, float head[3], float tail[3]); void bone_free(struct bArmature *arm, struct EditBone *bone); void armature_tag_select_mirrored(struct bArmature *arm); +/** + * Helper function for tools to work on mirrored parts. + * it leaves mirrored bones selected then too, which is a good indication of what happened. + */ void armature_select_mirrored_ex(struct bArmature *arm, const int flag); void armature_select_mirrored(struct bArmature *arm); +/** Only works when tagged. */ void armature_tag_unselect(struct bArmature *arm); struct EditBone *ED_armature_pick_ebone(struct bContext *C, @@ -291,6 +337,10 @@ struct Bone *ED_armature_pick_bone_from_selectbuffer(struct Base **bases, bool do_nearest, struct Base **r_base); +/** + * XXX: bone_looper is only to be used when we want to access settings + * (i.e. editability/visibility/selected) that context doesn't offer. + */ int bone_looper(struct Object *ob, struct Bone *bone, void *data, diff --git a/source/blender/editors/armature/armature_naming.c b/source/blender/editors/armature/armature_naming.c index 9d251c52217..750c64d74a7 100644 --- a/source/blender/editors/armature/armature_naming.c +++ b/source/blender/editors/armature/armature_naming.c @@ -80,7 +80,6 @@ static bool editbone_unique_check(void *arg, const char *name) return dupli && dupli != data->bone; } -/* If bone is already in list, pass it as param to ignore it. */ void ED_armature_ebone_unique_name(ListBase *ebones, char *name, EditBone *bone) { struct { @@ -154,9 +153,6 @@ static void constraint_bone_name_fix(Object *ob, } } -/* called by UI for renaming a bone */ -/* warning: make sure the original bone was not renamed yet! */ -/* seems messy, but that's what you get with not using pointers but channel names :) */ void ED_armature_bone_rename(Main *bmain, bArmature *arm, const char *oldnamep, @@ -395,16 +391,6 @@ typedef struct BoneFlipNameData { char name_flip[MAXBONENAME]; } BoneFlipNameData; -/** - * 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 BoneConflict elems. - * \param do_strip_numbers: if set, try to get rid of dot-numbers at end of bone names. - */ void ED_armature_bones_flip_names(Main *bmain, bArmature *arm, ListBase *bones_names, diff --git a/source/blender/editors/armature/armature_ops.c b/source/blender/editors/armature/armature_ops.c index 75b0455d026..364e778fc2e 100644 --- a/source/blender/editors/armature/armature_ops.c +++ b/source/blender/editors/armature/armature_ops.c @@ -33,9 +33,10 @@ /* ************************** registration **********************************/ -/* Both operators ARMATURE_OT_xxx and POSE_OT_xxx here */ void ED_operatortypes_armature(void) { + /* Both operators `ARMATURE_OT_*` and `POSE_OT_*` are registered here. */ + /* EDIT ARMATURE */ WM_operatortype_append(ARMATURE_OT_bone_primitive_add); diff --git a/source/blender/editors/armature/armature_relations.c b/source/blender/editors/armature/armature_relations.c index b06e4b6a9e7..eebe8a447f7 100644 --- a/source/blender/editors/armature/armature_relations.c +++ b/source/blender/editors/armature/armature_relations.c @@ -269,7 +269,6 @@ static void joined_armature_fix_links( } } -/* join armature exec is exported for use in object->join objects operator... */ int ED_armature_join_objects_exec(bContext *C, wmOperator *op) { Main *bmain = CTX_data_main(C); diff --git a/source/blender/editors/armature/armature_select.c b/source/blender/editors/armature/armature_select.c index 937385f9ffa..5e4cb813064 100644 --- a/source/blender/editors/armature/armature_select.c +++ b/source/blender/editors/armature/armature_select.c @@ -139,7 +139,6 @@ Base *ED_armature_base_and_pchan_from_select_buffer(Base **bases, return base; } -/* For callers that don't need the pose channel. */ Base *ED_armature_base_and_bone_from_select_buffer(Base **bases, uint bases_len, int hit, @@ -1080,7 +1079,6 @@ bool ED_armature_edit_select_pick_bone(bContext *C, return true; } -/* context: editmode armature in view3d */ bool ED_armature_edit_select_pick( bContext *C, const int mval[2], bool extend, bool deselect, bool toggle) { @@ -1175,18 +1173,6 @@ static bool armature_edit_select_op_apply(bArmature *arm, return changed; } -/** - * 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(bArmature *arm, const int sel_op) { bool changed = false; diff --git a/source/blender/editors/armature/armature_utils.c b/source/blender/editors/armature/armature_utils.c index 4fe4422e4e0..1c48285563d 100644 --- a/source/blender/editors/armature/armature_utils.c +++ b/source/blender/editors/armature/armature_utils.c @@ -45,10 +45,10 @@ #include "armature_intern.h" -/* *************************************************************** */ -/* Validation */ +/* -------------------------------------------------------------------- */ +/** \name Validation + * \{ */ -/* Sync selection to parent for connected children */ void ED_armature_edit_sync_selection(ListBase *edbo) { EditBone *ebo; @@ -86,10 +86,6 @@ 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(bArmature *arm) { arm->layer_used = 0; @@ -98,11 +94,12 @@ void ED_armature_edit_refresh_layer_used(bArmature *arm) } } -/* *************************************************************** */ -/* Bone Operations */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Bone Operations + * \{ */ -/* XXX bone_looper is only to be used when we want to access settings - * (i.e. editability/visibility/selected) that context doesn't offer */ int bone_looper(Object *ob, Bone *bone, void *data, int (*bone_func)(Object *, Bone *, void *)) { /* We want to apply the function bone_func to every bone @@ -129,8 +126,11 @@ int bone_looper(Object *ob, Bone *bone, void *data, int (*bone_func)(Object *, B return count; } -/* *************************************************************** */ -/* Bone Removal */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Bone Removal + * \{ */ void bone_free(bArmature *arm, EditBone *bone) { @@ -155,9 +155,6 @@ void bone_free(bArmature *arm, EditBone *bone) BLI_freelinkN(arm->edbo, bone); } -/** - * \param clear_connected: When false caller is responsible for keeping the flag in a valid state. - */ void ED_armature_ebone_remove_ex(bArmature *arm, EditBone *exBone, bool clear_connected) { EditBone *curBone; @@ -190,13 +187,6 @@ bool ED_armature_ebone_is_child_recursive(EditBone *ebone_parent, EditBone *ebon return false; } -/** - * 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. - */ EditBone *ED_armature_ebone_find_shared_parent(EditBone *ebone_child[], const uint ebone_child_tot) { #define EBONE_TEMP_UINT(ebone) (*((uint *)(&((ebone)->temp)))) @@ -284,20 +274,17 @@ void ED_armature_ebone_from_mat4(EditBone *ebone, const float mat[4][4]) ED_armature_ebone_from_mat3(ebone, mat3); } -/** - * Return a pointer to the bone of the given name - */ EditBone *ED_armature_ebone_find_name(const ListBase *edbo, const char *name) { return BLI_findstring(edbo, name, offsetof(EditBone, name)); } -/* *************************************************************** */ -/* Mirroring */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Mirroring + * \{ */ -/** - * \see #BKE_pose_channel_get_mirrored (pose-mode, matching function) - */ EditBone *ED_armature_ebone_get_mirrored(const ListBase *edbo, EditBone *ebo) { char name_flip[MAXBONENAME]; @@ -317,8 +304,6 @@ EditBone *ED_armature_ebone_get_mirrored(const ListBase *edbo, EditBone *ebo) /* ------------------------------------- */ -/* helper function for tools to work on mirrored parts. - * it leaves mirrored bones selected then too, which is a good indication of what happened */ void armature_select_mirrored_ex(bArmature *arm, const int flag) { BLI_assert((flag & ~(BONE_SELECTED | BONE_ROOTSEL | BONE_TIPSEL)) == 0); @@ -375,7 +360,6 @@ void armature_tag_select_mirrored(bArmature *arm) } } -/* only works when tagged */ void armature_tag_unselect(bArmature *arm) { EditBone *curBone; @@ -465,8 +449,6 @@ void ED_armature_ebone_transform_mirror_update(bArmature *arm, EditBone *ebo, bo } } -/* if editbone (partial) selected, copy data */ -/* context; editmode armature, with mirror editing enabled */ void ED_armature_edit_transform_mirror_update(Object *obedit) { bArmature *arm = obedit->data; @@ -475,8 +457,11 @@ void ED_armature_edit_transform_mirror_update(Object *obedit) } } -/* *************************************************************** */ -/* Armature EditMode Conversions */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Armature EditMode Conversions + * \{ */ /* converts Bones to EditBone list, used for tools as well */ static EditBone *make_boneList_recursive(ListBase *edbo, @@ -688,7 +673,6 @@ static void armature_finalize_restpose(ListBase *bonelist, ListBase *editbonelis } } -/* put EditMode back in Object */ void ED_armature_from_edit(Main *bmain, bArmature *arm) { EditBone *eBone, *neBone; @@ -838,7 +822,6 @@ void ED_armature_edit_free(struct bArmature *arm) } } -/* Put armature in EditMode */ void ED_armature_to_edit(bArmature *arm) { ED_armature_edit_free(arm); @@ -846,10 +829,11 @@ void ED_armature_to_edit(bArmature *arm) arm->act_edbone = make_boneList(arm->edbo, &arm->bonebase, arm->act_bone); } -/* *************************************************************** */ -/* Used by Undo for Armature EditMode. */ +/** \} */ -/* free's bones and their properties */ +/* -------------------------------------------------------------------- */ +/** \name Used by Undo for Armature EditMode + * \{ */ void ED_armature_ebone_listbase_free(ListBase *lb, const bool do_id_user) { @@ -908,10 +892,14 @@ void ED_armature_ebone_listbase_temp_clear(ListBase *lb) } } -/* *************************************************************** */ -/* Low level selection functions which hide connected-parent - * flag behavior which gets tricky to handle in selection operators. - * (no flushing in ED_armature_ebone_select.*, that should be explicit) */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Low Level Selection Functions + * + * which hide connected-parent flag behavior which gets tricky to handle in selection operators. + * (no flushing in `ED_armature_ebone_select.*`, that should be explicit). + * \{ */ int ED_armature_ebone_selectflag_get(const EditBone *ebone) { @@ -964,3 +952,5 @@ void ED_armature_ebone_select_set(EditBone *ebone, bool select) } ED_armature_ebone_selectflag_set(ebone, flag); } + +/** \} */ diff --git a/source/blender/editors/armature/editarmature_undo.c b/source/blender/editors/armature/editarmature_undo.c index 832e75b2a8b..9117dfe892f 100644 --- a/source/blender/editors/armature/editarmature_undo.c +++ b/source/blender/editors/armature/editarmature_undo.c @@ -244,7 +244,6 @@ static void armature_undosys_foreach_ID_ref(UndoStep *us_p, } } -/* Export for ED_undo_sys. */ void ED_armature_undosys_type(UndoType *ut) { ut->name = "Edit Armature"; diff --git a/source/blender/editors/armature/pose_edit.c b/source/blender/editors/armature/pose_edit.c index 20d7baa39ed..772fe8f3196 100644 --- a/source/blender/editors/armature/pose_edit.c +++ b/source/blender/editors/armature/pose_edit.c @@ -72,9 +72,10 @@ # include "PIL_time_utildefines.h" #endif -/* matches logic with ED_operator_posemode_context() */ Object *ED_pose_object_from_context(bContext *C) { + /* NOTE: matches logic with #ED_operator_posemode_context(). */ + ScrArea *area = CTX_wm_area(C); Object *ob; @@ -90,7 +91,6 @@ Object *ED_pose_object_from_context(bContext *C) return ob; } -/* This function is used to process the necessary updates for */ bool ED_object_posemode_enter_ex(struct Main *bmain, Object *ob) { BLI_assert(!ID_IS_LINKED(ob)); @@ -195,11 +195,6 @@ static eAnimvizCalcRange pose_path_convert_range(ePosePathCalcRange range) return ANIMVIZ_CALC_RANGE_FULL; } -/* 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(bContext *C, Scene *scene, Object *ob, ePosePathCalcRange range) { /* Transform doesn't always have context available to do update. */ diff --git a/source/blender/editors/armature/pose_select.c b/source/blender/editors/armature/pose_select.c index e5b8983af93..17347aa57fe 100644 --- a/source/blender/editors/armature/pose_select.c +++ b/source/blender/editors/armature/pose_select.c @@ -108,7 +108,6 @@ void ED_pose_bone_select_tag_update(Object *ob) DEG_id_tag_update(&arm->id, ID_RECALC_SELECT); } -/* Utility method for changing the selection status of a bone */ void ED_pose_bone_select(Object *ob, bPoseChannel *pchan, bool select) { bArmature *arm; @@ -238,10 +237,6 @@ void ED_armature_pose_select_pick_bone(ViewLayer *view_layer, } } -/** - * Called for mode-less pose selection. - * assumes the active object is still on old situation. - */ bool ED_armature_pose_select_pick_with_buffer(ViewLayer *view_layer, View3D *v3d, Base *base, @@ -269,14 +264,6 @@ bool ED_armature_pose_select_pick_with_buffer(ViewLayer *view_layer, return nearBone != NULL; } -/** - * 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(ViewLayer *view_layer, Base *base_select) { BLI_assert(base_select && (base_select->object->type == OB_ARMATURE)); @@ -323,9 +310,6 @@ void ED_armature_pose_select_in_wpaint_mode(ViewLayer *view_layer, Base *base_se } } -/* '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(Object *ob, int select_mode, const bool ignore_visibility) { bArmature *arm = ob->data; diff --git a/source/blender/editors/armature/pose_utils.c b/source/blender/editors/armature/pose_utils.c index 500b9663a6c..19a5348dbc0 100644 --- a/source/blender/editors/armature/pose_utils.c +++ b/source/blender/editors/armature/pose_utils.c @@ -132,9 +132,6 @@ static void fcurves_to_pchan_links_get(ListBase *pfLinks, } } -/** - * Returns a valid pose armature for this object, else returns NULL. - */ Object *poseAnim_object_get(Object *ob_) { Object *ob = BKE_object_pose_armature_get(ob_); @@ -144,9 +141,6 @@ Object *poseAnim_object_get(Object *ob_) return NULL; } -/** - * Get sets of F-Curves providing transforms for the bones in the Pose. - */ void poseAnim_mapping_get(bContext *C, ListBase *pfLinks) { /* for each Pose-Channel which gets affected, get the F-Curves for that channel @@ -192,7 +186,6 @@ void poseAnim_mapping_get(bContext *C, ListBase *pfLinks) } } -/* Free F-Curve <-> PoseChannel links. */ void poseAnim_mapping_free(ListBase *pfLinks) { tPChanFCurveLink *pfl, *pfln = NULL; @@ -219,7 +212,6 @@ void poseAnim_mapping_free(ListBase *pfLinks) /* ------------------------- */ -/* helper for apply() / reset() - refresh the data */ void poseAnim_mapping_refresh(bContext *C, Scene *UNUSED(scene), Object *ob) { DEG_id_tag_update(&ob->id, ID_RECALC_GEOMETRY); @@ -231,7 +223,6 @@ void poseAnim_mapping_refresh(bContext *C, Scene *UNUSED(scene), Object *ob) } } -/* reset changes made to current pose */ void poseAnim_mapping_reset(ListBase *pfLinks) { tPChanFCurveLink *pfl; @@ -268,7 +259,6 @@ void poseAnim_mapping_reset(ListBase *pfLinks) } } -/* perform auto-key-framing after changes were made + confirmed */ void poseAnim_mapping_autoKeyframe(bContext *C, Scene *scene, ListBase *pfLinks, float cframe) { ViewLayer *view_layer = CTX_data_view_layer(C); @@ -337,9 +327,6 @@ void poseAnim_mapping_autoKeyframe(bContext *C, Scene *scene, ListBase *pfLinks, /* ------------------------- */ -/* find the next F-Curve for a PoseChannel with matching path... - * - path is not just the pfl rna_path, since that path doesn't have property info yet - */ LinkData *poseAnim_mapping_getNextFCurve(ListBase *fcuLinks, LinkData *prev, const char *path) { LinkData *first = (prev) ? prev->next : (fcuLinks) ? fcuLinks->first : NULL; 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, diff --git a/source/blender/editors/mesh/meshtools.c b/source/blender/editors/mesh/meshtools.c index 7295d33acb6..ebe8b758aa2 100644 --- a/source/blender/editors/mesh/meshtools.c +++ b/source/blender/editors/mesh/meshtools.c @@ -755,11 +755,10 @@ int ED_mesh_join_objects_exec(bContext *C, wmOperator *op) /* -------------------------------------------------------------------- */ /** \name Join as Shapes + * + * Append selected meshes vertex locations as shapes of the active mesh. * \{ */ -/* Append selected meshes vertex locations as shapes of the active mesh, - * return 0 if no join is made (error) and 1 of the join is done */ - int ED_mesh_shapes_join_objects_exec(bContext *C, wmOperator *op) { Main *bmain = CTX_data_main(C); @@ -1197,8 +1196,7 @@ int *mesh_get_x_mirror_faces(Object *ob, BMEditMesh *em, Mesh *me_eval) return mirrorfaces; } -/* selection, vertex and face */ -/* returns 0 if not found, otherwise 1 */ +/* Selection (vertex and face). */ bool ED_mesh_pick_face(bContext *C, Object *ob, const int mval[2], uint dist_px, uint *r_index) { diff --git a/source/blender/editors/object/object_add.c b/source/blender/editors/object/object_add.c index d1789c9601c..2afadda9ade 100644 --- a/source/blender/editors/object/object_add.c +++ b/source/blender/editors/object/object_add.c @@ -3357,7 +3357,6 @@ static Base *object_add_duplicate_internal(Main *bmain, return basen; } -/* single object duplicate, if dupflag==0, fully linked, else it uses the flags given */ Base *ED_object_add_duplicate( Main *bmain, Scene *scene, ViewLayer *view_layer, Base *base, const eDupli_ID_Flags dupflag) { diff --git a/source/blender/editors/screen/screen_edit.c b/source/blender/editors/screen/screen_edit.c index 61d6997b0fb..5a2b53163b8 100644 --- a/source/blender/editors/screen/screen_edit.c +++ b/source/blender/editors/screen/screen_edit.c @@ -1803,11 +1803,6 @@ bool ED_screen_stereo3d_required(const bScreen *screen, const Scene *scene) return false; } -/** - * Find the scene displayed in \a screen. - * \note Assumes \a screen to be visible/active! - */ - Scene *ED_screen_scene_find_with_window(const bScreen *screen, const wmWindowManager *wm, struct wmWindow **r_window) diff --git a/source/blender/editors/sculpt_paint/paint_vertex.c b/source/blender/editors/sculpt_paint/paint_vertex.c index 302de13a881..23e03f3e576 100644 --- a/source/blender/editors/sculpt_paint/paint_vertex.c +++ b/source/blender/editors/sculpt_paint/paint_vertex.c @@ -199,8 +199,6 @@ static void paint_last_stroke_update(Scene *scene, const float location[3]) ups->last_stroke_valid = true; } -/* polling - retrieve whether cursor should be set or operator should be done */ - bool vertex_paint_mode_poll(bContext *C) { Object *ob = CTX_data_active_object(C); |