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_mesh_mapping.h | 79 +++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) (limited to 'source/blender/blenkernel/BKE_mesh_mapping.h') diff --git a/source/blender/blenkernel/BKE_mesh_mapping.h b/source/blender/blenkernel/BKE_mesh_mapping.h index 0518f303744..acc1628de1d 100644 --- a/source/blender/blenkernel/BKE_mesh_mapping.h +++ b/source/blender/blenkernel/BKE_mesh_mapping.h @@ -105,6 +105,11 @@ UvVertMap *BKE_mesh_uv_vert_map_create(const struct MPoly *mpoly, UvMapVert *BKE_mesh_uv_vert_map_get_vert(UvVertMap *vmap, unsigned int v); void BKE_mesh_uv_vert_map_free(UvVertMap *vmap); +/** + * Generates a map where the key is the vertex and the value + * is a list of polys that use that vertex as a corner. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -112,6 +117,11 @@ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, int totvert, int totpoly, int totloop); +/** + * Generates a map where the key is the vertex and the value + * is a list of loops that use that vertex as a corner. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -119,6 +129,11 @@ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, int totvert, int totpoly, int totloop); +/** + * Generates a map where the key is the edge and the value + * is a list of looptris that use that edge. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, int **r_mem, const struct MVert *mvert, @@ -127,10 +142,24 @@ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, const int totlooptri, const struct MLoop *mloop, const int totloop); +/** + * Generates a map where the key is the vertex and the value + * is a list of edges that use that vertex as an endpoint. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_edge_map_create( MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge); +/** + * A version of #BKE_mesh_vert_edge_map_create that references connected vertices directly + * (not their edges). + */ void BKE_mesh_vert_edge_vert_map_create( MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge); +/** + * Generates a map where the key is the edge and the value is a list of loops that use that edge. + * Loops indices of a same poly are contiguous and in winding order. + * The lists are allocated from one memory pool. + */ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, @@ -139,6 +168,11 @@ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, const int totpoly, const struct MLoop *mloop, const int totloop); +/** + * Generates a map where the key is the edge and the value + * is a list of polygons that use that edge. + * The lists are allocated from one memory pool. + */ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, @@ -147,11 +181,29 @@ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, const int totpoly, const struct MLoop *mloop, const int totloop); +/** + * This function creates a map so the source-data (vert/edge/loop/poly) + * can loop over the destination data (using the destination arrays origindex). + * + * This has the advantage that it can operate on any data-types. + * + * \param totsource: The total number of elements that \a final_origindex points to. + * \param totfinal: The size of \a final_origindex + * \param final_origindex: The size of the final array. + * + * \note `totsource` could be `totpoly`, + * `totfinal` could be `tottessface` and `final_origindex` its ORIGINDEX custom-data. + * This would allow an MPoly to loop over its tessfaces. + */ void BKE_mesh_origindex_map_create(MeshElemMap **r_map, int **r_mem, const int totsource, const int *final_origindex, const int totfinal); +/** + * A version of #BKE_mesh_origindex_map_create that takes a looptri array. + * Making a poly -> looptri map. + */ void BKE_mesh_origindex_map_create_looptri(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -212,7 +264,11 @@ typedef bool (*MeshRemapIslandsCalc)(struct MVert *verts, struct MeshIslandStore *r_island_store); /* Above vert/UV mapping stuff does not do what we need here, but does things we do not need here. - * So better keep them separated for now, I think. + * So better keep them separated for now, I think. */ + +/** + * Calculate 'generic' UV islands, i.e. based only on actual geometry data (edge seams), + * not some UV layers coordinates. */ bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts, const int totvert, @@ -224,6 +280,19 @@ bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts, const int totloop, MeshIslandStore *r_island_store); +/** + * Calculate UV islands. + * + * \note If no MLoopUV layer is passed, we only consider edges tagged as seams as UV boundaries. + * This has the advantages of simplicity, and being valid/common to all UV maps. + * However, it means actual UV islands without matching UV seams will not be handled correctly. + * If a valid UV layer is passed as \a luvs parameter, + * UV coordinates are also used to detect islands boundaries. + * + * \note All this could be optimized. + * Not sure it would be worth the more complex code, though, + * those loops are supposed to be really quick to do. + */ bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts, const int totvert, struct MEdge *edges, @@ -235,6 +304,14 @@ bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts, const struct MLoopUV *luvs, MeshIslandStore *r_island_store); +/** + * Calculate smooth groups from sharp edges. + * + * \param r_totgroup: The total number of groups, 1 or more. + * \return Polygon aligned array of group index values (bitflags if use_bitflags is true), + * starting at 1 (0 being used as 'invalid' flag). + * Note it's callers's responsibility to MEM_freeN returned array. + */ int *BKE_mesh_calc_smoothgroups(const struct MEdge *medge, const int totedge, const struct MPoly *mpoly, -- cgit v1.2.3