diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/BKE_constraint.h | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
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
Diffstat (limited to 'source/blender/blenkernel/BKE_constraint.h')
-rw-r--r-- | source/blender/blenkernel/BKE_constraint.h | 109 |
1 files changed, 106 insertions, 3 deletions
diff --git a/source/blender/blenkernel/BKE_constraint.h b/source/blender/blenkernel/BKE_constraint.h index 784b395dfa5..1f59efbb0f3 100644 --- a/source/blender/blenkernel/BKE_constraint.h +++ b/source/blender/blenkernel/BKE_constraint.h @@ -45,7 +45,7 @@ extern "C" { typedef struct bConstraintOb { /** to get evaluated armature. */ struct Depsgraph *depsgraph; - /** for system time, part of deglobalization, code nicer later with local time (ton) */ + /** for system time, part of de-globalization, code nicer later with local time (ton) */ struct Scene *scene; /** if pchan, then armature that it comes from, otherwise constraint owner */ struct Object *ob; @@ -61,7 +61,7 @@ typedef struct bConstraintOb { /** type of owner. */ short type; - /** rotation order for constraint owner (as defined in eEulerRotationOrders in BLI_math.h) */ + /** rotation order for constraint owner (as defined in #eEulerRotationOrders in BLI_math.h) */ short rotOrder; } bConstraintOb; @@ -76,7 +76,7 @@ typedef void (*ConstraintIDFunc)(struct bConstraint *con, /* ....... */ /** - * Constraint Type-Info (shorthand in code = cti): + * Constraint Type-Info (shorthand in code = `cti`): * This struct provides function pointers for runtime, so that functions can be * written more generally (with fewer/no special exceptions for various constraints). * @@ -138,49 +138,107 @@ typedef struct bConstraintTypeInfo { } bConstraintTypeInfo; /* Function Prototypes for bConstraintTypeInfo's */ + +/** + * This function should always be used to get the appropriate type-info, as it + * has checks which prevent segfaults in some weird cases. + */ const bConstraintTypeInfo *BKE_constraint_typeinfo_get(struct bConstraint *con); +/** + * This function should be used for getting the appropriate type-info when only + * a constraint type is known. + */ const bConstraintTypeInfo *BKE_constraint_typeinfo_from_type(int type); /* ---------------------------------------------------------------------------- */ /* Constraint function prototypes */ + +/** + * Find the first available, non-duplicate name for a given constraint. + */ void BKE_constraint_unique_name(struct bConstraint *con, struct ListBase *list); +/** + * Allocate and duplicate a single constraint, outside of any object/pose context. + */ struct bConstraint *BKE_constraint_duplicate_ex(struct bConstraint *src, const int flag, const bool do_extern); +/** + * Add a copy of the given constraint for the given bone. + */ struct bConstraint *BKE_constraint_copy_for_pose(struct Object *ob, struct bPoseChannel *pchan, struct bConstraint *src); +/** + * Add a copy of the given constraint for the given object. + */ struct bConstraint *BKE_constraint_copy_for_object(struct Object *ob, struct bConstraint *src); void BKE_constraints_free(struct ListBase *list); +/** + * Free all constraints from a constraint-stack. + */ void BKE_constraints_free_ex(struct ListBase *list, bool do_id_user); void BKE_constraints_copy(struct ListBase *dst, const struct ListBase *src, bool do_extern); +/** + * Duplicate all of the constraints in a constraint stack. + */ void BKE_constraints_copy_ex(struct ListBase *dst, const struct ListBase *src, const int flag, bool do_extern); +/** + * Run the given callback on all ID-blocks in list of constraints. + */ void BKE_constraints_id_loop(struct ListBase *list, ConstraintIDFunc func, void *userdata); void BKE_constraint_free_data(struct bConstraint *con); +/** + * Free data of a specific constraint if it has any info. + * Be sure to run #BIK_clear_data() when freeing an IK constraint, + * unless #DAG_relations_tag_update is called. + */ void BKE_constraint_free_data_ex(struct bConstraint *con, bool do_id_user); bool BKE_constraint_target_uses_bbone(struct bConstraint *con, struct bConstraintTarget *ct); /* Constraint API function prototypes */ + +/** + * Finds the 'active' constraint in a constraint stack. + */ struct bConstraint *BKE_constraints_active_get(struct ListBase *list); +/** + * Set the given constraint as the active one (clearing all the others). + */ void BKE_constraints_active_set(ListBase *list, struct bConstraint *con); struct bConstraint *BKE_constraints_find_name(struct ListBase *list, const char *name); +/** + * Finds the constraint that owns the given target within the object. + */ struct bConstraint *BKE_constraint_find_from_target(struct Object *ob, struct bConstraintTarget *tgt, struct bPoseChannel **r_pchan); +/** + * Check whether given constraint is not local (i.e. from linked data) when the object is a library + * override. + * + * \param con: May be NULL, in which case we consider it as a non-local constraint case. + */ bool BKE_constraint_is_nonlocal_in_liboverride(const struct Object *ob, const struct bConstraint *con); +/** + * Add new constraint for the given object. + */ struct bConstraint *BKE_constraint_add_for_object(struct Object *ob, const char *name, short type); +/** + * Add new constraint for the given bone. + */ struct bConstraint *BKE_constraint_add_for_pose(struct Object *ob, struct bPoseChannel *pchan, const char *name, @@ -190,8 +248,14 @@ bool BKE_constraint_remove_ex(ListBase *list, struct Object *ob, struct bConstraint *con, bool clear_dep); +/** + * Remove the specified constraint from the given constraint stack. + */ bool BKE_constraint_remove(ListBase *list, struct bConstraint *con); +/** + * Apply the specified constraint in the given constraint stack. + */ bool BKE_constraint_apply_for_object(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -217,17 +281,38 @@ bool BKE_constraint_apply_and_remove_for_pose(struct Depsgraph *depsgraph, void BKE_constraint_panel_expand(struct bConstraint *con); /* Constraints + Proxies function prototypes */ + +/** + * Rescue all constraints tagged as being #CONSTRAINT_PROXY_LOCAL + * (i.e. added to bone that's proxy-synced in this file). + */ void BKE_constraints_proxylocal_extract(struct ListBase *dst, struct ListBase *src); +/** + * Returns if the owner of the constraint is proxy-protected. + */ bool BKE_constraints_proxylocked_owner(struct Object *ob, struct bPoseChannel *pchan); /* Constraint Evaluation function prototypes */ + +/** + * This function MEM_calloc's a #bConstraintOb struct, + * that will need to be freed after evaluation. + */ struct bConstraintOb *BKE_constraints_make_evalob(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, void *subdata, short datatype); +/** + * Cleanup after constraint evaluation. + */ void BKE_constraints_clear_evalob(struct bConstraintOb *cob); +/** + * This function is responsible for the correct transformations/conversions + * of a matrix from one space to another for constraint evaluation. + * For now, this is only implemented for objects and pose-channels. + */ void BKE_constraint_mat_convertspace(struct Object *ob, struct bPoseChannel *pchan, struct bConstraintOb *cob, @@ -236,6 +321,14 @@ void BKE_constraint_mat_convertspace(struct Object *ob, short to, const bool keep_scale); +/** + * This function is a relic from the prior implementations of the constraints system, when all + * constraints either had one or no targets. It used to be called during the main constraint + * solving loop, but is now only used for the remaining cases for a few constraints. + * + * None of the actual calculations of the matrices should be done here! Also, this function is + * not to be used by any new constraints, particularly any that have multiple targets. + */ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, struct Scene *scene, struct bConstraint *con, @@ -244,12 +337,22 @@ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, void *ownerdata, float mat[4][4], float ctime); +/** + * Get the list of targets required for solving a constraint. + */ void BKE_constraint_targets_for_solving_get(struct Depsgraph *depsgraph, struct bConstraint *con, struct bConstraintOb *ob, struct ListBase *targets, float ctime); void BKE_constraint_custom_object_space_get(float r_mat[4][4], struct bConstraint *con); +/** + * This function is called whenever constraints need to be evaluated. Currently, all + * constraints that can be evaluated are every time this gets run. + * + * #BKE_constraints_make_evalob and #BKE_constraints_clear_evalob should be called before and + * after running this function, to sort out cob. + */ void BKE_constraints_solve(struct Depsgraph *depsgraph, struct ListBase *conlist, struct bConstraintOb *cob, |