Style Cleanup: whitespace and some formatting.
[blender.git] / source / blender / bmesh / bmesh.h
1 /*
2  *      BMesh API.
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19  *
20  * Contributor(s): Geoffrey Bantle, Levi Schooley.
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24
25 #ifndef BMESH_H
26 #define BMESH_H
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 #include "DNA_listBase.h"
33 #include "DNA_scene_types.h"
34 #include "DNA_customdata_types.h"
35
36 #include "BKE_customdata.h"
37
38 #include "BLI_utildefines.h"
39
40 /*
41  * short introduction:
42  *
43  * the bmesh structure is a boundary representation, supporting non-manifold
44  * locally modifiable topology. the API is designed to allow clean, maintainable
45  * code, that never (or almost never) directly inspects the underlying structure.
46  *
47  * The API includes iterators, including many useful topological iterators;
48  * walkers, which walk over a mesh, without the risk of hitting the recursion
49  * limit; operators, which are logical, reusable mesh modules; topological
50  * modification functions (like split face, join faces, etc), which are used for
51  * topological manipulations; and some (not yet finished) geometric utility
52  * functions.
53  *
54  * some definitions:
55  *
56  * tool flags: private flags for tools.  each operator has it's own private
57  *             tool flag "layer", which it can use to flag elements.
58  *             tool flags are also used by various other parts of the api.
59  * header flags: stores persistent flags, such as selection state, hide state,
60  *               etc.  be careful of touching these.
61  */
62
63 /*forward declarations*/
64 struct BMesh;
65 struct BMVert;
66 struct BMEdge;
67 struct BMFace;
68 struct BMLoop;
69 struct BMOperator;
70 struct Mesh;
71 struct EditMesh;
72
73 /*
74  * BMHeader
75  *
76  * All mesh elements begin with a BMHeader. This structure
77  * hold several types of data
78  *
79  * 1: The type of the element (vert, edge, loop or face)
80  * 2: Persistant "header" flags/markings (sharp, seam, select, hidden, ect)
81       note that this is different from the "tool" flags.
82  * 3: Unique ID in the bmesh.
83  * 4: some elements for internal record keeping.
84  *
85 */
86
87 /*BMHeader->htype (char) */
88 #define BM_VERT         1
89 #define BM_EDGE         2
90 #define BM_LOOP         4
91 #define BM_FACE         8
92 #define BM_ALL          (BM_VERT | BM_EDGE | BM_LOOP | BM_FACE)
93
94 /*BMHeader->hflag (char, all bits used!) */
95 #define BM_SELECT       (1<<0)
96
97 #define BM_SEAM         (1<<1)
98 #define BM_FGON         (1<<2)
99 #define BM_HIDDEN       (1<<3)
100 #define BM_SHARP        (1<<4)
101 #define BM_SMOOTH       (1<<5)
102 #define BM_ACTIVE       (1<<6)
103 #define BM_TMP_TAG      (1<<7) /* internal flag, used for ensuring correct normals
104                             * during multires interpolation, and any other time
105                             * when temp tagging is handy.
106                             * always assume dirty & clear before use. */
107
108 /* #define BM_NONORMCALC (1<<8) */ /* UNUSED */
109
110 #include "bmesh_class.h"
111
112 /* stub */
113 void bmesh_error(void);
114
115 /* Mesh Level Ops */
116
117 /* ob is needed by multires */
118 BMesh *BM_Make_Mesh(struct Object *ob, int allocsize[4]);
119 BMesh *BM_Copy_Mesh(BMesh *bmold);
120 void BM_Free_Mesh(BMesh *bm);
121
122 /* frees mesh, but not actual BMesh struct */
123 void BM_Free_Mesh_Data(BMesh *bm);
124 void BM_Compute_Normals(BMesh *bm);
125
126 /* Construction */
127 BMVert *BM_Make_Vert(BMesh *bm, const float co[3], const BMVert *example);
128 BMEdge *BM_Make_Edge(BMesh *bm, BMVert *v1, BMVert *v2, const BMEdge *example, int nodouble);
129 BMFace *BM_Make_Face(BMesh *bm, BMVert **verts, BMEdge **edges, const int len, int nodouble);
130
131 BMFace *BM_Make_Face_QuadTri_v(BMesh *bm,
132                                BMVert **verts, int len,
133                                const BMFace *example, const int nodouble);
134
135 /* easier to use version of BM_Make_Face_QuadTri_v.
136  * creates edges if necassary. */
137 BMFace *BM_Make_Face_QuadTri(BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v3, BMVert *v4,
138                              const BMFace *example, const int nodouble);
139
140 /* makes an ngon from an unordered list of edges.  v1 and v2 must be the verts
141  * defining edges[0], and define the winding of the new face. */
142 BMFace *BM_Make_Ngon(BMesh *bm, BMVert *v1, BMVert *v2, BMEdge **edges, int len, int nodouble);
143
144 /* stuff for dealing with header flags */
145 BM_INLINE char BM_TestHFlag(const void *element, const char hflag);
146
147 /* stuff for dealing with header flags */
148 BM_INLINE void BM_SetHFlag(void *element, const char hflag);
149
150 /* stuff for dealing with header flags */
151 BM_INLINE void BM_ClearHFlag(void *element, const char hflag);
152
153 /* stuff for dealing BM_ToggleHFlag header flags */
154 BM_INLINE void BM_ToggleHFlag(void *element, const char hflag);
155 BM_INLINE void BM_MergeHFlag(void *element_a, void *element_b);
156
157 /* notes on BM_SetIndex(...) usage,
158  * Set index is sometimes abused as temp storage, other times we cant be
159  * sure if the index values are valid because certain operations have modified
160  * the mesh structure.
161  *
162  * To set the elements to valid indicies 'BM_ElemIndex_Ensure' should be used
163  * rather then adding inline loops, however there are cases where we still
164  * set the index directly
165  *
166  * In an attempt to manage this, here are 3 tags Im adding to uses of
167  * 'BM_SetIndex'
168  *
169  * - 'set_inline'  -- since the data is already being looped over set to a
170  *                    valid value inline.
171  *
172  * - 'set_dirty!'  -- intentionally sets the index to an invalid value,
173  *                    flagging 'bm->elem_index_dirty' so we dont use it.
174  *
175  * - 'set_ok'      -- this is valid use since the part of the code is low level.
176  *
177  * - 'set_ok_invalid'  -- set to -1 on purpose since this should not be
178  *                    used without a full array re-index, do this on
179  *                    adding new vert/edge/faces since they may be added at
180  *                    the end of the array.
181  *
182  * - 'set_loop'    -- currently loop index values are not used used much so
183  *                    assume each case they are dirty.
184  * - campbell */
185
186 BM_INLINE void BM_SetIndex(void *element, const int index);
187 BM_INLINE int BM_GetIndex(const void *element);
188
189 /* copies loop data from adjacent faces */
190 void BM_Face_CopyShared(BMesh *bm, BMFace *f);
191
192 /* copies attributes, e.g. customdata, header flags, etc, from one element
193  * to another of the same type.*/
194 void BM_Copy_Attributes(BMesh *source_mesh, BMesh *target_mesh, const void *source, void *target);
195
196 /* Modification */
197 /* join two adjacent faces together along an edge.  note that
198  * the faces must only be joined by on edge.  e is the edge you
199  * wish to dissolve.*/
200 BMFace *BM_Join_TwoFaces(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e);
201
202 /* generic, flexible join faces function; note that most everything uses
203  * this, including BM_Join_TwoFaces*/
204 BMFace *BM_Join_Faces(BMesh *bm, BMFace **faces, int totface);
205
206 /* split a face along two vertices.  returns the newly made face, and sets
207  * the nl member to a loop in the newly created edge.*/
208 BMFace *BM_Split_Face(BMesh *bm, BMFace *f,
209                       BMVert *v1, BMVert *v2,
210                       struct BMLoop **nl, BMEdge *example);
211
212 /* these 2 functions are very similar */
213 BMEdge* BM_Collapse_Vert_Faces(BMesh *bm, BMEdge *ke, BMVert *kv, float fac, const int join_faces);
214 BMEdge* BM_Collapse_Vert_Edges(BMesh *bm, BMEdge *ke, BMVert *kv);
215
216
217 /* splits an edge.  ne is set to the new edge created. */
218 BMVert *BM_Split_Edge(BMesh *bm, BMVert *v, BMEdge *e, BMEdge **ne, float percent);
219
220 /* split an edge multiple times evenly*/
221 BMVert  *BM_Split_Edge_Multi(BMesh *bm, BMEdge *e, int numcuts);
222
223 /* connect two verts together, through a face they share.  this function may
224  * be removed in the future. */
225 BMEdge *BM_Connect_Verts(BMesh *bm, BMVert *v1, BMVert *v2, BMFace **nf);
226
227 /* rotates an edge topologically, either clockwise (if ccw=0) or counterclockwise
228  * (if ccw is 1). */
229 BMEdge *BM_Rotate_Edge(BMesh *bm, BMEdge *e, int ccw);
230
231 /* Rip a single face from a vertex fan */
232 BMVert *BM_Rip_Vertex(BMesh *bm, BMFace *sf, BMVert *sv);
233
234 /*updates a face normal*/
235 void BM_Face_UpdateNormal(BMesh *bm, BMFace *f);
236 void BM_Face_UpdateNormal_VertexCos(BMesh *bm, BMFace *f, float no[3], float (*vertexCos)[3]);
237
238 /*updates face and vertex normals incident on an edge*/
239 void BM_Edge_UpdateNormals(BMesh *bm, BMEdge *e);
240
241 /*update a vert normal (but not the faces incident on it)*/
242 void BM_Vert_UpdateNormal(BMesh *bm, BMVert *v);
243 void BM_Vert_UpdateAllNormals(BMesh *bm, BMVert *v);
244
245 void BM_flip_normal(BMesh *bm, BMFace *f);
246
247 /*dissolves all faces around a vert, and removes it.*/
248 int BM_Dissolve_Disk(BMesh *bm, BMVert *v);
249
250 /*dissolves vert, in more situations then BM_Dissolve_Disk
251   (e.g. if the vert is part of a wire edge, etc).*/
252 int BM_Dissolve_Vert(BMesh *bm, BMVert *v);
253
254 /* Projects co onto face f, and returns true if it is inside
255  * the face bounds.  Note that this uses a best-axis projection
256  * test, instead of projecting co directly into f's orientation
257  * space, so there might be accuracy issues.*/
258 int BM_Point_In_Face(BMesh *bm, BMFace *f, const float co[3]);
259
260 /* Interpolation */
261
262 /* projects target onto source for customdata interpolation.  note: only
263  * does loop customdata.  multires is handled.  */
264 void BM_face_interp_from_face(BMesh *bm, BMFace *target, BMFace *source);
265
266 /* projects a single loop, target, onto source for customdata interpolation. multires is handled.
267  * if do_vertex is true, target's vert data will also get interpolated.*/
268 void BM_loop_interp_from_face(BMesh *bm, BMLoop *target, BMFace *source,
269                               int do_vertex, int do_multires);
270
271 /* smoothes boundaries between multires grids, including some borders in adjacent faces */
272 void BM_multires_smooth_bounds(BMesh *bm, BMFace *f);
273
274 /* project the multires grid in target onto source's set of multires grids */
275 void BM_loop_interp_multires(BMesh *bm, BMLoop *target, BMFace *source);
276 void BM_vert_interp_from_face(BMesh *bm, BMVert *v, BMFace *source);
277
278 void BM_Data_Interp_From_Verts (BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v, float fac);
279 void BM_Data_Facevert_Edgeinterp (BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v, struct BMEdge *e1, float fac);
280 void BM_add_data_layer (BMesh *em, CustomData *data, int type);
281 void BM_add_data_layer_named (BMesh *bm, CustomData *data, int type, const char *name);
282 void BM_free_data_layer (BMesh *em, CustomData *data, int type);
283 void BM_free_data_layer_n(BMesh *bm, CustomData *data, int type, int n);
284 float BM_GetCDf(struct CustomData *cd, void *element, int type);
285 void BM_SetCDf(struct CustomData *cd, void *element, int type, float val);
286
287 /* get the area of the face */
288 float BM_Compute_Face_Area(BMesh *bm, BMFace *f);
289 /* computes the centroid of a face, using the center of the bounding box */
290 void BM_Compute_Face_CenterBounds(BMesh *bm, BMFace *f, float center[3]);
291 /* computes the centroid of a face, using the mean average */
292 void BM_Compute_Face_CenterMean(BMesh *bm, BMFace *f, float center[3]);
293
294 void BM_SelectMode_Flush(BMesh *bm);
295
296 /*convert an editmesh to a bmesh*/
297 BMesh *editmesh_to_bmesh(struct EditMesh *em);
298
299 /* initializes editmesh to bmesh operator, but doesn't execute.
300  * this is used in situations where you need to get access to the
301  * conversion operator's editmesh->bmesh mapping slot (e.g. if you
302  * need to find the bmesh edge that corrusponds to a specific editmesh
303  * edge).*/
304 BMesh *init_editmesh_to_bmesh(struct EditMesh *em, struct BMOperator *op);
305
306 /* converts a bmesh to an editmesh */
307 struct EditMesh *bmesh_to_editmesh(BMesh *bm);
308
309 /* unused, type spesific functions below */
310 #if 0
311 /*convert between bmesh and Mesh flags*/
312 short BMFlags_To_MEFlags(void *element);
313
314 /* convert between Mesh and bmesh flags
315  * type must be BM_VERT/BM_EDGE/BM_FACE,
316  * and represents the type of the element
317  * parameter (the three defines map to
318  * MVert, MEdge, and MPoly, respectively). */
319 char MEFlags_To_BMFlags(const short hflag, const char htype);
320 #endif
321
322 /* flag conversion funcs */
323 char BM_Face_Flag_From_MEFlag(const char  mflag);
324 char BM_Edge_Flag_From_MEFlag(const short mflag);
325 char BM_Vert_Flag_From_MEFlag(const char  mflag);
326 /* reverse */
327 char  BM_Face_Flag_To_MEFlag(BMFace *f);
328 short BM_Edge_Flag_To_MEFlag(BMEdge *e);
329 char  BM_Vert_Flag_To_MEFlag(BMVert *v);
330
331
332 /* convert MLoop*** in a bmface to mtface and mcol in
333  * an MFace*/
334 void BM_loops_to_corners(BMesh *bm, struct Mesh *me, int findex,
335                          BMFace *f, int numTex, int numCol);
336
337 void BM_Kill_Loop(BMesh *bm, BMLoop *l);
338 void BM_Kill_Face(BMesh *bm, BMFace *f);
339 void BM_Kill_Edge(BMesh *bm, BMEdge *e);
340 void BM_Kill_Vert(BMesh *bm, BMVert *v);
341
342 /* kills all edges associated with f, along with any other faces containing
343  * those edges*/
344 void BM_Kill_Face_Edges(BMesh *bm, BMFace *f);
345
346 /* kills all verts associated with f, along with any other faces containing
347  * those vertices*/
348 void BM_Kill_Face_Verts(BMesh *bm, BMFace *f);
349
350 /*clear all data in bm*/
351 void BM_Clear_Mesh(BMesh *bm);
352
353 void BM_ElemIndex_Ensure(BMesh *bm, const char hflag);
354
355 void BM_ElemIndex_Validate(BMesh *bm, const char *location, const char *func,
356                            const char *msg_a, const char *msg_b);
357
358 BMVert *BM_Vert_AtIndex(BMesh *bm, const int index);
359 BMEdge *BM_Edge_AtIndex(BMesh *bm, const int index);
360 BMFace *BM_Face_AtIndex(BMesh *bm, const int index);
361
362 /*start/stop edit*/
363 void bmesh_begin_edit(BMesh *bm, int flag);
364 void bmesh_end_edit(BMesh *bm, int flag);
365
366
367 #define BM_FACE_FIRST_LOOP(p) (((BMLoopList *)((p)->loops.first))->first)
368
369 /* size to use for static arrays when dealing with NGons,
370  * alloc after this limit is reached.
371  * this value is rather arbitrary */
372 #define BM_NGON_STACK_SIZE 32
373
374 /* avoid inf loop, this value is arbtrary
375  * but should not error on valid cases */
376 #define BM_LOOP_RADIAL_MAX 10000
377 #define BM_NGON_MAX 100000
378
379 /* include the rest of the API */
380 #include "bmesh_filters.h"
381 #include "bmesh_marking.h"
382 #include "bmesh_operator_api.h"
383 #include "bmesh_operators.h"
384 #include "bmesh_error.h"
385 #include "bmesh_queries.h"
386 #include "bmesh_iterators.h"
387 #include "bmesh_walkers.h"
388 #include "intern/bmesh_inline.c"
389
390 #ifdef __cplusplus
391 }
392 #endif
393
394 #endif /* BMESH_H */