6ce8e3790420d452e6cef10fd1847cd093881432
[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 struct BMesh *BM_Make_Mesh (struct Object *ob, int allocsize[4] );
119 BMesh *BM_Copy_Mesh ( BMesh *bmold );
120 void BM_Free_Mesh ( struct BMesh *bm );
121
122 /*frees mesh, but not actual BMesh struct*/
123 void BM_Free_Mesh_Data ( BMesh *bm );
124 void BM_Compute_Normals ( struct BMesh *bm );
125
126 /*Construction*/
127 struct BMVert *BM_Make_Vert ( struct BMesh *bm, const float co[3], const struct BMVert *example );
128 struct BMEdge *BM_Make_Edge ( struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, const struct BMEdge *example, int nodouble );
129 struct BMFace *BM_Make_Quadtriangle ( struct BMesh *bm, struct BMVert **verts, BMEdge **edges, int len, const struct BMFace *example, int nodouble );
130
131 BMFace *BM_Make_Face(BMesh *bm, BMVert **verts, BMEdge **edges, int len, int nodouble);
132
133 /*more easier to use version of BM_Make_Quadtriangle.
134   creates edges if necassary.*/
135 BMFace *BM_Make_QuadTri ( BMesh *bm, BMVert *v1, BMVert *v2, BMVert *v3,
136                           BMVert *v4, const BMFace *example, int nodouble );
137
138 /*makes an ngon from an unordered list of edges.  v1 and v2 must be the verts
139 defining edges[0], and define the winding of the new face.*/
140 struct BMFace *BM_Make_Ngon ( struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMEdge **edges, int len, int nodouble );
141
142 /*stuff for dealing with header flags*/
143 BM_INLINE char BM_TestHFlag(const void *element, const char hflag);
144
145 /*stuff for dealing with header flags*/
146 BM_INLINE void BM_SetHFlag(void *element, const char hflag);
147
148 /*stuff for dealing with header flags*/
149 BM_INLINE void BM_ClearHFlag(void *element, const char hflag);
150
151 /*stuff for dealing BM_ToggleHFlag header flags*/
152 BM_INLINE void BM_ToggleHFlag(void *element, const char hflag);
153 BM_INLINE void BM_MergeHFlag(void *element_a, void *element_b);
154
155 /* notes on BM_SetIndex(...) usage,
156  * Set index is sometimes abused as temp storage, other times we cant be
157  * sure if the index values are valid because certain operations have modified
158  * the mesh structure.
159  *
160  * To set the elements to valid indicies 'BM_ElemIndex_Ensure' should be used
161  * rather then adding inline loops, however there are cases where we still
162  * set the index directly
163  *
164  * In an attempt to manage this, here are 3 tags Im adding to uses of
165  * 'BM_SetIndex'
166  *
167  * - 'set_inline'  -- since the data is already being looped over set to a
168  *                    valid value inline.
169  *
170  * - 'set_dirty!'  -- intentionally sets the index to an invalid value,
171  *                    flagging 'bm->elem_index_dirty' so we dont use it.
172  *
173  * - 'set_ok'      -- this is valid use since the part of the code is low level.
174  *
175  * - 'set_ok_invalid'  -- set to -1 on purpose since this should not be
176  *                    used without a full array re-index, do this on
177  *                    adding new vert/edge/faces since they may be added at
178  *                    the end of the array.
179  *
180  * - 'set_loop'    -- currently loop index values are not used used much so
181  *                    assume each case they are dirty.
182  * - campbell */
183
184 BM_INLINE void BM_SetIndex(void *element, const int index);
185 BM_INLINE int BM_GetIndex(const void *element);
186
187 /*copies loop data from adjacent faces*/
188 void BM_Face_CopyShared ( BMesh *bm, BMFace *f );
189
190 /*copies attributes, e.g. customdata, header flags, etc, from one element
191   to another of the same type.*/
192 void BM_Copy_Attributes ( struct BMesh *source_mesh, struct BMesh *target_mesh, const void *source, void *target );
193
194 /*Modification*/
195 /*join two adjacent faces together along an edge.  note that
196   the faces must only be joined by on edge.  e is the edge you
197   wish to dissolve.*/
198 BMFace *BM_Join_TwoFaces(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e);
199
200 /*generic, flexible join faces function; note that most everything uses
201   this, including BM_Join_TwoFaces*/
202 BMFace *BM_Join_Faces(BMesh *bm, BMFace **faces, int totface);
203
204 /*split a face along two vertices.  returns the newly made face, and sets
205   the nl member to a loop in the newly created edge.*/
206 struct BMFace *BM_Split_Face ( struct BMesh *bm, struct BMFace *f,
207                                            struct BMVert *v1, struct BMVert *v2,
208                                            struct BMLoop **nl, struct BMEdge *example );
209
210 /*dissolves a vert shared only by two edges*/
211 BMEdge* BM_Collapse_Vert ( struct BMesh *bm, struct BMEdge *ke, struct BMVert *kv,
212                         float fac );
213
214 /*splits an edge.  ne is set to the new edge created.*/
215 struct BMVert *BM_Split_Edge ( struct BMesh *bm, struct BMVert *v,
216                                            struct BMEdge *e, struct BMEdge **ne,
217                                            float percent );
218
219 /*split an edge multiple times evenly*/
220 struct BMVert  *BM_Split_Edge_Multi ( struct BMesh *bm, struct BMEdge *e,
221                                                   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
237 /*updates face and vertex normals incident on an edge*/
238 void BM_Edge_UpdateNormals ( BMesh *bm, BMEdge *e );
239
240 /*update a vert normal (but not the faces incident on it)*/
241 void BM_Vert_UpdateNormal ( BMesh *bm, BMVert *v );
242 void BM_Vert_UpdateAllNormals ( BMesh *bm, BMVert *v );
243
244 void BM_flip_normal ( BMesh *bm, BMFace *f );
245
246 /*dissolves all faces around a vert, and removes it.*/
247 int BM_Dissolve_Disk ( BMesh *bm, BMVert *v );
248
249 /*dissolves vert, in more situations then BM_Dissolve_Disk
250   (e.g. if the vert is part of a wire edge, etc).*/
251 int BM_Dissolve_Vert ( BMesh *bm, BMVert *v );
252
253 /*Projects co onto face f, and returns true if it is inside
254   the face bounds.  Note that this uses a best-axis projection
255   test, instead of projecting co directly into f's orientation
256   space, so there might be accuracy issues.*/
257 int BM_Point_In_Face(BMesh *bm, BMFace *f, float co[3]);
258
259 /*Interpolation*/
260
261 /*projects target onto source for customdata interpolation.  note: only
262   does loop customdata.  multires is handled.  */
263 void BM_face_interp_from_face(BMesh *bm, BMFace *target, BMFace *source);
264
265 /*projects a single loop, target, onto source for customdata interpolation. multires is handled.  
266   if do_vertex is true, target's vert data will also get interpolated.*/
267 void BM_loop_interp_from_face(BMesh *bm, BMLoop *target, BMFace *source, 
268                               int do_vertex, int do_multires);
269
270 /*smoothes boundaries between multires grids, including some borders in adjacent faces*/
271 void BM_multires_smooth_bounds(BMesh *bm, BMFace *f);
272
273 /*project the multires grid in target onto source's set of multires grids*/
274 void BM_loop_interp_multires(BMesh *bm, BMLoop *target, BMFace *source);
275 void BM_vert_interp_from_face(BMesh *bm, BMVert *v, BMFace *source);
276
277 void BM_Data_Interp_From_Verts (struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, float fac);
278 void BM_Data_Facevert_Edgeinterp (struct BMesh *bm, struct BMVert *v1, struct BMVert *v2, struct BMVert *v, struct BMEdge *e1, float fac);
279 void BM_add_data_layer (BMesh *em, CustomData *data, int type);
280 void BM_add_data_layer_named (BMesh *bm, CustomData *data, int type, const char *name);
281 void BM_free_data_layer (BMesh *em, CustomData *data, int type );
282 void BM_free_data_layer_n(BMesh *bm, CustomData *data, int type, int n);
283 float BM_GetCDf(struct CustomData *cd, void *element, int type);
284 void BM_SetCDf(struct CustomData *cd, void *element, int type, float val);
285
286 /*computes the centroid of a face, using the center of the bounding box*/
287 int BM_Compute_Face_Center ( BMesh *bm, BMFace *f, float center[3] );
288
289 void BM_SelectMode_Flush ( BMesh *bm );
290
291 /*convert an editmesh to a bmesh*/
292 BMesh *editmesh_to_bmesh ( struct EditMesh *em );
293
294 /*initializes editmesh to bmesh operator, but doesn't execute.
295   this is used in situations where you need to get access to the
296   conversion operator's editmesh->bmesh mapping slot (e.g. if you
297   need to find the bmesh edge that corrusponds to a specific editmesh
298   edge).*/
299 BMesh *init_editmesh_to_bmesh ( struct EditMesh *em, struct BMOperator *op );
300
301 /*converts a bmesh to an editmesh*/
302 struct EditMesh *bmesh_to_editmesh ( BMesh *bm );
303
304 /*convert between bmesh and Mesh flags*/
305 short BMFlags_To_MEFlags(void *element);
306
307 /*convert between Mesh and bmesh flags
308   type must be BM_VERT/BM_EDGE/BM_FACE,
309   and represents the type of the element
310   parameter (the three defines map to
311   MVert, MEdge, and MPoly, respectively).*/
312 char MEFlags_To_BMFlags(const short hflag, const char htype);
313
314 /*convert MLoop*** in a bmface to mtface and mcol in
315   an MFace*/
316 void BM_loops_to_corners ( BMesh *bm, struct Mesh *me, int findex,
317                            BMFace *f, int numTex, int numCol );
318
319 void BM_Kill_Loop(BMesh *bm, BMLoop *l);
320 void BM_Kill_Face(BMesh *bm, BMFace *f);
321 void BM_Kill_Edge(BMesh *bm, BMEdge *e);
322 void BM_Kill_Vert(BMesh *bm, BMVert *v);
323
324 /*kills all edges associated with f, along with any other faces containing
325   those edges*/
326 void BM_Kill_Face_Edges(BMesh *bm, BMFace *f);
327
328 /*kills all verts associated with f, along with any other faces containing
329   those vertices*/
330 void BM_Kill_Face_Verts(BMesh *bm, BMFace *f) ;
331
332 /*clear all data in bm*/
333 void BM_Clear_Mesh(BMesh *bm);
334
335 void BM_ElemIndex_Ensure(BMesh *bm, const char hflag);
336
337 void BM_ElemIndex_Validate(BMesh *bm, const char *location, const char *func, const char *msg_a, const char *msg_b);
338
339 BMVert *BM_Vert_AtIndex(BMesh *bm, const int index);
340 BMEdge *BM_Edge_AtIndex(BMesh *bm, const int index);
341 BMFace *BM_Face_AtIndex(BMesh *bm, const int index);
342
343 /*start/stop edit*/
344 void bmesh_begin_edit(struct BMesh *bm, int flag);
345 void bmesh_end_edit(struct BMesh *bm, int flag);
346
347
348 #define bm_firstfaceloop(p) ((BMLoopList*)(p->loops.first))->first
349
350 /*include the rest of the API*/
351 #include "bmesh_filters.h"
352 #include "bmesh_iterators.h"
353 #include "bmesh_marking.h"
354 #include "bmesh_operator_api.h"
355 #include "bmesh_operators.h"
356 #include "bmesh_error.h"
357 #include "bmesh_queries.h"
358 #include "bmesh_walkers.h"
359 #include "intern/bmesh_inline.c"
360
361 #ifdef __cplusplus
362 }
363 #endif
364
365 #endif /* BMESH_H */