[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [44480] trunk/blender/source/blender/bmesh : update bmesh design doc and added some comments to the code from it.

Campbell Barton ideasman42 at gmail.com
Mon Feb 27 13:25:58 CET 2012 

Revision: 44480
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=44480
Author:   campbellbarton
Date:     2012-02-27 12:25:47 +0000 (Mon, 27 Feb 2012)
Log Message:
-----------
update bmesh design doc and added some comments to the code from it.

Modified Paths:
--------------
    trunk/blender/source/blender/bmesh/bmesh_class.h
    trunk/blender/source/blender/bmesh/bmesh_operator_api.h
    trunk/blender/source/blender/bmesh/bmesh_walkers.h
    trunk/blender/source/blender/bmesh/docs/bmesh_design.mwiki

Modified: trunk/blender/source/blender/bmesh/bmesh_class.h
===================================================================
--- trunk/blender/source/blender/bmesh/bmesh_class.h	2012-02-27 10:35:39 UTC (rev 44479)
+++ trunk/blender/source/blender/bmesh/bmesh_class.h	2012-02-27 12:25:47 UTC (rev 44480)
@@ -30,7 +30,7 @@
 /* bmesh data structures */
 
 /* dissable holes for now, these are ifdef'd because they use more memory and cant be saved in DNA currently */
-// define USE_BMESH_HOLES
+#define USE_BMESH_HOLES
 
 struct BMesh;
 struct BMVert;
@@ -95,7 +95,7 @@
 	/* notice no flags layer */
 
 	struct BMVert *v;
-	struct BMEdge *e;
+	struct BMEdge *e; /* edge, using verts (v, next->v) */
 	struct BMFace *f;
 
 	struct BMLoop *radial_next, *radial_prev;

Modified: trunk/blender/source/blender/bmesh/bmesh_operator_api.h
===================================================================
--- trunk/blender/source/blender/bmesh/bmesh_operator_api.h	2012-02-27 10:35:39 UTC (rev 44479)
+++ trunk/blender/source/blender/bmesh/bmesh_operator_api.h	2012-02-27 12:25:47 UTC (rev 44480)
@@ -90,24 +90,26 @@
 
 /* slot type arrays are terminated by the last member
  * having a slot type of 0.*/
-#define BMO_OP_SLOT_SENTINEL	0
-#define BMO_OP_SLOT_BOOL		1
-#define BMO_OP_SLOT_INT			2
-#define BMO_OP_SLOT_FLT			3
-#define BMO_OP_SLOT_PNT			4
-#define BMO_OP_SLOT_MAT			5
-#define BMO_OP_SLOT_VEC			8
+enum {
+	BMO_OP_SLOT_SENTINEL = 0,
+	BMO_OP_SLOT_BOOL = 1,
+	BMO_OP_SLOT_INT = 2,
+	BMO_OP_SLOT_FLT = 3,
 
-/* after BMO_OP_SLOT_VEC, everything is
+	/* normally store pointers to object, scene,
+	 * _never_ store arrays corresponding to mesh elements with this */
+	BMO_OP_SLOT_PNT = 4,
+	BMO_OP_SLOT_MAT = 5,
+	BMO_OP_SLOT_VEC = 8,
 
- * dynamically allocated arrays.  we
- * leave a space in the identifiers
- * for future growth.
- */
-//it's very important this remain a power of two
-#define BMO_OP_SLOT_ELEMENT_BUF		9
-#define BMO_OP_SLOT_MAPPING			10
-#define BMO_OP_SLOT_TOTAL_TYPES		11
+	/* after BMO_OP_SLOT_VEC, everything is dynamically allocated arrays.
+	 * We leave a space in the identifiers for future growth.
+	 *
+	 * it's very important this remain a power of two */
+	BMO_OP_SLOT_ELEMENT_BUF = 9, /* list of verts/edges/faces */
+	BMO_OP_SLOT_MAPPING = 10 /* simple hash map */
+};
+#define BMO_OP_SLOT_TOTAL_TYPES 11
 
 /* please ignore all these structures, don't touch them in tool code, except
  * for when your defining an operator with BMOpDefine.*/

Modified: trunk/blender/source/blender/bmesh/bmesh_walkers.h
===================================================================
--- trunk/blender/source/blender/bmesh/bmesh_walkers.h	2012-02-27 10:35:39 UTC (rev 44479)
+++ trunk/blender/source/blender/bmesh/bmesh_walkers.h	2012-02-27 12:25:47 UTC (rev 44480)
@@ -40,9 +40,9 @@
 
 /*Walkers*/
 typedef struct BMWalker {
-	void (*begin) (struct BMWalker *walker, void *start);
-	void *(*step) (struct BMWalker *walker);
-	void *(*yield)(struct BMWalker *walker);
+	void  (*begin) (struct BMWalker *walker, void *start);
+	void *(*step)  (struct BMWalker *walker);
+	void *(*yield) (struct BMWalker *walker);
 	int structsize;
 	BMWOrder order;
 	int valid_mask;
@@ -54,6 +54,7 @@
 	BLI_mempool *worklist;
 	ListBase states;
 
+	/* these masks are to be tested against elements BMO_elem_flag_test() */
 	short mask_vert;
 	short mask_edge;
 	short mask_loop;

Modified: trunk/blender/source/blender/bmesh/docs/bmesh_design.mwiki
===================================================================
--- trunk/blender/source/blender/bmesh/docs/bmesh_design.mwiki	2012-02-27 10:35:39 UTC (rev 44479)
+++ trunk/blender/source/blender/bmesh/docs/bmesh_design.mwiki	2012-02-27 12:25:47 UTC (rev 44480)
@@ -1,102 +1,139 @@
-{{Note|Note|Don't edit this page, instead edit the version in the bmesh branch, in source/blender/bmesh/docs/bmesh_design.mwiki (obviously you must be a committer involved in the bmesh project for this).  The idea is that having the documentation inside the repository, will remind us devs to update it more often.}} 
+{{Note|Note|Don't edit this page, instead edit the version in the bmesh branch, in source/blender/bmesh/docs/bmesh_design.mwiki (obviously you must be a committer involved in the bmesh project for this).  The idea is that having the documentation inside the repository, will remind us devs to update it more often.}}
 
+
 = Introduction  =
 
-BMesh is a non-manifold boundary representation. It was designed to replace the current, limited EditMesh structure, solving many of the design limitations and maintainance issues of EditMesh. 
+BMesh is a non-manifold boundary representation. It was designed to replace the current, limited EditMesh structure, solving many of the design limitations and maintenance issues of EditMesh.
 
+
 == The Structure  ==
 
-BMesh stores topology in four main element structures: 
+BMesh stores topology in four main element structures:
 
-*Faces 
-*Loops (stores per-face-vertex data, uvs, vcols, etc) 
-*Edges 
-*Verts
+* Faces
+* Loops (stores per-face-vertex data, UV's, vertex-colors, etc)
+* Edges
+* Verts
 
-===Persistent Flags===
-Each element (vertex/edge/face) in a mesh has an associated persistent bitfield, accessable through BM_TestHFlag, BM_ClearHFlag and BM_SetHFlag.  These are called "header flags", also "persistent flags" ("header flags" will be dropped just as soon as all the relevent API functions are renamed to match "persisten flags").
 
-Persistent flags should *never* be read or written to by bmesh operators (see Operators below).
+=== Header Flags ===
+Each element (vertex/edge/face/loop) in a mesh has an associated bit-field called "header flags".
 
+Header flags should *never* be read or written to by bmesh operators (see Operators below).
+
+Access to header flags is done with BM_elem_flag_*() functions.
+
+
 === Faces  ===
 
-Faces in BMesh are stored as a circular linked list of loops. Loops store per-face-vertex data (amongst other things outlined later in this document), and define the face boundary. 
+Faces in BMesh are stored as a circular linked list of loops. Loops store per-face-vertex data (amongst other things outlined later in this document), and define the face boundary.
 
+
 === The Loop  ===
 
-Loops define the boundary loop of a face. Each loop logically corresponds to an edge, which is defined by the loop and succeeding loop's vertices. 
+Loops define the boundary loop of a face. Each loop logically corresponds to an edge, which is defined by the loop and next loop's vertices.
 
-Loops store several handy pointers: 
+Loops store several handy pointers:
 
-*v - pointer to the vertex associated with this loop.
-*e - pointer to the edge associated with this loop.
-*f - pointer to the face associated with this loop.
+* v - pointer to the vertex associated with this loop.
+* e - pointer to the edge associated with this loop.
+* f - pointer to the face associated with this loop.
 
+
 === 2-Sided Faces  ===
 
-There are some situations where you need 2-sided faces (e.g. a face of two vertices). This is supported by BMesh, but note that such faces should only be used as intermediary steps, and should not end up in the final mesh. 
+There are some situations where you need 2-sided faces (e.g. a face of two vertices).
+This is supported by BMesh, but note that such faces should only be used as intermediary steps, and should not end up in the final mesh.
 
+
 === Edges and Vertices  ===
 
-Edges and Vertices in BMesh are much like their counterparts in EditMesh, except for some members private to the BMesh api.  Note that there can be more then one edge between two vertices in bmesh, though the rest of blender (e.g. DerivedMesh, CDDM, CCGSubSurf, etc) does not support this.
+Edges and Vertices in BMesh are much like their counterparts in EditMesh, except for some members private to the BMesh api.
+Note that there can be more then one edge between two vertices in bmesh, though the rest of blender (e.g. DerivedMesh, CDDM, CCGSubSurf, etc) does not support this.
 
+
 === Queries  ===
 
-The following topological queries are available: 
+The following topological queries are available:
 
-*Edges/Faces/Loops around a vertex. 
-*Faces around an edge. 
+*Edges/Faces/Loops around a vertex.
+*Faces around an edge.
 *Loops around an edge.
 
-These are accessible through the iterator api, which is covered later in this document 
+These are accessible through the iterator api, which is covered later in this document
 
 See source/blender/bmesh/bmesh_queries.h for more misc. queries.
 
-== The BMesh API  ==
 
-One of the goals of the BMesh API is to make it easy and natural to produce highly maintainable code. Code duplication, etc are avoided where possibe. 
+== The BMesh API ==
 
+One of the goals of the BMesh API is to make it easy and natural to produce highly maintainable code. Code duplication, etc are avoided where possible.
+
+
 === Iterator API  ===
 
-Most topological queries in BMesh go through an iterator API (see Queries above). These are defined in bmesh_iterators.h.  If you can, please use the BM_ITER macro in bmesh_iterators.h.
+Most topological queries in BMesh go through an iterator API (see Queries above). These are defined in bmesh_iterators.h.  If you can, please use the BM_ITER macro in bmesh_iterators.h
 
+
 === Walker API  ===
 
-Topological queries that require a stack (e.g. recursive queries) go through the Walker API, which is defined in bmesh_walkers.h. Currently the "walkers" are hard-coded into the API, though a mechanism for plugging in new walkers needs to be added at some point. 
+Topological queries that require a stack (e.g. recursive queries) go through the Walker API, which is defined in bmesh_walkers.h. Currently the "walkers" are hard-coded into the API, though a mechanism for plugging in new walkers needs to be added at some point.
 
 Most topological queries should go through these two APIs; there are additional functions you can use for topological iteration, but their meant for internal bmesh code.
 
+Note that the walker API supports delimiter flags, to allow the caller to flag elements not to walk past.
+
+
 === Operators  ===
 

@@ Diff output truncated at 10240 characters. @@

More information about the Bf-blender-cvs mailing list