From 21f1c99a781b6747eeace208c6786ab427eb39fc Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Mon, 27 Feb 2012 12:25:47 +0000
Subject: [PATCH] update bmesh design doc and added some comments to the code
 from it.

---
 source/blender/bmesh/bmesh_class.h        |  4 +--
 source/blender/bmesh/bmesh_operator_api.h | 34 ++++++++++++-----------
 source/blender/bmesh/bmesh_walkers.h      |  7 +++--
 3 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/source/blender/bmesh/bmesh_class.h b/source/blender/bmesh/bmesh_class.h
index 5a0158a7b9a..d800fe7bf77 100644
--- a/source/blender/bmesh/bmesh_class.h
+++ b/source/blender/bmesh/bmesh_class.h
@@ -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 @@ typedef struct BMLoop {
 	/* 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;
diff --git a/source/blender/bmesh/bmesh_operator_api.h b/source/blender/bmesh/bmesh_operator_api.h
index f6d33dd1b50..24b63815ec8 100644
--- a/source/blender/bmesh/bmesh_operator_api.h
+++ b/source/blender/bmesh/bmesh_operator_api.h
@@ -90,24 +90,26 @@ BM_INLINE void  _bmo_elem_flag_toggle(BMesh *bm, BMFlagLayer *oflags, const shor
 
 /* 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.*/
diff --git a/source/blender/bmesh/bmesh_walkers.h b/source/blender/bmesh/bmesh_walkers.h
index 9dff8cd98fb..de8da23aec7 100644
--- a/source/blender/bmesh/bmesh_walkers.h
+++ b/source/blender/bmesh/bmesh_walkers.h
@@ -40,9 +40,9 @@ typedef enum {
 
 /*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 @@ typedef struct BMWalker {
 	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;