diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-03 11:29:35 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-03 12:10:57 +0300 |
commit | c4e041da23b9c45273fcd4874308c536b6a315d1 (patch) | |
tree | 9afdea81b57e801d3a1930988ebf3a2145a408bb /source/blender/bmesh/tools | |
parent | 7c4fc5b58d2e7982aefbba093cb8f1dc36b64884 (diff) |
Cleanup: move public doc-strings into headers for 'bmesh'
Some minor improvements to doc-strings too.
Ref T92709
Diffstat (limited to 'source/blender/bmesh/tools')
23 files changed, 90 insertions, 88 deletions
diff --git a/source/blender/bmesh/tools/bmesh_beautify.c b/source/blender/bmesh/tools/bmesh_beautify.c index d5c5063f2cb..b7cf9c88282 100644 --- a/source/blender/bmesh/tools/bmesh_beautify.c +++ b/source/blender/bmesh/tools/bmesh_beautify.c @@ -235,12 +235,6 @@ static float bm_edge_calc_rotate_beauty__angle(const float v1[3], return FLT_MAX; } -/** - * Assuming we have 2 triangles sharing an edge (2 - 4), - * check if the edge running from (1 - 3) gives better results. - * - * \return (negative number means the edge can be rotated, lager == better). - */ float BM_verts_calc_rotate_beauty(const BMVert *v1, const BMVert *v2, const BMVert *v3, @@ -374,9 +368,6 @@ static void bm_edge_update_beauty_cost(BMEdge *e, /* -------------------------------------------------------------------- */ /* Beautify Fill */ -/** - * \note This function sets the edge indices to invalid values. - */ void BM_mesh_beautify_fill(BMesh *bm, BMEdge **edge_array, const int edge_array_len, diff --git a/source/blender/bmesh/tools/bmesh_beautify.h b/source/blender/bmesh/tools/bmesh_beautify.h index d0fef828e7c..2e7950118c1 100644 --- a/source/blender/bmesh/tools/bmesh_beautify.h +++ b/source/blender/bmesh/tools/bmesh_beautify.h @@ -27,6 +27,9 @@ enum { EDGE_RESTRICT_DEGENERATE = (1 << 1), }; +/** + * \note This function sets the edge indices to invalid values. + */ void BM_mesh_beautify_fill(BMesh *bm, BMEdge **edge_array, const int edge_array_len, @@ -35,6 +38,12 @@ void BM_mesh_beautify_fill(BMesh *bm, const short oflag_edge, const short oflag_face); +/** + * Assuming we have 2 triangles sharing an edge (2 - 4), + * check if the edge running from (1 - 3) gives better results. + * + * \return (negative number means the edge can be rotated, lager == better). + */ float BM_verts_calc_rotate_beauty(const BMVert *v1, const BMVert *v2, const BMVert *v3, diff --git a/source/blender/bmesh/tools/bmesh_bevel.c b/source/blender/bmesh/tools/bmesh_bevel.c index 6cf3641fed2..2f471bf0b81 100644 --- a/source/blender/bmesh/tools/bmesh_bevel.c +++ b/source/blender/bmesh/tools/bmesh_bevel.c @@ -7443,18 +7443,6 @@ static void bevel_limit_offset(BevelParams *bp, BMesh *bm) } } -/** - * - Currently only bevels BM_ELEM_TAG'd verts and edges. - * - * - Newly created faces, edges, and verts are BM_ELEM_TAG'd too, - * the caller needs to ensure these are cleared before calling - * if its going to use this tag. - * - * - If limit_offset is set, adjusts offset down if necessary - * to avoid geometry collisions. - * - * \warning all tagged edges _must_ be manifold. - */ void BM_mesh_bevel(BMesh *bm, const float offset, const int offset_type, diff --git a/source/blender/bmesh/tools/bmesh_bevel.h b/source/blender/bmesh/tools/bmesh_bevel.h index de57e1c62a9..03c10ee9f80 100644 --- a/source/blender/bmesh/tools/bmesh_bevel.h +++ b/source/blender/bmesh/tools/bmesh_bevel.h @@ -23,6 +23,18 @@ struct CurveProfile; struct MDeformVert; +/** + * - Currently only bevels BM_ELEM_TAG'd verts and edges. + * + * - Newly created faces, edges, and verts are BM_ELEM_TAG'd too, + * the caller needs to ensure these are cleared before calling + * if its going to use this tag. + * + * - If limit_offset is set, adjusts offset down if necessary + * to avoid geometry collisions. + * + * \warning all tagged edges _must_ be manifold. + */ void BM_mesh_bevel(BMesh *bm, const float offset, const int offset_type, diff --git a/source/blender/bmesh/tools/bmesh_bisect_plane.c b/source/blender/bmesh/tools/bmesh_bisect_plane.c index 8f03b86b859..c9a5c047462 100644 --- a/source/blender/bmesh/tools/bmesh_bisect_plane.c +++ b/source/blender/bmesh/tools/bmesh_bisect_plane.c @@ -411,11 +411,6 @@ finally: /** \name Public BMesh Bisect Function * \{ */ -/** - * \param use_snap_center: Snap verts onto the plane. - * \param use_tag: Only bisect tagged edges and faces. - * \param oflag_center: Operator flag, enabled for geometry on the axis (existing and created) - */ void BM_mesh_bisect_plane(BMesh *bm, const float plane[4], const bool use_snap_center, diff --git a/source/blender/bmesh/tools/bmesh_bisect_plane.h b/source/blender/bmesh/tools/bmesh_bisect_plane.h index f64b5d8097c..120935296b7 100644 --- a/source/blender/bmesh/tools/bmesh_bisect_plane.h +++ b/source/blender/bmesh/tools/bmesh_bisect_plane.h @@ -20,6 +20,11 @@ * \ingroup bmesh */ +/** + * \param use_snap_center: Snap verts onto the plane. + * \param use_tag: Only bisect tagged edges and faces. + * \param oflag_center: Operator flag, enabled for geometry on the axis (existing and created) + */ void BM_mesh_bisect_plane(BMesh *bm, const float plane[4], const bool use_snap_center, diff --git a/source/blender/bmesh/tools/bmesh_boolean.cc b/source/blender/bmesh/tools/bmesh_boolean.cc index 487ef6427af..e244bc377db 100644 --- a/source/blender/bmesh/tools/bmesh_boolean.cc +++ b/source/blender/bmesh/tools/bmesh_boolean.cc @@ -456,14 +456,6 @@ bool BM_mesh_boolean(BMesh *bm, static_cast<blender::meshintersect::BoolOpType>(boolean_mode)); } -/** - * Perform a Knife Intersection operation on the mesh bm. - * There are either one or two operands, the same as described above for BM_mesh_boolean(). - * If use_separate_all is true, each edge that is created from the intersection should - * be used to separate all its incident faces. TODO: implement that. - * TODO: need to ensure that "selected/non-selected" flag of original faces gets propagated - * to the intersection result faces. - */ bool BM_mesh_boolean_knife(BMesh *bm, struct BMLoop *(*looptris)[3], const int looptris_tot, diff --git a/source/blender/bmesh/tools/bmesh_boolean.h b/source/blender/bmesh/tools/bmesh_boolean.h index ed77242e14c..4dacc7b1095 100644 --- a/source/blender/bmesh/tools/bmesh_boolean.h +++ b/source/blender/bmesh/tools/bmesh_boolean.h @@ -35,6 +35,16 @@ bool BM_mesh_boolean(BMesh *bm, const bool hole_tolerant, const int boolean_mode); +/** + * Perform a Knife Intersection operation on the mesh `bm`. + * There are either one or two operands, the same as described above for #BM_mesh_boolean(). + * + * \param use_separate_all: When true, each edge that is created from the intersection should + * be used to separate all its incident faces. TODO: implement that. + * + * TODO: need to ensure that "selected/non-selected" flag of original faces gets propagated + * to the intersection result faces. + */ bool BM_mesh_boolean_knife(BMesh *bm, struct BMLoop *(*looptris)[3], const int looptris_tot, diff --git a/source/blender/bmesh/tools/bmesh_decimate.h b/source/blender/bmesh/tools/bmesh_decimate.h index c62288c269a..1de241a1326 100644 --- a/source/blender/bmesh/tools/bmesh_decimate.h +++ b/source/blender/bmesh/tools/bmesh_decimate.h @@ -20,6 +20,20 @@ * \ingroup bmesh */ +/** + * \brief BM_mesh_decimate + * \param bm: The mesh + * \param factor: face count multiplier [0 - 1] + * \param vweights: Optional array of vertex aligned weights [0 - 1], + * a vertex group is the usual source for this. + * \param symmetry_axis: Axis of symmetry, -1 to disable mirror decimate. + * \param symmetry_eps: Threshold when matching mirror verts. + * + * \note The caller is responsible for recalculating face and vertex normals. + * - Vertex normals are maintained while decimating, + * although they won't necessarily match the final recalculated normals. + * - Face normals are not maintained at all. + */ void BM_mesh_decimate_collapse(BMesh *bm, const float factor, float *vweights, @@ -28,6 +42,8 @@ void BM_mesh_decimate_collapse(BMesh *bm, const int symmetry_axis, const float symmetry_eps); +/** + * \param tag_only: so we can call this from an operator */ void BM_mesh_decimate_unsubdivide_ex(BMesh *bm, const int iterations, const bool tag_only); void BM_mesh_decimate_unsubdivide(BMesh *bm, const int iterations); diff --git a/source/blender/bmesh/tools/bmesh_decimate_collapse.c b/source/blender/bmesh/tools/bmesh_decimate_collapse.c index 97fccbe01fd..e90e50ef8ff 100644 --- a/source/blender/bmesh/tools/bmesh_decimate_collapse.c +++ b/source/blender/bmesh/tools/bmesh_decimate_collapse.c @@ -1277,20 +1277,6 @@ static bool bm_decim_edge_collapse(BMesh *bm, /* Main Decimate Function * ********************** */ -/** - * \brief BM_mesh_decimate - * \param bm: The mesh - * \param factor: face count multiplier [0 - 1] - * \param vweights: Optional array of vertex aligned weights [0 - 1], - * a vertex group is the usual source for this. - * \param symmetry_axis: Axis of symmetry, -1 to disable mirror decimate. - * \param symmetry_eps: Threshold when matching mirror verts. - * - * \note The caller is responsible for recalculating face and vertex normals. - * - Vertex normals are maintained while decimating, - * although they won't necessarily match the final recalculated normals. - * - Face normals are not maintained at all. - */ void BM_mesh_decimate_collapse(BMesh *bm, const float factor, float *vweights, diff --git a/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c b/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c index c96a7be1adf..ca0f31fdf75 100644 --- a/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c +++ b/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c @@ -168,8 +168,6 @@ enum { * - BMVert.index == -1: shows we will remove this vert */ -/** - * \param tag_only: so we can call this from an operator */ void BM_mesh_decimate_unsubdivide_ex(BMesh *bm, const int iterations, const bool tag_only) { #ifdef USE_WALKER diff --git a/source/blender/bmesh/tools/bmesh_edgenet.c b/source/blender/bmesh/tools/bmesh_edgenet.c index 242b269ed47..4cad1d3cb3c 100644 --- a/source/blender/bmesh/tools/bmesh_edgenet.c +++ b/source/blender/bmesh/tools/bmesh_edgenet.c @@ -422,15 +422,6 @@ static LinkNode *bm_edgenet_path_calc_best(BMEdge *e, return path; } -/** - * Fill in faces from an edgenet made up of boundary and wire edges. - * - * \note New faces currently don't have their normals calculated and are flipped randomly. - * The caller needs to flip faces correctly. - * - * \param bm: The mesh to operate on. - * \param use_edge_tag: Only fill tagged edges. - */ void BM_mesh_edgenet(BMesh *bm, const bool use_edge_tag, const bool use_new_face_tag) { VertNetInfo *vnet_info = MEM_callocN(sizeof(*vnet_info) * (size_t)bm->totvert, __func__); diff --git a/source/blender/bmesh/tools/bmesh_edgenet.h b/source/blender/bmesh/tools/bmesh_edgenet.h index 7855b2e2886..20edb30442c 100644 --- a/source/blender/bmesh/tools/bmesh_edgenet.h +++ b/source/blender/bmesh/tools/bmesh_edgenet.h @@ -20,4 +20,13 @@ * \ingroup bmesh */ +/** + * Fill in faces from an edgenet made up of boundary and wire edges. + * + * \note New faces currently don't have their normals calculated and are flipped randomly. + * The caller needs to flip faces correctly. + * + * \param bm: The mesh to operate on. + * \param use_edge_tag: Only fill tagged edges. + */ void BM_mesh_edgenet(BMesh *bm, const bool use_edge_tag, const bool use_new_face_tag); diff --git a/source/blender/bmesh/tools/bmesh_edgesplit.c b/source/blender/bmesh/tools/bmesh_edgesplit.c index 388e7f41aba..cd5200a660d 100644 --- a/source/blender/bmesh/tools/bmesh_edgesplit.c +++ b/source/blender/bmesh/tools/bmesh_edgesplit.c @@ -28,11 +28,6 @@ #include "bmesh_edgesplit.h" /* own include */ -/** - * \param use_verts: Use flagged verts instead of edges. - * \param tag_only: Only split tagged edges. - * \param copy_select: Copy selection history. - */ void BM_mesh_edgesplit(BMesh *bm, const bool use_verts, const bool tag_only, diff --git a/source/blender/bmesh/tools/bmesh_edgesplit.h b/source/blender/bmesh/tools/bmesh_edgesplit.h index 4d3db67ef5f..bcbb3ab7857 100644 --- a/source/blender/bmesh/tools/bmesh_edgesplit.h +++ b/source/blender/bmesh/tools/bmesh_edgesplit.h @@ -24,6 +24,11 @@ extern "C" { #endif +/** + * \param use_verts: Use flagged verts instead of edges. + * \param tag_only: Only split tagged edges. + * \param copy_select: Copy selection history. + */ void BM_mesh_edgesplit(BMesh *bm, const bool use_verts, const bool tag_only, diff --git a/source/blender/bmesh/tools/bmesh_intersect.c b/source/blender/bmesh/tools/bmesh_intersect.c index 947442c7bd8..6824dd5008a 100644 --- a/source/blender/bmesh/tools/bmesh_intersect.c +++ b/source/blender/bmesh/tools/bmesh_intersect.c @@ -947,14 +947,6 @@ static int isect_bvhtree_point_v3(BVHTree *tree, const float **looptris, const f #endif /* USE_BVH */ -/** - * Intersect tessellated faces - * leaving the resulting edges tagged. - * - * \param test_fn: Return value: -1: skip, 0: tree_a, 1: tree_b (use_self == false) - * \param boolean_mode: -1: no-boolean, 0: intersection... see #BMESH_ISECT_BOOLEAN_ISECT. - * \return true if the mesh is changed (intersections cut or faces removed from boolean). - */ bool BM_mesh_intersect(BMesh *bm, struct BMLoop *(*looptris)[3], const int looptris_tot, diff --git a/source/blender/bmesh/tools/bmesh_intersect.h b/source/blender/bmesh/tools/bmesh_intersect.h index d09ea67a3bb..a6c91715f31 100644 --- a/source/blender/bmesh/tools/bmesh_intersect.h +++ b/source/blender/bmesh/tools/bmesh_intersect.h @@ -24,6 +24,14 @@ extern "C" { #endif +/** + * Intersect tessellated faces + * leaving the resulting edges tagged. + * + * \param test_fn: Return value: -1: skip, 0: tree_a, 1: tree_b (use_self == false) + * \param boolean_mode: -1: no-boolean, 0: intersection... see #BMESH_ISECT_BOOLEAN_ISECT. + * \return true if the mesh is changed (intersections cut or faces removed from boolean). + */ bool BM_mesh_intersect(BMesh *bm, struct BMLoop *(*looptris)[3], const int looptris_tot, diff --git a/source/blender/bmesh/tools/bmesh_region_match.c b/source/blender/bmesh/tools/bmesh_region_match.c index 924538490ad..8a909cbc9fd 100644 --- a/source/blender/bmesh/tools/bmesh_region_match.c +++ b/source/blender/bmesh/tools/bmesh_region_match.c @@ -1332,12 +1332,6 @@ static void bm_vert_fasthash_destroy(UUIDFashMatch *fm) #endif /* USE_PIVOT_FASTMATCH */ -/** - * Take a face-region and return a list of matching face-regions. - * - * \param faces_region: A single, contiguous face-region. - * \return A list of matching null-terminated face-region arrays. - */ int BM_mesh_region_match(BMesh *bm, BMFace **faces_region, uint faces_region_len, diff --git a/source/blender/bmesh/tools/bmesh_region_match.h b/source/blender/bmesh/tools/bmesh_region_match.h index 799af938c31..7b7233783ce 100644 --- a/source/blender/bmesh/tools/bmesh_region_match.h +++ b/source/blender/bmesh/tools/bmesh_region_match.h @@ -20,6 +20,12 @@ * \ingroup bmesh */ +/** + * Take a face-region and return a list of matching face-regions. + * + * \param faces_region: A single, contiguous face-region. + * \return A list of matching null-terminated face-region arrays. + */ int BM_mesh_region_match(BMesh *bm, BMFace **faces_region, uint faces_region_len, diff --git a/source/blender/bmesh/tools/bmesh_separate.c b/source/blender/bmesh/tools/bmesh_separate.c index 3c69ea111bf..e00829604d5 100644 --- a/source/blender/bmesh/tools/bmesh_separate.c +++ b/source/blender/bmesh/tools/bmesh_separate.c @@ -32,10 +32,6 @@ #include "bmesh_separate.h" /* own include */ #include "intern/bmesh_private.h" -/** - * Split all faces that match `filter_fn`. - * \note - */ void BM_mesh_separate_faces(BMesh *bm, BMFaceFilterFunc filter_fn, void *user_data) { BMFace **faces_array_all = MEM_mallocN(bm->totface * sizeof(BMFace *), __func__); diff --git a/source/blender/bmesh/tools/bmesh_separate.h b/source/blender/bmesh/tools/bmesh_separate.h index 9260903a8fa..8c599eef2b0 100644 --- a/source/blender/bmesh/tools/bmesh_separate.h +++ b/source/blender/bmesh/tools/bmesh_separate.h @@ -20,4 +20,8 @@ * \ingroup bmesh */ +/** + * Split all faces that match `filter_fn`. + * \note + */ void BM_mesh_separate_faces(BMesh *bm, BMFaceFilterFunc filter_fn, void *user_data); diff --git a/source/blender/bmesh/tools/bmesh_wireframe.c b/source/blender/bmesh/tools/bmesh_wireframe.c index af4a4424103..67010fc89c7 100644 --- a/source/blender/bmesh/tools/bmesh_wireframe.c +++ b/source/blender/bmesh/tools/bmesh_wireframe.c @@ -152,12 +152,6 @@ static bool bm_loop_is_radial_boundary(BMLoop *l_first) return true; } -/** - * \param defgrp_index: Vertex group index, -1 for no vertex groups. - * - * \note All edge tags must be cleared. - * \note Behavior matches MOD_solidify.c - */ void BM_mesh_wireframe(BMesh *bm, const float offset, const float offset_fac, diff --git a/source/blender/bmesh/tools/bmesh_wireframe.h b/source/blender/bmesh/tools/bmesh_wireframe.h index b2c2f5f5523..5b64a16435f 100644 --- a/source/blender/bmesh/tools/bmesh_wireframe.h +++ b/source/blender/bmesh/tools/bmesh_wireframe.h @@ -22,6 +22,12 @@ #pragma once +/** + * \param defgrp_index: Vertex group index, -1 for no vertex groups. + * + * \note All edge tags must be cleared. + * \note Behavior matches MOD_solidify.c + */ void BM_mesh_wireframe(BMesh *bm, const float offset, const float offset_fac, |