bmesh api cleanup
[blender-staging.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
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 #include "DNA_listBase.h"
35 #include "DNA_customdata_types.h"
36
37 #include "BLI_utildefines.h"
38
39 #include "bmesh_class.h"
40
41 /*
42  * short introduction:
43  *
44  * the bmesh structure is a boundary representation, supporting non-manifold
45  * locally modifiable topology. the API is designed to allow clean, maintainable
46  * code, that never (or almost never) directly inspects the underlying structure.
47  *
48  * The API includes iterators, including many useful topological iterators;
49  * walkers, which walk over a mesh, without the risk of hitting the recursion
50  * limit; operators, which are logical, reusable mesh modules; topological
51  * modification functions (like split face, join faces, etc), which are used for
52  * topological manipulations; and some (not yet finished) geometric utility
53  * functions.
54  *
55  * some definitions:
56  *
57  * tool flags: private flags for tools.  each operator has it's own private
58  *             tool flag "layer", which it can use to flag elements.
59  *             tool flags are also used by various other parts of the api.
60  * header flags: stores persistent flags, such as selection state, hide state,
61  *               etc.  be careful of touching these.
62  */
63
64 /*forward declarations*/
65 struct BMesh;
66 struct BMVert;
67 struct BMEdge;
68 struct BMFace;
69 struct BMLoop;
70 struct BMOperator;
71 struct Mesh;
72 struct EditMesh;
73
74 /*
75  * BMHeader
76  *
77  * All mesh elements begin with a BMHeader. This structure
78  * hold several types of data
79  *
80  * 1: The type of the element (vert, edge, loop or face)
81  * 2: Persistant "header" flags/markings (sharp, seam, select, hidden, ect)
82       note that this is different from the "tool" flags.
83  * 3: Unique ID in the bmesh.
84  * 4: some elements for internal record keeping.
85  *
86 */
87
88 /* BMHeader->htype (char) */
89 #define BM_VERT         1
90 #define BM_EDGE         2
91 #define BM_LOOP         4
92 #define BM_FACE         8
93 #define BM_ALL          (BM_VERT | BM_EDGE | BM_LOOP | BM_FACE)
94
95 /* BMHeader->hflag (char) */
96 #define BM_ELEM_SELECT  (1 << 0)
97 #define BM_ELEM_HIDDEN  (1 << 1)
98 #define BM_ELEM_SEAM    (1 << 2)
99 #define BM_ELEM_SMOOTH  (1 << 3) /* used for faces and edges, note from the user POV,
100                                   * this is a sharp edge when disabled */
101
102 #define BM_ELEM_TAG     (1 << 4) /* internal flag, used for ensuring correct normals
103                                   * during multires interpolation, and any other time
104                                   * when temp tagging is handy.
105                                   * always assume dirty & clear before use. */
106
107 /* we have 3 spare flags which is awesome but since we're limited to 8
108  * only add new flags with care! - campbell */
109 /* #define BM_ELEM_SPARE         (1<<5) */
110 /* #define BM_ELEM_SPARE         (1<<6) */
111 /* #define BM_ELEM_NONORMCALC (1<<7) */ /* UNUSED */
112
113 /* stub */
114 void bmesh_error(void);
115
116 /* Mesh Level Ops */
117 extern int bm_mesh_allocsize_default[4];
118
119 /* ob is needed by multires */
120 BMesh *BM_mesh_create(struct Object *ob, const int allocsize[4]);
121 BMesh *BM_mesh_copy(BMesh *bmold);
122 void   BM_mesh_free(BMesh *bm);
123
124 /* frees mesh, but not actual BMesh struct */
125 void BM_mesh_data_free(BMesh *bm);
126 void BM_mesh_normals_update(BMesh *bm, const short skip_hidden);
127
128 /* Construction */
129 BMVert *BM_vert_create(BMesh *bm, const float co[3], const BMVert *example);
130 BMEdge *BM_edge_create(BMesh *bm, BMVert *v1, BMVert *v2, const BMEdge *example, int nodouble);
131 BMFace *BM_face_create(BMesh *bm, BMVert **verts, BMEdge **edges, const int len, int nodouble);
132
133 BMFace *BM_face_create_quad_tri_v(BMesh *bm,
134                                   BMVert **verts, int len,
135                                   const BMFace *example, const int nodouble);
136
137 /* easier to use version of BM_face_create_quad_tri_v.
138  * creates edges if necassary. */
139 BMFace *BM_face_create_quad_tri(BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v3, BMVert *v4,
140                                 const BMFace *example, const int nodouble);
141
142 /* makes an ngon from an unordered list of edges.  v1 and v2 must be the verts
143  * defining edges[0], and define the winding of the new face. */
144 BMFace *BM_face_create_ngon(BMesh *bm, BMVert *v1, BMVert *v2, BMEdge **edges, int len, int nodouble);
145
146 /* stuff for dealing with header flags */
147 #define BM_elem_flag_test(ele, hflag)      _bm_elem_flag_test    (&(ele)->head, hflag)
148 #define BM_elem_flag_enable(ele, hflag)    _bm_elem_flag_enable  (&(ele)->head, hflag)
149 #define BM_elem_flag_disable(ele, hflag)   _bm_elem_flag_disable (&(ele)->head, hflag)
150 #define BM_elem_flag_set(ele, hflag, val)  _bm_elem_flag_set     (&(ele)->head, hflag, val)
151 #define BM_elem_flag_toggle(ele, hflag)    _bm_elem_flag_toggle  (&(ele)->head, hflag)
152 #define BM_elem_flag_merge(ele_a, ele_b)   _bm_elem_flag_merge   (&(ele_a)->head, &(ele_b)->head)
153
154 BM_INLINE char _bm_elem_flag_test(const BMHeader *element, const char hflag);
155 BM_INLINE void _bm_elem_flag_enable(BMHeader *element, const char hflag);
156 BM_INLINE void _bm_elem_flag_disable(BMHeader *element, const char hflag);
157 BM_INLINE void _bm_elem_flag_set(BMHeader *ele, const char hflag, const int val);
158 BM_INLINE void _bm_elem_flag_toggle(BMHeader *ele, const char hflag);
159 BM_INLINE void _bm_elem_flag_merge(BMHeader *ele_a, BMHeader *ele_b);
160
161 /* notes on BM_elem_index_set(...) usage,
162  * Set index is sometimes abused as temp storage, other times we cant be
163  * sure if the index values are valid because certain operations have modified
164  * the mesh structure.
165  *
166  * To set the elements to valid indicies 'BM_mesh_elem_index_ensure' should be used
167  * rather then adding inline loops, however there are cases where we still
168  * set the index directly
169  *
170  * In an attempt to manage this, here are 3 tags Im adding to uses of
171  * 'BM_elem_index_set'
172  *
173  * - 'set_inline'  -- since the data is already being looped over set to a
174  *                    valid value inline.
175  *
176  * - 'set_dirty!'  -- intentionally sets the index to an invalid value,
177  *                    flagging 'bm->elem_index_dirty' so we dont use it.
178  *
179  * - 'set_ok'      -- this is valid use since the part of the code is low level.
180  *
181  * - 'set_ok_invalid'  -- set to -1 on purpose since this should not be
182  *                    used without a full array re-index, do this on
183  *                    adding new vert/edge/faces since they may be added at
184  *                    the end of the array.
185  *
186  * - 'set_loop'    -- currently loop index values are not used used much so
187  *                    assume each case they are dirty.
188  * - campbell */
189
190 #define BM_elem_index_get(ele)           _bm_elem_index_get(&(ele)->head)
191 #define BM_elem_index_set(ele, index)    _bm_elem_index_set(&(ele)->head, index)
192 BM_INLINE int  _bm_elem_index_get(const BMHeader *ele);
193 BM_INLINE void _bm_elem_index_set(BMHeader *ele, const int index);
194
195 /* todo */
196 BMFace *BM_face_copy(BMesh *bm, BMFace *f, const short copyverts, const short copyedges);
197
198 /* copies loop data from adjacent faces */
199 void BM_face_copy_shared(BMesh *bm, BMFace *f);
200
201 /* copies attributes, e.g. customdata, header flags, etc, from one element
202  * to another of the same type.*/
203 void BM_elem_attrs_copy(BMesh *source_mesh, BMesh *target_mesh, const void *source, void *target);
204
205 /* Modification */
206 /* join two adjacent faces together along an edge.  note that
207  * the faces must only be joined by on edge.  e is the edge you
208  * wish to dissolve.*/
209 BMFace *BM_faces_join_pair(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e);
210
211 /* generic, flexible join faces function; note that most everything uses
212  * this, including BM_faces_join_pair */
213 BMFace *BM_faces_join(BMesh *bm, BMFace **faces, int totface);
214
215 /* split a face along two vertices.  returns the newly made face, and sets
216  * the nl member to a loop in the newly created edge.*/
217 BMFace *BM_face_split(BMesh *bm, BMFace *f,
218                       BMVert *v1, BMVert *v2,
219                       struct BMLoop **nl, BMEdge *example);
220
221 /* these 2 functions are very similar */
222 BMEdge* BM_vert_collapse_faces(BMesh *bm, BMEdge *ke, BMVert *kv, float fac, const int join_faces);
223 BMEdge* BM_vert_collapse_edge(BMesh *bm, BMEdge *ke, BMVert *kv);
224
225
226 /* splits an edge.  ne is set to the new edge created. */
227 BMVert *BM_edge_split(BMesh *bm, BMEdge *e, BMVert *v, BMEdge **ne, float percent);
228
229 /* split an edge multiple times evenly */
230 BMVert  *BM_edge_split_n(BMesh *bm, BMEdge *e, int numcuts);
231
232 /* connect two verts together, through a face they share.  this function may
233  * be removed in the future. */
234 BMEdge *BM_verts_connect(BMesh *bm, BMVert *v1, BMVert *v2, BMFace **nf);
235
236 /* rotates an edge topologically, either clockwise (if ccw=0) or counterclockwise
237  * (if ccw is 1). */
238 BMEdge *BM_edge_rotate(BMesh *bm, BMEdge *e, int ccw);
239
240 /* Rip a single face from a vertex fan */
241 BMVert *BM_vert_rip(BMesh *bm, BMFace *sf, BMVert *sv);
242
243 /*updates a face normal*/
244 void BM_face_normal_update(BMesh *bm, BMFace *f);
245 void BM_face_normal_update_vcos(BMesh *bm, BMFace *f, float no[3], float (*vertexCos)[3]);
246
247 /*updates face and vertex normals incident on an edge*/
248 void BM_edge_normals_update(BMesh *bm, BMEdge *e);
249
250 /*update a vert normal (but not the faces incident on it)*/
251 void BM_vert_normal_update(BMesh *bm, BMVert *v);
252 void BM_vert_normal_update_all(BMesh *bm, BMVert *v);
253
254 void BM_face_normal_flip(BMesh *bm, BMFace *f);
255
256 /*dissolves all faces around a vert, and removes it.*/
257 int BM_disk_dissolve(BMesh *bm, BMVert *v);
258
259 /* dissolves vert, in more situations then BM_disk_dissolve
260  * (e.g. if the vert is part of a wire edge, etc).*/
261 int BM_vert_dissolve(BMesh *bm, BMVert *v);
262
263 /* Projects co onto face f, and returns true if it is inside
264  * the face bounds.  Note that this uses a best-axis projection
265  * test, instead of projecting co directly into f's orientation
266  * space, so there might be accuracy issues.*/
267 int BM_face_point_inside_test(BMesh *bm, BMFace *f, const float co[3]);
268
269 /* Interpolation */
270
271 /* projects target onto source for customdata interpolation.  note: only
272  * does loop customdata.  multires is handled.  */
273 void BM_face_interp_from_face(BMesh *bm, BMFace *target, BMFace *source);
274
275 /* projects a single loop, target, onto source for customdata interpolation. multires is handled.
276  * if do_vertex is true, target's vert data will also get interpolated.*/
277 void BM_loop_interp_from_face(BMesh *bm, BMLoop *target, BMFace *source,
278                               int do_vertex, int do_multires);
279
280 /* smoothes boundaries between multires grids, including some borders in adjacent faces */
281 void BM_face_multires_bounds_smooth(BMesh *bm, BMFace *f);
282
283 /* project the multires grid in target onto source's set of multires grids */
284 void BM_loop_interp_multires(BMesh *bm, BMLoop *target, BMFace *source);
285 void BM_vert_interp_from_face(BMesh *bm, BMVert *v, BMFace *source);
286
287 void  BM_data_interp_from_verts(BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v, const float fac);
288 void  BM_data_interp_face_vert_edge(BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v, struct BMEdge *e1, const float fac);
289 void  BM_data_layer_add(BMesh *em, CustomData *data, int type);
290 void  BM_data_layer_add_named(BMesh *bm, CustomData *data, int type, const char *name);
291 void  BM_data_layer_free(BMesh *em, CustomData *data, int type);
292 void  BM_data_layer_free_n(BMesh *bm, CustomData *data, int type, int n);
293 float BM_elem_float_data_get(struct CustomData *cd, void *element, int type);
294 void  BM_elem_float_data_set(struct CustomData *cd, void *element, int type, const float val);
295
296 /* get the area of the face */
297 float BM_face_area_calc(BMesh *bm, BMFace *f);
298 /* computes the centroid of a face, using the center of the bounding box */
299 void BM_face_center_bounds_calc(BMesh *bm, BMFace *f, float center[3]);
300 /* computes the centroid of a face, using the mean average */
301 void BM_face_center_mean_calc(BMesh *bm, BMFace *f, float center[3]);
302
303 void BM_mesh_select_mode_flush(BMesh *bm);
304
305 /* mode independent flushing up/down */
306 void BM_mesh_deselect_flush(BMesh *bm);
307 void BM_mesh_select_flush(BMesh *bm);
308
309 /* flag conversion funcs */
310 char BM_face_flag_from_mflag(const char  mflag);
311 char BM_edge_flag_from_mflag(const short mflag);
312 char BM_vert_flag_from_mflag(const char  mflag);
313 /* reverse */
314 char  BM_face_flag_to_mflag(BMFace *f);
315 short BM_edge_flag_to_mflag(BMEdge *e);
316 char  BM_vert_flag_to_mflag(BMVert *v);
317
318
319 /* convert MLoop*** in a bmface to mtface and mcol in
320  * an MFace*/
321 void BM_loops_to_corners(BMesh *bm, struct Mesh *me, int findex,
322                          BMFace *f, int numTex, int numCol);
323
324 void BM_loop_kill(BMesh *bm, BMLoop *l);
325 void BM_face_kill(BMesh *bm, BMFace *f);
326 void BM_edge_kill(BMesh *bm, BMEdge *e);
327 void BM_vert_kill(BMesh *bm, BMVert *v);
328
329 /* kills all edges associated with f, along with any other faces containing
330  * those edges*/
331 void BM_face_edges_kill(BMesh *bm, BMFace *f);
332
333 /* kills all verts associated with f, along with any other faces containing
334  * those vertices*/
335 void BM_face_verts_kill(BMesh *bm, BMFace *f);
336
337 /*clear all data in bm*/
338 void BM_mesh_clear(BMesh *bm);
339
340 void BM_mesh_elem_index_ensure(BMesh *bm, const char hflag);
341
342 void BM_mesh_elem_index_validate(BMesh *bm, const char *location, const char *func,
343                                  const char *msg_a, const char *msg_b);
344
345 BMVert *BM_vert_at_index(BMesh *bm, const int index);
346 BMEdge *BM_edge_at_index(BMesh *bm, const int index);
347 BMFace *BM_face_at_index(BMesh *bm, const int index);
348
349 /*start/stop edit*/
350 void bmesh_begin_edit(BMesh *bm, int flag);
351 void bmesh_end_edit(BMesh *bm, int flag);
352
353
354 #ifdef USE_BMESH_HOLES
355 #  define BM_FACE_FIRST_LOOP(p) (((BMLoopList *)((p)->loops.first))->first)
356 #else
357 #  define BM_FACE_FIRST_LOOP(p) ((p)->l_first)
358 #endif
359
360 /* size to use for static arrays when dealing with NGons,
361  * alloc after this limit is reached.
362  * this value is rather arbitrary */
363 #define BM_NGON_STACK_SIZE 32
364
365 /* avoid inf loop, this value is arbtrary
366  * but should not error on valid cases */
367 #define BM_LOOP_RADIAL_MAX 10000
368 #define BM_NGON_MAX 100000
369
370 /* include the rest of the API */
371 #include "bmesh_marking.h"
372 #include "bmesh_operator_api.h"
373 #include "bmesh_operators.h"
374 #include "bmesh_error.h"
375 #include "bmesh_queries.h"
376 #include "bmesh_iterators.h"
377 #include "bmesh_walkers.h"
378 #include "intern/bmesh_inline.c"
379 #include "intern/bmesh_operator_api_inline.c"
380
381 #ifdef __cplusplus
382 }
383 #endif
384
385 #endif /* __BMESH_H__ */