From ffc4c126f5416b04a01653e7a03451797b98aba4 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 7 Dec 2021 17:19:15 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenkernel' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenkernel/BKE_animsys.h | 60 +++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 6 deletions(-) (limited to 'source/blender/blenkernel/BKE_animsys.h') diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index 07da9d75e59..6197cb93c95 100644 --- a/source/blender/blenkernel/BKE_animsys.h +++ b/source/blender/blenkernel/BKE_animsys.h @@ -69,12 +69,17 @@ AnimationEvalContext BKE_animsys_eval_context_construct_at( /* ************************************* */ /* KeyingSets API */ -/* Used to create a new 'custom' KeyingSet for the user, - * that will be automatically added to the stack */ +/** + * Used to create a new 'custom' KeyingSet for the user, + * that will be automatically added to the stack. + */ struct KeyingSet *BKE_keyingset_add( struct ListBase *list, const char idname[], const char name[], short flag, short keyingflag); -/* Add a path to a KeyingSet */ +/** + * Add a path to a KeyingSet. Nothing is returned for now. + * Checks are performed to ensure that destination is appropriate for the KeyingSet in question + */ struct KS_Path *BKE_keyingset_add_path(struct KeyingSet *ks, struct ID *id, const char group_name[], @@ -83,7 +88,10 @@ struct KS_Path *BKE_keyingset_add_path(struct KeyingSet *ks, short flag, short groupmode); -/* Find the destination matching the criteria given */ +/** + * Find the destination matching the criteria given. + * TODO: do we want some method to perform partial matches too? + */ struct KS_Path *BKE_keyingset_find_path(struct KeyingSet *ks, struct ID *id, const char group_name[], @@ -208,11 +216,32 @@ void BKE_fcurves_id_cb(struct ID *id, ID_FCurve_Edit_Callback func, void *user_d typedef struct NlaKeyframingContext NlaKeyframingContext; +/** + * Prepare data necessary to compute correct keyframe values for NLA strips + * with non-Replace mode or influence different from 1. + * + * \param cache: List used to cache contexts for reuse when keying + * multiple channels in one operation. + * \param ptr: RNA pointer to the Object with the animation. + * \return Keyframing context, or NULL if not necessary. + */ struct NlaKeyframingContext *BKE_animsys_get_nla_keyframing_context( struct ListBase *cache, struct PointerRNA *ptr, struct AnimData *adt, const struct AnimationEvalContext *anim_eval_context); +/** + * Apply correction from the NLA context to the values about to be keyframed. + * + * \param context: Context to use (may be NULL). + * \param prop_ptr: Property about to be keyframed. + * \param[in,out] values: Array of property values to adjust. + * \param count: Number of values in the array. + * \param index: Index of the element about to be updated, or -1. + * \param[out] r_force_all: Set to true if all channels must be inserted. May be NULL. + * \return False if correction fails due to a division by zero, + * or null r_force_all when all channels are required. + */ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, struct PointerRNA *prop_ptr, struct PropertyRNA *prop, @@ -220,6 +249,9 @@ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, int count, int index, bool *r_force_all); +/** + * Free all cached contexts from the list. + */ void BKE_animsys_free_nla_keyframing_context_cache(struct ListBase *cache); /* ************************************* */ @@ -240,16 +272,32 @@ bool BKE_animsys_rna_path_resolve(struct PointerRNA *ptr, const int array_index, struct PathResolvedRNA *r_result); bool BKE_animsys_read_from_rna_path(struct PathResolvedRNA *anim_rna, float *r_value); +/** + * Write the given value to a setting using RNA, and return success. + */ bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, const float value); -/* Evaluation loop for evaluating animation data. */ +/** + * Evaluation loop for evaluation animation data + * + * This assumes that the animation-data provided belongs to the ID block in question, + * and that the flags for which parts of the animation-data settings need to be recalculated + * have been set already by the depsgraph. Now, we use the recalculate. + */ void BKE_animsys_evaluate_animdata(struct ID *id, struct AnimData *adt, const struct AnimationEvalContext *anim_eval_context, eAnimData_Recalc recalc, const bool flush_to_original); -/* Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only */ +/** + * Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only + * + * This will evaluate only the animation info available in the animation data-blocks + * encountered. In order to enforce the system by which some settings controlled by a + * 'local' (i.e. belonging in the nearest ID-block that setting is related to, not a + * standard 'root') block are overridden by a larger 'user' + */ void BKE_animsys_evaluate_all_animation(struct Main *main, struct Depsgraph *depsgraph, float ctime); -- cgit v1.2.3 From 025c9214165ca9e43d3c281c326bf4887c32d642 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Thu, 23 Dec 2021 13:49:58 +0100 Subject: Cleanup: remove BKE_animdata_driver_path_hack The `BKE_animdata_driver_path_hack()` function has had almost no effect since rB51b796ff1528, and basically boils down to: ``` return base_path ? base_path : RNA_path_from_ID_to_property(ptr, prop); ``` Since `base_path` was `NULL` in the majority of cases, it's just been replaced by a direct call to `RNA_path_from_ID_to_property()`. The conditional now just appears in one remaining case. This relates to T91387. Reviewed By: mont29 Differential Revision: https://developer.blender.org/D13646 --- source/blender/blenkernel/BKE_animsys.h | 5 ----- 1 file changed, 5 deletions(-) (limited to 'source/blender/blenkernel/BKE_animsys.h') diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index 6197cb93c95..4733c96543e 100644 --- a/source/blender/blenkernel/BKE_animsys.h +++ b/source/blender/blenkernel/BKE_animsys.h @@ -186,11 +186,6 @@ void BKE_animdata_transfer_by_basepath(struct Main *bmain, struct ID *dstID, struct ListBase *basepaths); -char *BKE_animdata_driver_path_hack(struct bContext *C, - struct PointerRNA *ptr, - struct PropertyRNA *prop, - char *base_path); - /* ************************************* */ /* Batch AnimData API */ -- cgit v1.2.3 From 0e53ea4cb524ad2b7dc6c9e6a6f66eaa12031612 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 6 Jan 2022 13:54:46 +1100 Subject: Correct error when moving doc-strings into header Error in ffc4c126f5416b04a01653e7a03451797b98aba4, which moved doc-strings from implementation into headers. Some changes in BKE_animsys.h needed to done manually as there were already doc-strings in both the header and implementation (with overlapping information). When making these changes some doc-strings were removed unintentionally. Thanks for @sybren for the heads up. --- source/blender/blenkernel/BKE_animsys.h | 63 +++++++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 14 deletions(-) (limited to 'source/blender/blenkernel/BKE_animsys.h') diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index 4733c96543e..d5183891296 100644 --- a/source/blender/blenkernel/BKE_animsys.h +++ b/source/blender/blenkernel/BKE_animsys.h @@ -121,7 +121,15 @@ void BKE_keyingsets_blend_read_expand(struct BlendExpander *expander, struct Lis /* ************************************* */ /* Path Fixing API */ -/* Get a "fixed" version of the given path (oldPath) */ +/** + * Get a "fixed" version of the given path `old_path`. + * + * This is just an external wrapper for the RNA-Path fixing function, + * with input validity checks on top of the basic method. + * + * \note it is assumed that the structure we're replacing is `<["><"]>` + * i.e. `pose.bones["Bone"]`. + */ char *BKE_animsys_fix_rna_path_rename(struct ID *owner_id, char *old_path, const char *prefix, @@ -131,7 +139,15 @@ char *BKE_animsys_fix_rna_path_rename(struct ID *owner_id, int newSubscript, bool verify_paths); -/* Fix all the paths for the given ID + Action */ +/** + * Fix all the paths for the given ID + Action. + * + * This is just an external wrapper for the F-Curve fixing function, + * with input validity checks on top of the basic method. + * + * \note it is assumed that the structure we're replacing is `<["><"]>` + * i.e. `pose.bones["Bone"]`. + */ void BKE_action_fix_paths_rename(struct ID *owner_id, struct bAction *act, const char *prefix, @@ -141,7 +157,12 @@ void BKE_action_fix_paths_rename(struct ID *owner_id, int newSubscript, bool verify_paths); -/* Fix all the paths for the given ID+AnimData */ +/** + * Fix all the paths for the given ID+AnimData + * + * \note it is assumed that the structure we're replacing is `<["><"]>` + * i.e. `pose.bones["Bone"]`. + */ void BKE_animdata_fix_paths_rename(struct ID *owner_id, struct AnimData *adt, struct ID *ref_id, @@ -152,13 +173,12 @@ void BKE_animdata_fix_paths_rename(struct ID *owner_id, int newSubscript, bool verify_paths); -/* Fix all the paths for the entire database... */ -void BKE_animdata_fix_paths_rename_all(struct ID *ref_id, - const char *prefix, - const char *oldName, - const char *newName); - -/* Fix all the paths for the entire bmain with extra parameters. */ +/** + * Fix all RNA-Paths throughout the database (directly access the #Global.main version). + * + * \note it is assumed that the structure we're replacing is `<["><"]>` + * i.e. `pose.bones["Bone"]` + */ void BKE_animdata_fix_paths_rename_all_ex(struct Main *bmain, struct ID *ref_id, const char *prefix, @@ -168,8 +188,16 @@ void BKE_animdata_fix_paths_rename_all_ex(struct Main *bmain, const int newSubscript, const bool verify_paths); -/* Fix the path after removing elements that are not ID (e.g., node). - * Return true if any animation data was affected. */ +/** See #BKE_animdata_fix_paths_rename_all_ex */ +void BKE_animdata_fix_paths_rename_all(struct ID *ref_id, + const char *prefix, + const char *oldName, + const char *newName); + +/** + * Fix the path after removing elements that are not ID (e.g., node). + * Return true if any animation data was affected. + */ bool BKE_animdata_fix_paths_remove(struct ID *id, const char *path); /* -------------------------------------- */ @@ -180,7 +208,14 @@ typedef struct AnimationBasePathChange { const char *dst_basepath; } AnimationBasePathChange; -/* Move animation data from src to destination if its paths are based on basepaths */ +/** + * Move animation data from source to destination if its paths are based on `basepaths`. + * + * Transfer the animation data from `srcID` to `dstID` where the `srcID` animation data + * is based off `basepath`, creating new #AnimData and associated data as necessary. + * + * \param basepaths: A list of #AnimationBasePathChange. + */ void BKE_animdata_transfer_by_basepath(struct Main *bmain, struct ID *srcID, struct ID *dstID, @@ -198,7 +233,7 @@ typedef void (*ID_FCurve_Edit_Callback)(struct ID *id, struct FCurve *fcu, void /* Loop over all datablocks applying callback */ void BKE_animdata_main_cb(struct Main *bmain, ID_AnimData_Edit_Callback func, void *user_data); -/* Loop over all datablocks applying callback to all its F-Curves */ +/** Apply the given callback function on all F-Curves attached to data in `main` database. */ void BKE_fcurves_main_cb(struct Main *bmain, ID_FCurve_Edit_Callback func, void *user_data); /* Look over all f-curves of a given ID. */ -- cgit v1.2.3 From f9aa6376f1a2b13ab12a77197257e9145f029792 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Thu, 6 Jan 2022 11:37:31 +0100 Subject: Cleanup: anim, remove `const` declarations from pass-by-value params Remove `const` from pass-by-value parameters in function declarations. The variables passed as parameters can never be modified by the function anyway, so declaring them as `const` is meaningless. Having the declaration there could confuse, especially as it suggests it does have a meaning, training people to write meaningless code. --- source/blender/blenkernel/BKE_animsys.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'source/blender/blenkernel/BKE_animsys.h') diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index d5183891296..4845807de39 100644 --- a/source/blender/blenkernel/BKE_animsys.h +++ b/source/blender/blenkernel/BKE_animsys.h @@ -184,9 +184,9 @@ void BKE_animdata_fix_paths_rename_all_ex(struct Main *bmain, const char *prefix, const char *oldName, const char *newName, - const int oldSubscript, - const int newSubscript, - const bool verify_paths); + int oldSubscript, + int newSubscript, + bool verify_paths); /** See #BKE_animdata_fix_paths_rename_all_ex */ void BKE_animdata_fix_paths_rename_all(struct ID *ref_id, @@ -299,13 +299,13 @@ typedef enum eAnimData_Recalc { bool BKE_animsys_rna_path_resolve(struct PointerRNA *ptr, const char *rna_path, - const int array_index, + int array_index, struct PathResolvedRNA *r_result); bool BKE_animsys_read_from_rna_path(struct PathResolvedRNA *anim_rna, float *r_value); /** * Write the given value to a setting using RNA, and return success. */ -bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, const float value); +bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, float value); /** * Evaluation loop for evaluation animation data @@ -318,7 +318,7 @@ void BKE_animsys_evaluate_animdata(struct ID *id, struct AnimData *adt, const struct AnimationEvalContext *anim_eval_context, eAnimData_Recalc recalc, - const bool flush_to_original); + bool flush_to_original); /** * Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only -- cgit v1.2.3