Blender  V3.3
Files
BMesh

BMesh is a non-manifold boundary representation designed to support advanced editing operations. More...

Files

file  bmesh.h
 
file  bmesh_class.h
 
file  bmesh_tools.h
 
file  bmesh_callback_generic.c
 
file  bmesh_callback_generic.h
 
file  bmesh_construct.c
 
file  bmesh_construct.h
 
file  bmesh_core.c
 
file  bmesh_core.h
 
file  bmesh_delete.c
 
file  bmesh_delete.h
 
file  bmesh_edgeloop.c
 
file  bmesh_edgeloop.h
 
file  bmesh_error.h
 
file  bmesh_inline.h
 
file  bmesh_interp.c
 
file  bmesh_interp.h
 
file  bmesh_iterators.c
 
file  bmesh_iterators.h
 
file  bmesh_iterators_inline.h
 
file  bmesh_log.c
 
file  bmesh_log.h
 
file  bmesh_marking.c
 
file  bmesh_marking.h
 
file  bmesh_mesh.cc
 
file  bmesh_mesh.h
 
file  bmesh_mesh_convert.cc
 
file  bmesh_mesh_convert.h
 
file  bmesh_mesh_debug.h
 
file  bmesh_mesh_duplicate.c
 
file  bmesh_mesh_duplicate.h
 
file  bmesh_mesh_normals.c
 
file  bmesh_mesh_normals.h
 
file  bmesh_mesh_partial_update.c
 
file  bmesh_mesh_partial_update.h
 
file  bmesh_mesh_tessellate.c
 
file  bmesh_mesh_tessellate.h
 
file  bmesh_mesh_validate.c
 
file  bmesh_mesh_validate.h
 
file  bmesh_mods.c
 
file  bmesh_mods.h
 
file  bmesh_opdefines.c
 
file  bmesh_operator_api.h
 
file  bmesh_operator_api_inline.h
 
file  bmesh_operators.c
 
file  bmesh_operators.h
 
file  bmesh_operators_private.h
 
file  bmesh_polygon.c
 
file  bmesh_polygon.h
 
file  bmesh_polygon_edgenet.c
 
file  bmesh_polygon_edgenet.h
 
file  bmesh_private.h
 
file  bmesh_query.c
 
file  bmesh_query.h
 
file  bmesh_query_inline.h
 
file  bmesh_query_uv.c
 
file  bmesh_query_uv.h
 
file  bmesh_structure.c
 
file  bmesh_structure.h
 
file  bmesh_structure_inline.h
 
file  bmesh_walkers.c
 
file  bmesh_walkers.h
 
file  bmesh_walkers_impl.c
 
file  bmesh_walkers_private.h
 
file  bmo_beautify.c
 
file  bmo_bevel.c
 
file  bmo_bisect_plane.c
 
file  bmo_bridge.c
 
file  bmo_connect.c
 
file  bmo_connect_concave.c
 
file  bmo_connect_nonplanar.c
 
file  bmo_connect_pair.c
 
file  bmo_create.c
 
file  bmo_dissolve.c
 
file  bmo_dupe.c
 
file  bmo_edgenet.c
 
file  bmo_extrude.c
 
file  bmo_fill_attribute.c
 
file  bmo_fill_edgeloop.c
 
file  bmo_fill_grid.c
 
file  bmo_fill_holes.c
 
file  bmo_hull.c
 
file  bmo_inset.c
 
file  bmo_join_triangles.c
 
file  bmo_mesh_convert.c
 
file  bmo_mirror.c
 
file  bmo_normals.c
 
file  bmo_offset_edgeloops.c
 
file  bmo_planar_faces.c
 
file  bmo_poke.c
 
file  bmo_primitive.c
 
file  bmo_removedoubles.c
 
file  bmo_rotate_edges.c
 
file  bmo_smooth_laplacian.c
 
file  bmo_split_edges.c
 
file  bmo_subdivide.c
 
file  bmo_subdivide_edgering.c
 
file  bmo_symmetrize.c
 
file  bmo_triangulate.c
 
file  bmo_unsubdivide.c
 
file  bmo_utils.c
 
file  bmo_wireframe.c
 
file  bmesh_beautify.c
 
file  bmesh_beautify.h
 
file  bmesh_bevel.c
 
file  bmesh_bevel.h
 
file  bmesh_bisect_plane.c
 
file  bmesh_bisect_plane.h
 
file  bmesh_boolean.cc
 
file  bmesh_boolean.h
 
file  bmesh_decimate.h
 
file  bmesh_decimate_collapse.c
 
file  bmesh_decimate_dissolve.c
 
file  bmesh_decimate_unsubdivide.c
 
file  bmesh_edgenet.c
 
file  bmesh_edgenet.h
 
file  bmesh_edgesplit.c
 
file  bmesh_edgesplit.h
 
file  bmesh_intersect.c
 
file  bmesh_intersect.h
 
file  bmesh_intersect_edges.c
 
file  bmesh_intersect_edges.h
 
file  bmesh_path.c
 
file  bmesh_path.h
 
file  bmesh_path_region.c
 
file  bmesh_path_region.h
 
file  bmesh_path_region_uv.c
 
file  bmesh_path_region_uv.h
 
file  bmesh_path_uv.c
 
file  bmesh_path_uv.h
 
file  bmesh_region_match.c
 
file  bmesh_region_match.h
 
file  bmesh_separate.c
 
file  bmesh_separate.h
 
file  bmesh_triangulate.c
 
file  bmesh_triangulate.h
 
file  bmesh_wireframe.c
 
file  bmesh_wireframe.h
 

Detailed Description

BMesh is a non-manifold boundary representation designed to support advanced editing operations.

The Structure

BMesh stores topology in four main element structures:

Header Flags

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

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.

The Loop

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:

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.

Edges and Vertices

Edges and Vertices in BMesh are primitive structures.

Note
There can be more than one edge between two vertices in BMesh, though the rest of Blender (i.e. DNA and evaluated Mesh) does not support this. So it should only occur temporarily during editing operations.

Queries

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.

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_MESH, BM_ITER_ELEM macros 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.

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

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.

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 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.

Warning
Operators are never allowed to read or write to header flags. They act entirely on the data inside their input slots. For example an operator should not check the selected state of an element, there are some exceptions to this - some operators check of a face is smooth.

Slot Types

The following slot types are available:

Slot Iterators

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

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.

Note
Element buffers may have elements of different types within the same buffer (this is supported by the API.

Function Naming Conventions

These conventions should be used throughout the bmesh module.

BMesh TODO's

There may be a better place for this section, but adding here for now.

Optimizations