Blender
V3.3
|
BMesh is a non-manifold boundary representation designed to support advanced editing operations. More...
BMesh is a non-manifold boundary representation designed to support advanced editing operations.
BMesh stores topology in four main element structures:
Each element (vertex/edge/face/loop) in a mesh has an associated bit-field called "header flags".
BMHeader 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 in BMesh are stored as a circular linked list of loops. Loops store per-face-vertex data (among other things outlined later in this document), and define the face boundary.
Loops can be thought of as a face-corner, since faces don't reference verts or edges directly. Each loop connects the face to one of its corner vertices, and also references an edge which connects this loop's vertex to the next loop's vertex.
Loops allow faces to access their verts and edges, while edges and faces store their loops, allowing access in the opposite direction too.
Loop pointers:
(loop->v, loop->next->v)
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 in BMesh are primitive structures.
The following topological queries are available:
These are accessible through the iterator api, which is covered later in this document
See source/blender/bmesh/bmesh_query.h for more misc. queries.
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.
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_MESH, BM_ITER_ELEM macros in bmesh_iterators.h
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 are an integral part of BMesh. Unlike regular blender operators, BMesh operators bmo's are designed to be nested (e.g. call other operators).
Each operator has a number of input/output "slots" which are used to pass settings & data into/out of the operator (and allows for chaining operators together).
These slots are identified by name, using strings.
Access to slots is done with BMO_slot_***()
functions.
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 its 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).
Access to tool flags is done with BMO_elem_flag_***()
functions.
The following slot types are available:
Access to element buffers or maps must go through the slot iterator api, defined in bmesh_operators.h. Use BMO_ITER where ever possible.
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.
These conventions should be used throughout the bmesh module.
bmesh_kernel_*()
- Low level API, for primitive functions that others are built ontop of.bmesh_***()
- Low level API function.bm_***()
- 'static' functions, not a part of the API at all, but use prefix since they operate on BMesh data.BM_***()
- High level BMesh API function for use anywhere.BMO_***()
- High level operator API function for use anywhere.bmo_***()
- Low level / internal operator API functions._bm_***()
- Functions which are called via macros only.There may be a better place for this section, but adding here for now.