From BlenderWiki

[edit] 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.

[edit] The Structure

BMesh stores topology in four main element structures:

• Faces
• Loops (stores per-face-vertex data, uvs, vcols, etc)
• Edges
• Verts

[edit] 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).

[edit] 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.

[edit] The Loop

Loops define the boundary loop of a face. Each loop logically corrusponds to an edge, which is defined by the loop and succeeding loop's vertices.

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.

[edit] 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.

[edit] 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.

[edit] Queries

The following topological queries are available:

• 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

See source/blender/bmesh/bmesh_queries.h for more misc. queries.

[edit] 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.

[edit] 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.

[edit] 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.

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.

[edit] Operators

Operators are an integrat part of BMesh. Unlike normal blender operators, BMesh operators ("bmops") can be nested (e.g. call other operators). Each operator has a number of input/output "slots" which are used to pass data into/out of the operator (and allows for chaining operators together). These slots are identified by name, using strings.

[edit] Tool Flags

The BMesh API provides a set of flags for faces, edges and vertices, which are private to an operator. These flags may be used by the client operator code as needed (a common example is flagging elements for use in another operator). Each call to an operator allocates it's own set of tool flags when it's executed, avoiding flag conflicts between operators.

These flags should not be confused with header flags, which are used to store persistent flags (e.g. selection, hide status, etc).

[edit] Persistent Flags

Operators are never allowed to read or write to persistent flags. They act entirely on the data inside their input slots.

[edit] Slot Types

The following slot types are available:

• Integer
• Float
• Pointer - do not store arrays corrusponding to elements with this
• Element Buffer - a list of verts/edges/faces
• Map - simple hash map

[edit] Slot Iterators

Access to element buffers or maps must go through the slot iterator api, defined in bmesh_operators.h. Use BMO_ITER whereever possible.

[edit] Element Buffers

The element buffer slot type is used to feed elements (verts/edges/faces) to operators. Internally they are stored as pointer arrays (which happily has not caused any problems so far). Many operators take in a buffer of elements, process it, then spit out a new one; this allows operators to be chained together.

\