source/blender/bmesh/bmesh.h

   1 /*
   2  * This program is free software; you can redistribute it and/or
   3  * modify it under the terms of the GNU General Public License
   4  * as published by the Free Software Foundation; either version 2
   5  * of the License, or (at your option) any later version.
   6  *
   7  * This program is distributed in the hope that it will be useful,
   8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10  * GNU General Public License for more details.
  11  *
  12  * You should have received a copy of the GNU General Public License
  13  * along with this program; if not, write to the Free Software Foundation,
  14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  15  */
  16
  17 #ifndef __BMESH_H__
  18 #define __BMESH_H__
  19
  20 /** \file
  21  * \ingroup bmesh
  22  *
  23  * \addtogroup bmesh BMesh
  24  *
  25  * \brief BMesh is a non-manifold boundary representation designed to support advanced editing operations.
  26  * \section bm_structure The Structure
  27  *
  28  * BMesh stores topology in four main element structures:
  29  *
  30  * - Faces - BMFace
  31  * - Loops - BMLoop, (stores per-face-vertex data, UV's, vertex-colors, etc)
  32  * - Edges - BMEdge
  33  * - Verts - BMVert
  34  * \subsection bm_header_flags Header Flags
  35  * Each element (vertex/edge/face/loop) in a mesh has an associated bit-field called "header flags".
  36  *
  37  * BMHeader flags should **never** be read or written to by bmesh operators (see Operators below).
  38  *
  39  * Access to header flags is done with ``BM_elem_flag_*()`` functions.
  40  * \subsection bm_faces Faces
  41  *
  42  * Faces in BMesh are stored as a circular linked list of loops. Loops store per-face-vertex data
  43  * (amongst other things outlined later in this document), and define the face boundary.
  44  * \subsection bm_loop The Loop
  45  *
  46  * Loops can be thought of as a *face-corner*, since faces don't reference verts or edges directly.
  47  * Each loop connects the face to one of its corner vertices,
  48  * and also references an edge which connects this loop's vertex to the next loop's vertex.
  49  *
  50  * Loops allow faces to access their verts and edges,
  51  * while edges and faces store their loops, allowing access in the opposite direction too.
  52  *
  53  * Loop pointers:
  54  *
  55  * - BMLoop#v - pointer to the vertex associated with this loop.
  56  * - BMLoop#e - pointer to the edge associated with this loop,
  57  *   between verts ``(loop->v, loop->next->v)``
  58  * - BMLoop#f - pointer to the face associated with this loop.
  59  * \subsection bm_two_side_face 2-Sided Faces
  60  *
  61  * There are some situations where you need 2-sided faces (e.g. a face of two vertices).
  62  * This is supported by BMesh, but note that such faces should only be used as intermediary steps,
  63  * and should not end up in the final mesh.
  64  * \subsection bm_edges_and_verts Edges and Vertices
  65  *
  66  * Edges and Vertices in BMesh are primitive structures.
  67  *
  68  * \note There can be more than one edge between two vertices in BMesh,
  69  * though the rest of Blender (i.e. DNA and evaluated Mesh) does not support this.
  70  * So it should only occur temporarily during editing operations.
  71  * \subsection bm_queries Queries
  72  *
  73  * The following topological queries are available:
  74  *
  75  * - Edges/Faces/Loops around a vertex.
  76  * - Faces around an edge.
  77  * - Loops around an edge.
  78  *
  79  * These are accessible through the iterator api, which is covered later in this document
  80  *
  81  * See source/blender/bmesh/bmesh_query.h for more misc. queries.
  82  * \section bm_api The BMesh API
  83  *
  84  * One of the goals of the BMesh API is to make it easy and natural to produce highly maintainable code.
  85  * Code duplication, etc are avoided where possible.
  86  * \subsection bm_iter_api Iterator API
  87  *
  88  * Most topological queries in BMesh go through an iterator API (see Queries above).
  89  * These are defined in bmesh_iterators.h.
  90  * If you can, please use the #BM_ITER_MESH, #BM_ITER_ELEM macros in bmesh_iterators.h
  91  * \subsection bm_walker_api Walker API
  92  *
  93  * Topological queries that require a stack (e.g. recursive queries) go through the Walker API,
  94  * which is defined in bmesh_walkers.h. Currently the "walkers" are hard-coded into the API,
  95  * though a mechanism for plugging in new walkers needs to be added at some point.
  96  *
  97  * Most topological queries should go through these two APIs;
  98  * there are additional functions you can use for topological iteration, but their meant for internal bmesh code.
  99  *
 100  * Note that the walker API supports delimiter flags, to allow the caller to flag elements not to walk past.
 101  * \subsection bm_ops Operators
 102  *
 103  * Operators are an integral part of BMesh. Unlike regular blender operators,
 104  * BMesh operators **bmo's** are designed to be nested (e.g. call other operators).
 105  *
 106  * Each operator has a number of input/output "slots" which are used to pass settings & data into/out of the operator
 107  * (and allows for chaining operators together).
 108  *
 109  * These slots are identified by name, using strings.
 110  *
 111  * Access to slots is done with ``BMO_slot_***()`` functions.
 112  * \subsection bm_tool_flags Tool Flags
 113  *
 114  * The BMesh API provides a set of flags for faces, edges and vertices, which are private to an operator.
 115  * These flags may be used by the client operator code as needed
 116  * (a common example is flagging elements for use in another operator).
 117  * Each call to an operator allocates it's own set of tool flags when it's executed,
 118  * avoiding flag conflicts between operators.
 119  *
 120  * These flags should not be confused with header flags, which are used to store persistent flags
 121  * (e.g. selection, hide status, etc).
 122  *
 123  * Access to tool flags is done with ``BMO_elem_flag_***()`` functions.
 124  *
 125  * \warning Operators are **never** allowed to read or write to header flags.
 126  * They act entirely on the data inside their input slots.
 127  * For example an operator should not check the selected state of an element,
 128  * there are some exceptions to this - some operators check of a face is smooth.
 129  * \subsection bm_slot_types Slot Types
 130  *
 131  * The following slot types are available:
 132  *
 133  * - integer - #BMO_OP_SLOT_INT
 134  * - boolean - #BMO_OP_SLOT_BOOL
 135  * - float   - #BMO_OP_SLOT_FLT
 136  * - pointer - #BMO_OP_SLOT_PTR
 137  * - matrix  - #BMO_OP_SLOT_MAT
 138  * - vector  - #BMO_OP_SLOT_VEC
 139  * - buffer  - #BMO_OP_SLOT_ELEMENT_BUF - a list of verts/edges/faces.
 140  * - map     - BMO_OP_SLOT_MAPPING - simple hash map.
 141  * \subsection bm_slot_iter Slot Iterators
 142  *
 143  * Access to element buffers or maps must go through the slot iterator api, defined in bmesh_operators.h.
 144  * Use #BMO_ITER where ever possible.
 145  * \subsection bm_elem_buf Element Buffers
 146  *
 147  * The element buffer slot type is used to feed elements (verts/edges/faces) to operators.
 148  * Internally they are stored as pointer arrays (which happily has not caused any problems so far).
 149  * Many operators take in a buffer of elements, process it,
 150  * then spit out a new one; this allows operators to be chained together.
 151  *
 152  * \note Element buffers may have elements of different types within the same buffer (this is supported by the API.
 153  * \section bm_fname Function Naming Conventions
 154  *
 155  * These conventions should be used throughout the bmesh module.
 156  *
 157  * - ``bmesh_kernel_*()`` - Low level API, for primitive functions that others are built ontop of.
 158  * - ``bmesh_***()`` - Low level API function.
 159  * - ``bm_***()`` -     'static' functions, not apart of the API at all, but use prefix since they operate on BMesh data.
 160  * - ``BM_***()`` -     High level BMesh API function for use anywhere.
 161  * - ``BMO_***()`` -    High level operator API function for use anywhere.
 162  * - ``bmo_***()`` -    Low level / internal operator API functions.
 163  * - ``_bm_***()`` -    Functions which are called via macros only.
 164  *
 165  * \section bm_todo BMesh TODO's
 166  *
 167  * There may be a better place for this section, but adding here for now.
 168  *
 169  * \subsection bm_todo_optimize Optimizations
 170  *
 171  * - skip normal calc when its not needed (when calling chain of operators & for modifiers, flag as dirty)
 172  * - skip BMO flag allocation, its not needed in many cases, this is fairly redundant to calc by default.
 173  * - ability to call BMO's with option not to create return data (will save some time)
 174  * - binary diff UNDO, currently this uses huge amount of ram when all shapes are stored for each undo step for eg.
 175  * - use two different iterator types for BMO map/buffer types.
 176  */
 177
 178 #ifdef __cplusplus
 179 extern "C" {
 180 #endif
 181
 182 #include "DNA_listBase.h" /* selection history uses */
 183 #include "DNA_customdata_types.h" /* BMesh struct in bmesh_class.h uses */
 184
 185 #include <stdlib.h>
 186 #include <stdio.h>
 187 #include <assert.h>
 188
 189 #include "bmesh_class.h"
 190
 191 /* include the rest of the API */
 192 #include "intern/bmesh_operator_api.h"
 193 #include "intern/bmesh_error.h"
 194
 195 #include "intern/bmesh_core.h"
 196 #include "intern/bmesh_callback_generic.h"
 197 #include "intern/bmesh_construct.h"
 198 #include "intern/bmesh_delete.h"
 199 #include "intern/bmesh_edgeloop.h"
 200 #include "intern/bmesh_interp.h"
 201 #include "intern/bmesh_iterators.h"
 202 #include "intern/bmesh_log.h"
 203 #include "intern/bmesh_marking.h"
 204 #include "intern/bmesh_mesh.h"
 205 #include "intern/bmesh_mesh_conv.h"
 206 #include "intern/bmesh_mesh_validate.h"
 207 #include "intern/bmesh_mods.h"
 208 #include "intern/bmesh_operators.h"
 209 #include "intern/bmesh_polygon.h"
 210 #include "intern/bmesh_polygon_edgenet.h"
 211 #include "intern/bmesh_query.h"
 212 #include "intern/bmesh_walkers.h"
 213
 214 #include "intern/bmesh_inline.h"
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif /* __BMESH_H__ */