(NOTE: DO NOT TEST)
[blender.git] / source / blender / bmesh / bmesh.h
1 /**
2  *  bmesh.h    jan 2007
3  *
4  *      BMesh API.
5  *
6  * $Id: BKE_bmesh.h,v 1.00 2007/01/17 17:42:01 Briggs Exp $
7  *
8  * ***** BEGIN GPL LICENSE BLOCK *****
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License
12  * as published by the Free Software Foundation; either version 2
13  * of the License, or (at your option) any later version. The Blender
14  * Foundation also sells licenses for use in proprietary software under
15  * the Blender License.  See http://www.blender.org/BL/ for information
16  * about this.  
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
26  *
27  * The Original Code is Copyright (C) 2004 Blender Foundation.
28  * All rights reserved.
29  *
30  * The Original Code is: all of this file.
31  *
32  * Contributor(s): Geoffrey Bantle, Levi Schooley.
33  *
34  * ***** END GPL LICENSE BLOCK *****
35  */
36
37 #ifndef BMESH_H
38 #define BMESH_H
39
40 #include "DNA_listBase.h"
41 #include "DNA_customdata_types.h"
42 #include "DNA_scene_types.h"
43 #include "BLI_mempool.h"
44 #include "BKE_customdata.h"
45
46 /*
47 short introduction:
48
49 the bmesh structure is a boundary representation, supporting non-manifold 
50 locally modifiable topology. the API is designed to allow clean, maintainable
51 code, that never (or almost never) directly inspects the underlying structure.
52
53 The API includes iterators, including many useful topological iterators;
54 walkers, which walk over a mesh, without the risk of hitting the recursion
55 limit; operators, which are logical, reusable mesh modules; topological
56 modification functions (like split face, join faces, etc), which are used for 
57 topological manipulations; and some (not yet finished) geometric utility 
58 functions.
59
60 some definitions:
61
62 tool flags: private flags for tools.  each operator has it's own private
63             tool flag "layer", which it can use to flag elements.
64             tool flags are also used by various other parts of the api.
65 header flags: stores persistent flags, such as selection state, hide state,
66               etc.  be careful of touching these.
67 */
68
69 /*forward declarations*/
70 struct BMVert;
71 struct BMEdge;
72 struct BMFace;
73 struct BMLoop;
74 struct EditMesh;
75 struct BMOperator;
76
77 /*
78  * BMHeader
79  *
80  * All mesh elements begin with a BMHeader. This structure 
81  * hold several types of data
82  *
83  * 1: The type of the element (vert, edge, loop or face)
84  * 2: Persistant flags/markings (sharp, seam, select, hidden, ect)
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_FACE         4
94 #define BM_LOOP         8
95 #define BM_ALL          BM_VERT | BM_EDGE | BM_FACE | BM_LOOP
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_NONORMCALC   (1<<7)
107
108 typedef struct BMHeader {
109         struct BMHeader *next, *prev;
110         int             EID;  /*Consider removing this/making it ifdeffed for debugging*/
111         
112         /*don't confuse this with tool flags.  this flag
113           member is what "header flag" means.*/
114         int             flag;
115         int             type;
116         int                     eflag1, eflag2; /*Flags used by eulers. Try and get rid of/minimize some of these*/
117         
118         //this can only be used to store a temporary index.  don't use it for anything else.
119         int index;
120         struct BMFlagLayer *flags; /*Dynamically allocated block of flag layers for operators to use*/
121 } BMHeader;
122
123 typedef struct BMFlagLayer {
124         int f1;
125         short mask, pflag;
126 } BMFlagLayer;
127
128 #define BM_OVERLAP              (1<<14)                 /*used by bmesh_verts_in_face*/
129 #define BM_EDGEVERT     (1<<15)                 /*used by bmesh_make_ngon*/
130
131 /*
132  * BMNode
133  *
134  * Used for circular/linked list functions that form basis of
135  * adjacency system in BMesh. This should probably be hidden 
136  * somewhere since tool authors never need to know about it.
137  *
138 */
139
140 typedef struct BMNode {
141         struct BMNode *next, *prev;
142         void *data;
143 } BMNode;
144
145 typedef struct BMesh {
146         ListBase verts, edges, polys;
147         struct BLI_mempool *vpool;
148         struct BLI_mempool *epool;
149         struct BLI_mempool *lpool;
150         struct BLI_mempool *ppool;
151         struct BMVert **vtar;
152         struct BMEdge **edar;
153         struct BMLoop **lpar;
154         struct BMFace **plar;
155         int vtarlen, edarlen, lparlen, plarlen;
156         int totvert, totedge, totface, totloop; 
157         int totvertsel, totedgesel, totfacesel;
158         int nextv, nexte, nextp, nextl;
159         struct CustomData vdata, edata, pdata, ldata;
160         int selectmode; /*now uses defines in DNA_scene_types.h*/
161         struct BLI_mempool *flagpool;                                   /*memory pool for dynamically allocated flag layers*/
162         int stackdepth;                                                                 /*current depth of operator stack*/
163         int totflags, walkers;                                                  /*total number of tool flag layers*/
164         ListBase errorstack;
165 } BMesh;
166
167 typedef struct BMVert { 
168         struct BMHeader head;
169         float co[3];                                                                    
170         float no[3];                                                                    
171         struct BMEdge *edge;
172         void *data;
173         void *tmp;                                                                                                      /*what?*/
174         float bweight;                                                                                          /*please, someone just get rid of me...*/
175 } BMVert;
176
177 typedef struct BMEdge {
178         struct BMHeader head;
179         struct BMVert *v1, *v2;
180         struct BMNode d1, d2;
181         struct BMLoop *loop;
182         void *data;
183         float crease, bweight; /*make these custom data.... no really, please....*/
184 } BMEdge;
185
186 typedef struct BMLoop  {
187         struct BMHeader head;
188         struct BMNode radial;
189         struct BMVert *v;
190         struct BMEdge *e;
191         struct BMFace *f;       
192         void *data;
193 } BMLoop;
194
195 typedef struct BMFace {
196         struct BMHeader head;
197         struct BMLoop *loopbase;
198         int len;
199         void *data;
200         float no[3];
201
202         /*custom data again*/
203         short mat_nr; 
204 } BMFace;
205
206 /*stub */
207 void bmesh_error(void);
208
209 /*Mesh Level Ops */
210 struct BMesh *BM_Make_Mesh(int allocsize[4]);
211 BMesh *BM_Copy_Mesh(BMesh *bmold);
212 void BM_Free_Mesh(struct BMesh *bm);
213
214 /*frees mesh, but not actual BMesh struct*/
215 void BM_Free_Mesh_Data(BMesh *bm);
216 void BM_Compute_Normals(struct BMesh *bm);
217
218 /*Construction*/
219 struct BMVert *BM_Make_Vert(struct BMesh *bm, float co[3], struct BMVert *example);
220 struct BMEdge *BM_Make_Edge(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge *example, int nodouble);
221 struct BMFace *BM_Make_Quadtriangle(struct BMesh *bm, struct BMVert **verts, BMEdge **edges, int len, struct BMFace *example, int nodouble);
222 /*more easier to use version of BM_Make_Quadtriangle*/
223 BMFace *BM_Make_QuadTri(BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v3, BMVert *v4, BMFace *example);
224
225 /*makes an ngon from an unordered list of edges.  v1 and v2 must be the verts
226 defining edges[0], and define the winding of the new face.*/
227 struct BMFace *BM_Make_Ngon(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge **edges, int len, int nodouble);
228
229 /*stuff for dealing with header flags*/
230 #define BM_TestHFlag(ele, f) (((BMHeader*)ele)->flag & (f))
231 #define BM_SetHFlag(ele, f) (((BMHeader*)ele)->flag = ((BMHeader*)ele)->flag | (f))
232 #define BM_ClearHFlag(ele, f) (((BMHeader*)ele)->flag = ((BMHeader*)ele)->flag & ~(f))
233
234 /*stuff for setting indices*/
235 #define BMINDEX_SET(ele, i) (((BMHeader*)ele)->index = i)
236 #define BMINDEX_GET(ele) ((BMHeader*)ele)->index
237
238 /*copies loop data from adjacent faces*/
239 void BM_Face_CopyShared(BMesh *bm, BMFace *f);
240
241 /*copies attributes, e.g. customdata, header flags, etc, from one element
242   to another of the same type.*/
243 void BM_Copy_Attributes(struct BMesh *source_mesh, struct BMesh *target_mesh, void *source, void *target);
244
245 /*remove tool flagged elements*/
246 void BM_remove_tagged_faces(struct BMesh *bm, int flag);
247 void BM_remove_tagged_edges(struct BMesh *bm, int flag);
248 void BM_remove_tagged_verts(struct BMesh *bm, int flag);
249
250
251 /*Modification*/
252 /*join two adjacent faces together along an edge.  note that
253   the faces must only be joined by on edge.  e is the edge you
254   wish to dissolve.*/
255 struct BMFace *BM_Join_Faces(struct BMesh *bm, struct BMFace *f1, 
256                              struct BMFace *f2, struct BMEdge *e);
257
258 /*split a face along two vertices.  returns the newly made face, and sets
259   the nl member to a loop in the newly created edge.*/
260 struct BMFace *BM_Split_Face(struct BMesh *bm, struct BMFace *f,  
261                              struct BMVert *v1, struct BMVert *v2, 
262                              struct BMLoop **nl, struct BMEdge *example);
263
264 /*dissolves a vert shared only by two edges*/
265 void BM_Collapse_Vert(struct BMesh *bm, struct BMEdge *ke, struct BMVert *kv, 
266                       float fac);
267
268 /*splits an edge.  ne is set to the new edge created.*/
269 struct BMVert *BM_Split_Edge(struct BMesh *bm, struct BMVert *v, 
270                              struct BMEdge *e, struct BMEdge **ne,
271                              float percent);
272
273 /*split an edge multiple times evenly*/
274 struct BMVert  *BM_Split_Edge_Multi(struct BMesh *bm, struct BMEdge *e, 
275                                     int numcuts);
276
277 /*connect two verts together, through a face they share.  this function may
278   be removed in the future.*/
279 BMEdge *BM_Connect_Verts(BMesh *bm, BMVert *v1, BMVert *v2, BMFace **nf);
280
281
282 /*updates a face normal*/
283 void BM_Face_UpdateNormal(BMesh *bm, BMFace *f);
284
285 /*updates face and vertex normals incident on an edge*/
286 void BM_Edge_UpdateNormals(BMesh *bm, BMEdge *e);
287
288 /*update a vert normal (but not the faces incident on it)*/
289 void BM_Vert_UpdateNormal(BMesh *bm, BMVert *v);
290
291
292 /*dissolves all faces around a vert, and removes it.*/
293 int BM_Dissolve_Disk(BMesh *bm, BMVert *v);
294
295 /*dissolves vert, in more situations then BM_Dissolve_Disk
296   (e.g. if the vert is part of a wire edge, etc).*/
297 int BM_Dissolve_Vert(BMesh *bm, BMVert *v);
298
299
300 /*Interpolation*/
301 void BM_Data_Interp_From_Verts(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, float fac);
302 void BM_Data_Facevert_Edgeinterp(struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, struct BMEdge *e1, float fac);
303 //void bmesh_data_interp_from_face(struct BMesh *bm, struct BMFace *source, struct BMFace *target);
304
305 /*computes the centroid of a face, using the center of the bounding box*/
306 int BM_Compute_Face_Center(BMesh *bm, BMFace *f, float center[3]);
307 void BM_SelectMode_Flush(BMesh *bm);
308
309 /*convert an editmesh to a bmesh*/
310 BMesh *editmesh_to_bmesh(struct EditMesh *em);
311
312 /*initializes editmesh to bmesh operator, but doesn't execute.
313   this is used in situations where you need to get access to the
314   conversion operator's editmesh->bmesh mapping slot (e.g. if you
315   need to find the bmesh edge that corrusponds to a specific editmesh
316   edge).*/
317 BMesh *init_editmesh_to_bmesh(struct EditMesh *em, struct BMOperator *op);
318
319 /*converts a bmesh to an editmesh*/
320 struct EditMesh *bmesh_to_editmesh(BMesh *bm);
321
322 /*convert between bmesh and Mesh flags*/
323 int BMFlags_To_MEFlags(void *element);
324
325 /*include the rest of the API*/
326 #include "bmesh_filters.h"
327 #include "bmesh_iterators.h"
328 #include "bmesh_marking.h"
329 #include "bmesh_operator_api.h"
330 #include "bmesh_operators.h"
331 #include "bmesh_error.h"
332 #include "bmesh_queries.h"
333 #include "bmesh_walkers.h"
334
335 #endif /* BMESH_H */