diff options
Diffstat (limited to 'source/blender/blenkernel/BKE_animsys.h')
| -rw-r--r-- | source/blender/blenkernel/BKE_animsys.h | 140 |
1 files changed, 109 insertions, 31 deletions
diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index 07da9d75e59..4845807de39 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[], @@ -113,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 `<prefix><["><name><"]>` + * i.e. `pose.bones["Bone"]`. + */ char *BKE_animsys_fix_rna_path_rename(struct ID *owner_id, char *old_path, const char *prefix, @@ -123,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 `<prefix><["><name><"]>` + * i.e. `pose.bones["Bone"]`. + */ void BKE_action_fix_paths_rename(struct ID *owner_id, struct bAction *act, const char *prefix, @@ -133,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 `<prefix><["><name><"]>` + * i.e. `pose.bones["Bone"]`. + */ void BKE_animdata_fix_paths_rename(struct ID *owner_id, struct AnimData *adt, struct ID *ref_id, @@ -144,24 +173,31 @@ 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 `<prefix><["><name><"]>` + * i.e. `pose.bones["Bone"]` + */ void BKE_animdata_fix_paths_rename_all_ex(struct Main *bmain, struct ID *ref_id, 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, + 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. */ +/** + * 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); /* -------------------------------------- */ @@ -172,17 +208,19 @@ 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, struct ListBase *basepaths); -char *BKE_animdata_driver_path_hack(struct bContext *C, - struct PointerRNA *ptr, - struct PropertyRNA *prop, - char *base_path); - /* ************************************* */ /* Batch AnimData API */ @@ -195,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. */ @@ -208,11 +246,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 +279,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); /* ************************************* */ @@ -237,19 +299,35 @@ 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); -bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, const float value); +/** + * Write the given value to a setting using RNA, and return success. + */ +bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, 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); + 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); |