diff options
Diffstat (limited to 'source/blender/bmesh/intern/bmesh_core.c')
-rw-r--r-- | source/blender/bmesh/intern/bmesh_core.c | 249 |
1 files changed, 125 insertions, 124 deletions
diff --git a/source/blender/bmesh/intern/bmesh_core.c b/source/blender/bmesh/intern/bmesh_core.c index 290668de10b..2e5b95dc4db 100644 --- a/source/blender/bmesh/intern/bmesh_core.c +++ b/source/blender/bmesh/intern/bmesh_core.c @@ -20,7 +20,7 @@ * ***** END GPL LICENSE BLOCK ***** */ -/** \file blender/bmesh/intern/bmesh_newcore.c +/** \file blender/bmesh/intern/bmesh_core.c * \ingroup bmesh * */ @@ -445,7 +445,8 @@ int bmesh_elem_check(BMesh *UNUSED(bm), void *element, const char htype) return err; } -/* low level function, only free's, +/** + * low level function, only free's, * does not change adjust surrounding geometry */ static void bm_kill_only_vert(BMesh *bm, BMVert *v) { @@ -632,21 +633,6 @@ void BM_vert_kill(BMesh *bm, BMVert *v) /********** private disk and radial cycle functions ********** */ -/** - * bmesh_loop_reverse - * - * FLIP FACE EULER - * - * Changes the winding order of a face from CW to CCW or vice versa. - * This euler is a bit peculiar in compairson to others as it is its - * own inverse. - * - * BMESH_TODO: reinsert validation code. - * - * Returns - - * 1 for success, 0 for failure. - */ - static int bm_loop_length(BMLoop *l) { BMLoop *l_first = l; @@ -659,6 +645,17 @@ static int bm_loop_length(BMLoop *l) return i; } +/** + * \brief Loop Reverse + * + * Changes the winding order of a face from CW to CCW or vice versa. + * This euler is a bit peculiar in compairson to others as it is its + * own inverse. + * + * BMESH_TODO: reinsert validation code. + * + * \return Success + */ static int bm_loop_reverse_loop(BMesh *bm, BMFace *f #ifdef USE_BMESH_HOLES , BMLoopList *lst @@ -856,16 +853,18 @@ static int disk_is_flagged(BMVert *v, int flag) /* Midlevel Topology Manipulation Functions */ /** + * \brief Join Connected Faces + * * Joins a collected group of faces into one. Only restriction on * the input data is that the faces must be connected to each other. * - * If a pair of faces share multiple edges, the pair of - * faces will be joined at every edge. + * \return The newly created combine BMFace. * - * Returns a pointer to the combined face. + * \note If a pair of faces share multiple edges, + * the pair of faces will be joined at every edge. * - * \note this is a generic, flexible join faces function, almost everything - * uses this, including #BM_faces_join_pair + * \note this is a generic, flexible join faces function, + * almost everything uses this, including #BM_faces_join_pair */ BMFace *BM_faces_join(BMesh *bm, BMFace **faces, int totface) { @@ -1045,8 +1044,6 @@ error: return NULL; } -/* BMESH_TODO - this is only used once, investigate sharing code with BM_face_create - */ static BMFace *bm_face_create__sfme(BMesh *bm, BMFace *UNUSED(example)) { BMFace *f; @@ -1069,41 +1066,38 @@ static BMFace *bm_face_create__sfme(BMesh *bm, BMFace *UNUSED(example)) } /** - * bmesh_SFME - * - * SPLIT FACE MAKE EDGE: + * \brief Split Face Make Edge (SFME) * - * Takes as input two vertices in a single face. An edge is created which divides the original face - * into two distinct regions. One of the regions is assigned to the original face and it is closed off. - * The second region has a new face assigned to it. + * Takes as input two vertices in a single face. An edge is created which divides the original face + * into two distinct regions. One of the regions is assigned to the original face and it is closed off. + * The second region has a new face assigned to it. * - * Examples: + * \par Examples: * * Before: After: - * ---------- ---------- - * | | | | - * | | | f1 | - * v1 f1 v2 v1======v2 - * | | | f2 | - * | | | | - * ---------- ---------- + * ---------- ---------- + * | | | | + * | | | f1 | + * v1 f1 v2 v1======v2 + * | | | f2 | + * | | | | + * ---------- ---------- * - * Note that the input vertices can be part of the same edge. This will - * result in a two edged face. This is desirable for advanced construction - * tools and particularly essential for edge bevel. Because of this it is - * up to the caller to decide what to do with the extra edge. + * \note the input vertices can be part of the same edge. This will + * result in a two edged face. This is desirable for advanced construction + * tools and particularly essential for edge bevel. Because of this it is + * up to the caller to decide what to do with the extra edge. * - * If holes is NULL, then both faces will lose - * all holes from the original face. Also, you cannot split between - * a hole vert and a boundary vert; that case is handled by higher- - * level wrapping functions (when holes are fully implemented, anyway). + * \note If \a holes is NULL, then both faces will lose + * all holes from the original face. Also, you cannot split between + * a hole vert and a boundary vert; that case is handled by higher- + * level wrapping functions (when holes are fully implemented, anyway). * - * Note that holes represents which holes goes to the new face, and of - * course this requires removing them from the exitsing face first, since - * you cannot have linked list links inside multiple lists. + * \note that holes represents which holes goes to the new face, and of + * course this requires removing them from the exitsing face first, since + * you cannot have linked list links inside multiple lists. * - * Returns - - * A BMFace pointer + * \return A BMFace pointer */ BMFace *bmesh_sfme(BMesh *bm, BMFace *f, BMVert *v1, BMVert *v2, BMLoop **r_l, @@ -1211,20 +1205,17 @@ BMFace *bmesh_sfme(BMesh *bm, BMFace *f, BMVert *v1, BMVert *v2, } /** - * bmesh_SEMV + * \brief Split Edge Make Vert (SEMV) * - * SPLIT EDGE MAKE VERT: - * Takes a given edge and splits it into two, creating a new vert. + * Takes \a e edge and splits it into two, creating a new vert. * + * \par Examples: * - * Before: OV---------TV - * After: OV----NV---TV - * - * Returns - - * BMVert pointer. + * Before: OV---------TV + * After: OV----NV---TV * + * \return The newly created BMVert pointer. */ - BMVert *bmesh_semv(BMesh *bm, BMVert *tv, BMEdge *e, BMEdge **r_e) { BMLoop *nextl; @@ -1385,35 +1376,33 @@ BMVert *bmesh_semv(BMesh *bm, BMVert *tv, BMEdge *e, BMEdge **r_e) } /** - * bmesh_JEKV + * \brief Join Edge Kill Vert (JEKV) * - * JOIN EDGE KILL VERT: - * Takes a an edge and pointer to one of its vertices and collapses - * the edge on that vertex. + * Takes an edge \a ke and pointer to one of its vertices \a kv + * and collapses the edge on that vertex. * - * Before: OE KE - * ------- ------- - * | || | - * OV KV TV + * \par Examples: * + * Before: OE KE + * ------- ------- + * | || | + * OV KV TV * - * After: OE - * --------------- - * | | - * OV TV * + * After: OE + * --------------- + * | | + * OV TV * - * Restrictions: - * KV is a vertex that must have a valance of exactly two. Furthermore - * both edges in KV's disk cycle (OE and KE) must be unique (no double - * edges). + * \par Restrictions: + * KV is a vertex that must have a valance of exactly two. Furthermore + * both edges in KV's disk cycle (OE and KE) must be unique (no double edges). * - * It should also be noted that this euler has the possibility of creating - * faces with just 2 edges. It is up to the caller to decide what to do with - * these faces. + * \return The resulting edge, NULL for failure. * - * Returns - - * The resulting edge, NULL for failure. + * \note This euler has the possibility of creating + * faces with just 2 edges. It is up to the caller to decide what to do with + * these faces. */ BMEdge *bmesh_jekv(BMesh *bm, BMEdge *ke, BMVert *kv, const short check_edge_double) { @@ -1548,35 +1537,34 @@ BMEdge *bmesh_jekv(BMesh *bm, BMEdge *ke, BMVert *kv, const short check_edge_dou } /** - * bmesh_JFKE + * \brief Join Face Kill Edge (JFKE) * - * JOIN FACE KILL EDGE: + * Takes two faces joined by a single 2-manifold edge and fuses them togather. + * The edge shared by the faces must not be connected to any other edges which have + * Both faces in its radial cycle * - * Takes two faces joined by a single 2-manifold edge and fuses them togather. - * The edge shared by the faces must not be connected to any other edges which have - * Both faces in its radial cycle + * \par Examples: * - * Examples: + * A B + * ---------- ---------- + * | | | | + * | f1 | | f1 | + * v1========v2 = Ok! v1==V2==v3 == Wrong! + * | f2 | | f2 | + * | | | | + * ---------- ---------- * - * A B - * ---------- ---------- - * | | | | - * | f1 | | f1 | - * v1========v2 = Ok! v1==V2==v3 == Wrong! - * | f2 | | f2 | - * | | | | - * ---------- ---------- + * In the example A, faces \a f1 and \a f2 are joined by a single edge, + * and the euler can safely be used. + * In example B however, \a f1 and \a f2 are joined by multiple edges and will produce an error. + * The caller in this case should call #bmesh_jekv on the extra edges + * before attempting to fuse \a f1 and \a f2. * - * In the example A, faces f1 and f2 are joined by a single edge, and the euler can safely be used. - * In example B however, f1 and f2 are joined by multiple edges and will produce an error. The caller - * in this case should call bmesh_JEKV on the extra edges before attempting to fuse f1 and f2. + * \note The order of arguments decides whether or not certain per-face attributes are present + * in the resultant face. For instance vertex winding, material index, smooth flags, ect are inherited + * from \a f1, not \a f2. * - * Also note that the order of arguments decides whether or not certain per-face attributes are present - * in the resultant face. For instance vertex winding, material index, smooth flags, ect are inherited - * from f1, not f2. - * - * Returns - - * A BMFace pointer + * \return A BMFace pointer */ BMFace *bmesh_jfke(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e) { @@ -1703,10 +1691,12 @@ BMFace *bmesh_jfke(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e) return f1; } -/* - * BMESH SPLICE VERT +/** + * \brief Splice Vert * - * merges two verts into one (v into vtarget). + * Merges two verts into one (\a v into \a vtarget). + * + * \return Success */ static int bm_vert_splice(BMesh *bm, BMVert *v, BMVert *vtarget) { @@ -1740,11 +1730,13 @@ static int bm_vert_splice(BMesh *bm, BMVert *v, BMVert *vtarget) return TRUE; } -/* BMESH CUT VERT +/** + * \brief Cut Vert * - * cut all disjoint fans that meet at a vertex, making a unique - * vertex for each region. returns an array of all resulting - * vertices. + * Cut all disjoint fans that meet at a vertex, making a unique + * vertex for each region. returns an array of all resulting vertices. + * + * \return Success */ static int bm_vert_cut(BMesh *bm, BMVert *v, BMVert ***vout, int *len) { @@ -1843,11 +1835,14 @@ static int bm_vert_cut(BMesh *bm, BMVert *v, BMVert ***vout, int *len) return TRUE; } -/* BMESH SPLICE EDGE +/** + * \brief Splice Edge * - * splice two unique edges which share the same two vertices into one edge. + * Splice two unique edges which share the same two vertices into one edge. * - * edges must already have the same vertices + * \return Success + * + * \note Edges must already have the same vertices. */ static int bm_edge_splice(BMesh *bm, BMEdge *e, BMEdge *etarget) { @@ -1877,13 +1872,15 @@ static int bm_edge_splice(BMesh *bm, BMEdge *e, BMEdge *etarget) return TRUE; } -/* - * BMESH CUT EDGE +/** + * \brief Cut Edge * * Cuts a single edge into two edge: the original edge and - * a new edge that has only "cutl" in its radial. + * a new edge that has only \a cutl in its radial. + * + * \return Success * - * Does nothing if cutl is already the only loop in the + * \note Does nothing if \a cutl is already the only loop in the * edge radial. */ static int bm_edge_cut(BMesh *bm, BMEdge *e, BMLoop *cutl) @@ -1918,10 +1915,12 @@ static int bm_edge_cut(BMesh *bm, BMEdge *e, BMLoop *cutl) return TRUE; } -/* - * BMESH UNGLUE REGION MAKE VERT +/** + * \brief Unglue Region Make Vert (URMV) * - * Disconnects a face from its vertex fan at loop sl. + * Disconnects a face from its vertex fan at loop \a sl + * + * \return The newly created BMVert */ static BMVert *bm_urmv_loop(BMesh *bm, BMLoop *sl) { @@ -1991,10 +1990,12 @@ static BMVert *bm_urmv_loop(BMesh *bm, BMLoop *sl) return nv; } -/* - * BMESH UNGLUE REGION MAKE VERT +/** + * \brief Unglue Region Make Vert (URMV) + * + * Disconnects sf from the vertex fan at \a sv * - * Disconnects sf from the vertex fan at sv + * \return The newly created BMVert */ BMVert *bmesh_urmv(BMesh *bm, BMFace *sf, BMVert *sv) { |