[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [19279] branches/bmesh/blender/source/ blender/bmesh: further code comments.
Joseph Eagar
joeedh at gmail.com
Sat Mar 14 03:52:18 CET 2009
Revision: 19279
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=19279
Author: joeedh
Date: 2009-03-14 03:52:16 +0100 (Sat, 14 Mar 2009)
Log Message:
-----------
further code comments. used a somewhat minimilistic style for the function comments, so people won't hate me.
Modified Paths:
--------------
branches/bmesh/blender/source/blender/bmesh/bmesh.h
branches/bmesh/blender/source/blender/bmesh/bmesh_iterators.h
branches/bmesh/blender/source/blender/bmesh/bmesh_operator_api.h
branches/bmesh/blender/source/blender/bmesh/bmesh_operators.h
branches/bmesh/blender/source/blender/bmesh/bmesh_queries.h
branches/bmesh/blender/source/blender/bmesh/intern/bmesh_queries.c
branches/bmesh/blender/source/blender/bmesh/intern/bmesh_walkers.c
branches/bmesh/blender/source/blender/bmesh/operators/dissolveops.c
Modified: branches/bmesh/blender/source/blender/bmesh/bmesh.h
===================================================================
--- branches/bmesh/blender/source/blender/bmesh/bmesh.h 2009-03-13 23:35:15 UTC (rev 19278)
+++ branches/bmesh/blender/source/blender/bmesh/bmesh.h 2009-03-14 02:52:16 UTC (rev 19279)
@@ -42,11 +42,35 @@
#include "BLI_mempool.h"
#include "BKE_customdata.h"
+/*
+short introduction:
+
+the bmesh structure is a boundary representation, supporting non-manifold
+locally modifiable topology. the API is designed to allow clean, maintainable
+code, that never (or almost never) directly inspects the underlying structure.
+
+The API includes iterators, including many useful topological iterators;
+walkers, which walk over a mesh, without the risk of hitting the recursion
+limit; operators, which are logical, reusable mesh modules; topological
+"euler" functions, which are used for topological manipulations; and some
+(not yet finished) geometric utility functions.
+
+some definitions:
+
+tool flags: private flags for tools. each operator has it's own private
+ tool flag "layer", which it can use to flag elements.
+ tool flags are also used by various other parts of the api.
+header flags: stores persistent flags, such as selection state, hide state,
+ etc. be careful of touching these.
+*/
+
/*forward declarations*/
struct BMVert;
struct BMEdge;
struct BMFace;
struct BMLoop;
+struct EditMesh;
+struct BMOperator;
/*
* BMHeader
@@ -82,7 +106,11 @@
typedef struct BMHeader {
struct BMHeader *next, *prev;
int EID; /*Consider removing this/making it ifdeffed for debugging*/
- int flag, type;
+
+ /*don't confuse this with tool flags. this flag
+ member is what "header flag" means.*/
+ int flag;
+ int type;
int eflag1, eflag2; /*Flags used by eulers. Try and get rid of/minimize some of these*/
struct BMFlagLayer *flags; /*Dynamically allocated block of flag layers for operators to use*/
} BMHeader;
@@ -181,48 +209,91 @@
struct BMVert *BM_Make_Vert(struct BMesh *bm, float co[3], struct BMVert *example);
struct BMEdge *BM_Make_Edge(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge *example, int nodouble);
struct BMFace *BM_Make_Quadtriangle(struct BMesh *bm, struct BMVert **verts, BMEdge **edges, int len, struct BMFace *example, int nodouble);
+
+/*makes an ngon from an unordered list of edges. v1 and v2 must be the verts
+defining edges[0], and define the winding of the new face.*/
struct BMFace *BM_Make_Ngon(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge **edges, int len, int nodouble);
+
+
/*copies loop data from adjacent faces*/
void BM_Face_CopyShared(BMesh *bm, BMFace *f);
+
+/*copies attributes, e.g. customdata, header flags, etc, from one element
+ to another of the same type.*/
void BM_Copy_Attributes(struct BMesh *source_mesh, struct BMesh *target_mesh, void *source, void *target);
+
+/*remove tool flagged elements*/
void BM_remove_tagged_faces(struct BMesh *bm, int flag);
void BM_remove_tagged_edges(struct BMesh *bm, int flag);
void BM_remove_tagged_verts(struct BMesh *bm, int flag);
/*Modification*/
+/*join two adjacent faces together along an edge. note that
+ the faces must only be joined by on edge. e is the edge you
+ wish to dissolve.*/
struct BMFace *BM_Join_Faces(struct BMesh *bm, struct BMFace *f1,
struct BMFace *f2, struct BMEdge *e);
+
+/*split a face along two vertices. returns the newly made face, and sets
+ the nl member to a loop in the newly created edge.*/
struct BMFace *BM_Split_Face(struct BMesh *bm, struct BMFace *f,
struct BMVert *v1, struct BMVert *v2,
struct BMLoop **nl, struct BMEdge *example);
+
+/*dissolves a vert shared only by two edges*/
void BM_Collapse_Vert(struct BMesh *bm, struct BMEdge *ke, struct BMVert *kv,
float fac);
+
+/*splits an edge. ne is set to the new edge created.*/
struct BMVert *BM_Split_Edge(struct BMesh *bm, struct BMVert *v,
struct BMEdge *e, struct BMEdge **ne,
float percent);
+
+/*split an edge multiple times evenly*/
struct BMVert *BM_Split_Edge_Multi(struct BMesh *bm, struct BMEdge *e,
int numcuts);
+
+/*connect two verts together, through a face they share. this function may
+ be removed in the future.*/
BMEdge *BM_Connect_Verts(BMesh *bm, BMVert *v1, BMVert *v2, BMFace **nf);
+
+
+/*updates a face normal*/
void BM_Face_UpdateNormal(BMesh *bm, BMFace *f);
+
+/*updates face and vertex normals incident on an edge*/
void BM_Edge_UpdateNormals(BMesh *bm, BMEdge *e);
+
+/*update a vert normal (but not the faces incident on it)*/
void BM_Vert_UpdateNormal(BMesh *bm, BMVert *v);
-/*dissolves vert surrounded by faces*/
+
+/*dissolves all faces around a vert, and removes it.*/
int BM_Dissolve_Disk(BMesh *bm, BMVert *v);
-/*dissolves vert, in more situations then BM_Dissolve_Disk.*/
+/*dissolves vert, in more situations then BM_Dissolve_Disk
+ (e.g. if the vert is part of a wire edge, etc).*/
int BM_Dissolve_Vert(BMesh *bm, BMVert *v);
+
/*Interpolation*/
void BM_Data_Interp_From_Verts(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, float fac);
void BM_Data_Facevert_Edgeinterp(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, struct BMEdge *e1, float fac);
//void bmesh_data_interp_from_face(struct BMesh *bm, struct BMFace *source, struct BMFace *target);
-struct EditMesh;
-struct BMOperator;
+
+/*convert an editmesh to a bmesh*/
BMesh *editmesh_to_bmesh(struct EditMesh *em);
+
+/*initializes editmesh to bmesh operator, but doesn't execute.
+ this is used in situations where you need to get access to the
+ conversion operator's editmesh->bmesh mapping slot (e.g. if you
+ need to find the bmesh edge that corrusponds to a specific editmesh
+ edge).*/
BMesh *init_editmesh_to_bmesh(struct EditMesh *em, struct BMOperator *op);
+
+/*converts a bmesh to an editmesh*/
struct EditMesh *bmesh_to_editmesh(BMesh *bm);
/*include the rest of the API*/
Modified: branches/bmesh/blender/source/blender/bmesh/bmesh_iterators.h
===================================================================
--- branches/bmesh/blender/source/blender/bmesh/bmesh_iterators.h 2009-03-13 23:35:15 UTC (rev 19278)
+++ branches/bmesh/blender/source/blender/bmesh/bmesh_iterators.h 2009-03-14 02:52:16 UTC (rev 19279)
@@ -13,21 +13,35 @@
#ifndef BM_ITERATORS_H
#define BM_ITERATORS_H
-/*Defines for passing to BMIter_New*/
+/*Defines for passing to BMIter_New.
+
+ "OF" can be substituted for "around"
+ so BM_VERTS_OF_FACE means "vertices
+ around a face."
+ */
+
+/*these iterator over all elements of a specific
+ type in the mesh.*/
#define BM_VERTS 1
#define BM_EDGES 2
#define BM_FACES 3
+
+/*these are topological iterators.*/
#define BM_EDGES_OF_VERT 4
#define BM_FACES_OF_VERT 5
-#define BM_VERTS_OF_EDGE 6
-#define BM_FACES_OF_EDGE 7
-#define BM_VERTS_OF_FACE 8
-#define BM_FACEVERTS_OF_FACE 9
-#define BM_EDGES_OF_FACE 10
-#define BM_LOOPS_OF_FACE 11
-#define BM_LOOPS_OF_VERT 12
-#define BM_LOOPS_OF_LOOP 13
+#define BM_FACES_OF_EDGE 6
+#define BM_VERTS_OF_FACE 7
+#define BM_FACEVERTS_OF_FACE 8
+#define BM_EDGES_OF_FACE 9
+#define BM_LOOPS_OF_FACE 10
+#define BM_LOOPS_OF_VERT 11
+/*iterate through loops around this loop, which are fetched
+ from the other faces in the radial cycle surrounding the
+ input loop's edge.*/
+#define BM_LOOPS_OF_LOOP 12
+
+
/*Iterator Structure*/
typedef struct BMIter{
struct BMVert *firstvert, *nextvert, *vdata;
Modified: branches/bmesh/blender/source/blender/bmesh/bmesh_operator_api.h
===================================================================
--- branches/bmesh/blender/source/blender/bmesh/bmesh_operator_api.h 2009-03-13 23:35:15 UTC (rev 19278)
+++ branches/bmesh/blender/source/blender/bmesh/bmesh_operator_api.h 2009-03-14 02:52:16 UTC (rev 19279)
@@ -7,11 +7,37 @@
#include <stdarg.h>
/*
-operators represent logical, executable mesh modules. all operations
-involving a bmesh has to go through them.
+operators represent logical, executable mesh modules. all topological
+operations involving a bmesh has to go through them.
-operators are nested, and certain data (e.g. tool flags) are also nested,
-and are private to an operator when it's executed.
+operators are nested, as are tool flags, which are private to an operator
+when it's executed. tool flags are allocated in layers, one per operator
+execution, and are used for all internal flagging a tool needs to do.
+
+each operator has a series of "slots," which can be of the following types:
+* simple numerical types
+* arrays of elements (e.g. arrays of faces).
+* hash mappings.
+
+each slot is identified by a slot code, as are each operator.
+operators, and their slots, are defined in bmesh_opdefines.c (with their
+execution functions prototyped in bmesh_operators_private.h), with all their
+operator code and slot codes defined in bmesh_operators.h. see
+bmesh_opdefines.c and the BMOpDefine struct for how to define new operators.
+
+in general, operators are fed arrays of elements, created using either
+BM_HeaderFlag_To_Slot or BM_Flag_To_Slot (or through one of the format
+specifyers in BMO_CallOpf or BMO_InitOpf). Note that multiple element
+types (e.g. faces and edges) can be fed to the same slot array. Operators
+act on this data, and possibly spit out data into output slots.
+
+some notes:
+* operators should never read from header flags (e.g. element->head.flag). for
+ example, if you want an operator to only operate on selected faces, you
+ should use BM_HeaderFlag_To_Slot to put the selected elements into a slot.
+* when you read from an element slot array or mapping, you can either tool-flag
+ all the elements in it, or read them using an iterator APi (which is
+ semantically similar to the iterator api in bmesh_iterators.h).
*/
struct GHashIterator;
@@ -22,6 +48,7 @@
#define BMOP_OPSLOT_VEC 6
/*after BMOP_OPSLOT_VEC, everything is
+
dynamically allocated arrays. we
leave a space in the identifiers
for future growth.*/
@@ -29,7 +56,9 @@
#define BMOP_OPSLOT_MAPPING 8
#define BMOP_OPSLOT_TYPES 9
-/*don't access the contents of this directly*/
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list