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_object_deform.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_object_deform.h')
-rw-r--r-- | source/blender/blenkernel/BKE_object_deform.h | 88 |
1 files changed, 86 insertions, 2 deletions
diff --git a/source/blender/blenkernel/BKE_object_deform.h b/source/blender/blenkernel/BKE_object_deform.h index a10158254c2..ddbf5178ab0 100644 --- a/source/blender/blenkernel/BKE_object_deform.h +++ b/source/blender/blenkernel/BKE_object_deform.h @@ -31,24 +31,73 @@ struct MDeformVert; struct Object; struct bDeformGroup; -/* General vgroup operations */ +/* General vgroup operations. */ + +/** + * Update users of vgroups from this object, according to given map. + * + * Use it when you remove or reorder vgroups in the object. + * + * \param map: an array mapping old indices to new indices. + */ void BKE_object_defgroup_remap_update_users(struct Object *ob, const int *map); +/** + * Get #MDeformVert vgroup data from given object. Should only be used in Object mode. + * + * \return True if the id type supports weights. + */ bool BKE_object_defgroup_array_get(struct ID *id, struct MDeformVert **dvert_arr, int *dvert_tot); +/** + * Add a vgroup of default name to object. *Does not* handle #MDeformVert data at all! + */ struct bDeformGroup *BKE_object_defgroup_add(struct Object *ob); +/** + * Add a vgroup of given name to object. *Does not* handle #MDeformVert data at all! + */ struct bDeformGroup *BKE_object_defgroup_add_name(struct Object *ob, const char *name); +/** + * Create #MDeformVert data for given ID. Work in Object mode only. + */ struct MDeformVert *BKE_object_defgroup_data_create(struct ID *id); +/** + * Remove all verts (or only selected ones) from given vgroup. Work in Object and Edit modes. + * + * \param use_selection: Only operate on selection. + * \return True if any vertex was removed, false otherwise. + */ bool BKE_object_defgroup_clear(struct Object *ob, struct bDeformGroup *dg, const bool use_selection); +/** + * Remove all verts (or only selected ones) from all vgroups. Work in Object and Edit modes. + * + * \param use_selection: Only operate on selection. + * \return True if any vertex was removed, false otherwise. + */ bool BKE_object_defgroup_clear_all(struct Object *ob, const bool use_selection); +/** + * Remove given vgroup from object. Work in Object and Edit modes. + */ void BKE_object_defgroup_remove(struct Object *ob, struct bDeformGroup *defgroup); +/** + * Remove all vgroups from object. Work in Object and Edit modes. + * When only_unlocked=true, locked vertex groups are not removed. + */ void BKE_object_defgroup_remove_all_ex(struct Object *ob, bool only_unlocked); +/** + * Remove all vgroups from object. Work in Object and Edit modes. + */ void BKE_object_defgroup_remove_all(struct Object *ob); +/** + * Compute mapping for vertex groups with matching name, -1 is used for no remapping. + * Returns null if no remapping is required. + * The returned array has to be freed. + */ int *BKE_object_defgroup_index_map_create(struct Object *ob_src, struct Object *ob_dst, int *r_map_len); @@ -57,34 +106,69 @@ void BKE_object_defgroup_index_map_apply(struct MDeformVert *dvert, const int *map, int map_len); -/* Select helpers */ +/* Select helpers. */ + enum eVGroupSelect; +/** + * Return the subset type of the Vertex Group Selection. + */ bool *BKE_object_defgroup_subset_from_select_type(struct Object *ob, enum eVGroupSelect subset_type, int *r_defgroup_tot, int *r_subset_count); +/** + * Store indices from the defgroup_validmap (faster lookups in some cases). + */ void BKE_object_defgroup_subset_to_index_array(const bool *defgroup_validmap, const int defgroup_tot, int *r_defgroup_subset_map); /* ********** */ +/** + * Gets the status of "flag" for each #bDeformGroup + * in the object data's vertex group list and returns an array containing them + */ bool *BKE_object_defgroup_lock_flags_get(struct Object *ob, const int defbase_tot); bool *BKE_object_defgroup_validmap_get(struct Object *ob, const int defbase_tot); +/** + * Returns total selected vgroups, + * `wpi.defbase_sel` is assumed malloc'd, all values are set. + */ bool *BKE_object_defgroup_selected_get(struct Object *ob, int defbase_tot, int *r_dg_flags_sel_tot); +/** + * Checks if the lock relative mode is applicable. + * + * \return true if an unlocked deform group is active. + */ bool BKE_object_defgroup_check_lock_relative(const bool *lock_flags, const bool *validmap, int index); +/** + * Additional check for whether the lock relative mode is applicable in multi-paint mode. + * + * \return true if none of the selected groups are locked. + */ bool BKE_object_defgroup_check_lock_relative_multi(int defbase_tot, const bool *lock_flags, const bool *selected, int sel_tot); +/** + * Takes a pair of boolean masks of all locked and all deform groups, and computes + * a pair of masks for locked deform and unlocked deform groups. Output buffers may + * reuse the input ones. + */ void BKE_object_defgroup_split_locked_validmap( int defbase_tot, const bool *locked, const bool *deform, bool *r_locked, bool *r_unlocked); +/** + * Marks mirror vgroups in output and counts them. + * Output and counter assumed to be already initialized. + * Designed to be usable after BKE_object_defgroup_selected_get to extend selection to mirror. + */ void BKE_object_defgroup_mirror_selection(struct Object *ob, int defbase_tot, const bool *selection, |