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