bmesh: fixed merge issues with navmesh (though I've not tested if it works yet).
[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. The Blender
10  * Foundation also sells licenses for use in proprietary software under
11  * the Blender License.  See http://www.blender.org/BL/ for information
12  * about this.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
22  *
23  * Contributor(s): Geoffrey Bantle, Levi Schooley.
24  *
25  * ***** END GPL LICENSE BLOCK *****
26  */
27
28 #ifndef BMESH_H
29 #define BMESH_H
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 #include "DNA_listBase.h"
36 #include "DNA_scene_types.h"
37 #include "DNA_customdata_types.h"
38
39 #include "BKE_customdata.h"
40
41 #include "BLI_utildefines.h"
42         
43 /*
44 short introduction:
45
46 the bmesh structure is a boundary representation, supporting non-manifold
47 locally modifiable topology. the API is designed to allow clean, maintainable
48 code, that never (or almost never) directly inspects the underlying structure.
49
50 The API includes iterators, including many useful topological iterators;
51 walkers, which walk over a mesh, without the risk of hitting the recursion
52 limit; operators, which are logical, reusable mesh modules; topological
53 modification functions (like split face, join faces, etc), which are used for
54 topological manipulations; and some (not yet finished) geometric utility
55 functions.
56
57 some definitions:
58
59 tool flags: private flags for tools.  each operator has it's own private
60             tool flag "layer", which it can use to flag elements.
61             tool flags are also used by various other parts of the api.
62 header flags: stores persistent flags, such as selection state, hide state,
63               etc.  be careful of touching these.
64 */
65
66 /*forward declarations*/
67 struct BMesh;
68 struct BMVert;
69 struct BMEdge;
70 struct BMFace;
71 struct BMLoop;
72 struct BMOperator;
73 struct Mesh;
74 struct EditMesh;
75
76 /*
77  * BMHeader
78  *
79  * All mesh elements begin with a BMHeader. This structure
80  * hold several types of data
81  *
82  * 1: The type of the element (vert, edge, loop or face)
83  * 2: Persistant "header" flags/markings (sharp, seam, select, hidden, ect)
84       note that this is different from the "tool" flags.
85  * 3: Unique ID in the bmesh.
86  * 4: some elements for internal record keeping.
87  *
88 */
89
90 /*BMHeader->type*/
91 #define BM_VERT         1
92 #define BM_EDGE         2
93 #define BM_LOOP         4
94 #define BM_FACE         8
95 #define BM_ALL          (BM_VERT | BM_EDGE | BM_LOOP | BM_FACE)
96
97 /*BMHeader->flag*/
98 #define BM_SELECT       (1<<0)
99
100 #define BM_SEAM         (1<<1)
101 #define BM_FGON         (1<<2)
102 #define BM_HIDDEN       (1<<3)
103 #define BM_SHARP        (1<<4)
104 #define BM_SMOOTH       (1<<5)
105 #define BM_ACTIVE       (1<<6)
106 #define BM_TMP_TAG      (1<<7) /* internal flag, used for ensuring correct normals
107                             * during multires interpolation, and any other time
108                             * when temp tagging is handy.
109                             * always assume dirty & clear before use. */
110
111 /* #define BM_NONORMCALC (1<<8) */ /* UNUSED */
112
113 #include "bmesh_class.h"
114
115 /*stub */
116 void bmesh_error ( void );
117
118 /*Mesh Level Ops */
119
120 /*ob is needed by multires*/
121 struct BMesh *BM_Make_Mesh (struct Object *ob, int allocsize[4] );
122 BMesh *BM_Copy_Mesh ( BMesh *bmold );
123 void BM_Free_Mesh ( struct BMesh *bm );
124
125 /*frees mesh, but not actual BMesh struct*/
126 void BM_Free_Mesh_Data ( BMesh *bm );
127 void BM_Compute_Normals ( struct BMesh *bm );
128
129 /*Construction*/
130 struct BMVert *BM_Make_Vert ( struct BMesh *bm, float co[3], const struct BMVert *example );
131 struct BMEdge *BM_Make_Edge ( struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, const struct BMEdge *example, int nodouble );
132 struct BMFace *BM_Make_Quadtriangle ( struct BMesh *bm, struct BMVert **verts, BMEdge **edges, int len, const struct BMFace *example, int nodouble );
133
134 BMFace *BM_Make_Face(BMesh *bm, BMVert **verts, BMEdge **edges, int len, int nodouble);
135
136 /*more easier to use version of BM_Make_Quadtriangle.
137   creates edges if necassary.*/
138 BMFace *BM_Make_QuadTri ( BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v3,
139                           BMVert *v4, const BMFace *example, int nodouble );
140
141 /*makes an ngon from an unordered list of edges.  v1 and v2 must be the verts
142 defining edges[0], and define the winding of the new face.*/
143 struct BMFace *BM_Make_Ngon ( struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge **edges, int len, int nodouble );
144
145 /*stuff for dealing with header flags*/
146 BM_INLINE char BM_TestHFlag(const void *element, const char hflag);
147
148 /*stuff for dealing with header flags*/
149 BM_INLINE void BM_SetHFlag(void *element, const char hflag);
150
151 /*stuff for dealing with header flags*/
152 BM_INLINE void BM_ClearHFlag(void *element, const char hflag);
153
154 /*stuff for dealing BM_ToggleHFlag header flags*/
155 BM_INLINE void BM_ToggleHFlag(void *element, const char hflag);
156 BM_INLINE void BM_MergeHFlag(void *element_a, void *element_b);
157 BM_INLINE void BM_SetIndex(void *element, const int index);
158 BM_INLINE int BM_GetIndex(const void *element);
159
160 /*copies loop data from adjacent faces*/
161 void BM_Face_CopyShared ( BMesh *bm, BMFace *f );
162
163 /*copies attributes, e.g. customdata, header flags, etc, from one element
164   to another of the same type.*/
165 void BM_Copy_Attributes ( struct BMesh *source_mesh, struct BMesh *target_mesh, const void *source, void *target );
166
167 /*Modification*/
168 /*join two adjacent faces together along an edge.  note that
169   the faces must only be joined by on edge.  e is the edge you
170   wish to dissolve.*/
171 BMFace *BM_Join_TwoFaces(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e);
172
173 /*generic, flexible join faces function; note that most everything uses
174   this, including BM_Join_TwoFaces*/
175 BMFace *BM_Join_Faces(BMesh *bm, BMFace **faces, int totface);
176
177 /*split a face along two vertices.  returns the newly made face, and sets
178   the nl member to a loop in the newly created edge.*/
179 struct BMFace *BM_Split_Face ( struct BMesh *bm, struct BMFace *f,
180                                            struct BMVert *v1, struct BMVert *v2,
181                                            struct BMLoop **nl, struct BMEdge *example );
182
183 /*dissolves a vert shared only by two edges*/
184 BMEdge* BM_Collapse_Vert ( struct BMesh *bm, struct BMEdge *ke, struct BMVert *kv,
185                         float fac );
186
187 /*splits an edge.  ne is set to the new edge created.*/
188 struct BMVert *BM_Split_Edge ( struct BMesh *bm, struct BMVert *v,
189                                            struct BMEdge *e, struct BMEdge **ne,
190                                            float percent );
191
192 /*split an edge multiple times evenly*/
193 struct BMVert  *BM_Split_Edge_Multi ( struct BMesh *bm, struct BMEdge *e,
194                                                   int numcuts );
195
196 /*connect two verts together, through a face they share.  this function may
197   be removed in the future.*/
198 BMEdge *BM_Connect_Verts ( BMesh *bm, BMVert *v1, BMVert *v2, BMFace **nf );
199
200 /*rotates an edge topologically, either clockwise (if ccw=0) or counterclockwise
201   (if ccw is 1).*/
202 BMEdge *BM_Rotate_Edge ( BMesh *bm, BMEdge *e, int ccw );
203
204 /* Rip a single face from a vertex fan */
205 BMVert *BM_Rip_Vertex ( BMesh *bm, BMFace *sf, BMVert *sv);
206
207 /*updates a face normal*/
208 void BM_Face_UpdateNormal ( BMesh *bm, BMFace *f );
209
210 /*updates face and vertex normals incident on an edge*/
211 void BM_Edge_UpdateNormals ( BMesh *bm, BMEdge *e );
212
213 /*update a vert normal (but not the faces incident on it)*/
214 void BM_Vert_UpdateNormal ( BMesh *bm, BMVert *v );
215 void BM_Vert_UpdateAllNormals ( BMesh *bm, BMVert *v );
216
217 void BM_flip_normal ( BMesh *bm, BMFace *f );
218
219 /*dissolves all faces around a vert, and removes it.*/
220 int BM_Dissolve_Disk ( BMesh *bm, BMVert *v );
221
222 /*dissolves vert, in more situations then BM_Dissolve_Disk
223   (e.g. if the vert is part of a wire edge, etc).*/
224 int BM_Dissolve_Vert ( BMesh *bm, BMVert *v );
225
226 /*Projects co onto face f, and returns true if it is inside
227   the face bounds.  Note that this uses a best-axis projection
228   test, instead of projecting co directly into f's orientation
229   space, so there might be accuracy issues.*/
230 int BM_Point_In_Face(BMesh *bm, BMFace *f, float co[3]);
231
232 /*Interpolation*/
233
234 /*projects target onto source for customdata interpolation.  note: only
235   does loop customdata.  multires is handled.  */
236 void BM_face_interp_from_face(BMesh *bm, BMFace *target, BMFace *source);
237
238 /*projects a single loop, target, onto source for customdata interpolation. multires is handled.  
239   if do_vertex is true, target's vert data will also get interpolated.*/
240 void BM_loop_interp_from_face(BMesh *bm, BMLoop *target, BMFace *source, 
241                               int do_vertex, int do_multires);
242
243 /*smoothes boundaries between multires grids, including some borders in adjacent faces*/
244 void BM_multires_smooth_bounds(BMesh *bm, BMFace *f);
245
246 /*project the multires grid in target onto source's set of multires grids*/
247 void BM_loop_interp_multires(BMesh *bm, BMLoop *target, BMFace *source);
248 void BM_vert_interp_from_face(BMesh *bm, BMVert *v, BMFace *source);
249
250 void BM_Data_Interp_From_Verts (struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, float fac);
251 void BM_Data_Facevert_Edgeinterp (struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, struct BMEdge *e1, float fac);
252 void BM_add_data_layer (BMesh *em, CustomData *data, int type);
253 void BM_add_data_layer_named (BMesh *bm, CustomData *data, int type, const char *name);
254 void BM_free_data_layer (BMesh *em, CustomData *data, int type );
255 void BM_free_data_layer_n(BMesh *bm, CustomData *data, int type, int n);
256 float BM_GetCDf(struct CustomData *cd, void *element, int type);
257 void BM_SetCDf(struct CustomData *cd, void *element, int type, float val);
258
259 /*computes the centroid of a face, using the center of the bounding box*/
260 int BM_Compute_Face_Center ( BMesh *bm, BMFace *f, float center[3] );
261
262 void BM_SelectMode_Flush ( BMesh *bm );
263
264 /*convert an editmesh to a bmesh*/
265 BMesh *editmesh_to_bmesh ( struct EditMesh *em );
266
267 /*initializes editmesh to bmesh operator, but doesn't execute.
268   this is used in situations where you need to get access to the
269   conversion operator's editmesh->bmesh mapping slot (e.g. if you
270   need to find the bmesh edge that corrusponds to a specific editmesh
271   edge).*/
272 BMesh *init_editmesh_to_bmesh ( struct EditMesh *em, struct BMOperator *op );
273
274 /*converts a bmesh to an editmesh*/
275 struct EditMesh *bmesh_to_editmesh ( BMesh *bm );
276
277 /*convert between bmesh and Mesh flags*/
278 short BMFlags_To_MEFlags(void *element);
279
280 /*convert between Mesh and bmesh flags
281   type must be BM_VERT/BM_EDGE/BM_FACE,
282   and represents the type of the element
283   parameter (the three defines map to
284   MVert, MEdge, and MPoly, respectively).*/
285 char MEFlags_To_BMFlags(const char hflag, const char htype);
286
287 /*convert MLoop*** in a bmface to mtface and mcol in
288   an MFace*/
289 void BM_loops_to_corners ( BMesh *bm, struct Mesh *me, int findex,
290                            BMFace *f, int numTex, int numCol );
291
292 void BM_Kill_Loop(BMesh *bm, BMLoop *l);
293 void BM_Kill_Face(BMesh *bm, BMFace *f);
294 void BM_Kill_Edge(BMesh *bm, BMEdge *e);
295 void BM_Kill_Vert(BMesh *bm, BMVert *v);
296
297 /*kills all edges associated with f, along with any other faces containing
298   those edges*/
299 void BM_Kill_Face_Edges(BMesh *bm, BMFace *f);
300
301 /*kills all verts associated with f, along with any other faces containing
302   those vertices*/
303 void BM_Kill_Face_Verts(BMesh *bm, BMFace *f) ;
304
305 /*clear all data in bm*/
306 void BM_Clear_Mesh(BMesh *bm);
307
308 /*start/stop edit*/
309 void bmesh_begin_edit(struct BMesh *bm, int flag);
310 void bmesh_end_edit(struct BMesh *bm, int flag);
311
312
313 #define bm_firstfaceloop(p) ((BMLoopList*)(p->loops.first))->first
314
315 /*include the rest of the API*/
316 #include "bmesh_filters.h"
317 #include "bmesh_iterators.h"
318 #include "bmesh_marking.h"
319 #include "bmesh_operator_api.h"
320 #include "bmesh_operators.h"
321 #include "bmesh_error.h"
322 #include "bmesh_queries.h"
323 #include "bmesh_walkers.h"
324 #include "intern/bmesh_inline.c"
325
326 #ifdef __cplusplus
327 }
328 #endif
329
330 #endif /* BMESH_H */