code cleanup: better use of BLI_array_* (grow in larger steps where possible), includ...
[blender.git] / source / blender / bmesh / intern / bmesh_operator_api.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): Joseph Eagar.
19  *
20  * ***** END GPL LICENSE BLOCK *****
21  */
22
23 #ifndef __BMESH_OPERATOR_API_H__
24 #define __BMESH_OPERATOR_API_H__
25
26 /** \file blender/bmesh/bmesh_operator_api.h
27  *  \ingroup bmesh
28  */
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 #include "BLI_ghash.h"
35
36 #include <stdarg.h>
37
38 /**
39  * operators represent logical, executable mesh modules.  all topological
40  * operations involving a bmesh has to go through them.
41  *
42  * operators are nested, as are tool flags, which are private to an operator
43  * when it's executed.  tool flags are allocated in layers, one per operator
44  * execution, and are used for all internal flagging a tool needs to do.
45  *
46  * each operator has a series of "slots" which can be of the following types:
47  * - simple numerical types
48  * - arrays of elements (e.g. arrays of faces).
49  * - hash mappings.
50  *
51  * each slot is identified by a slot code, as are each operator.
52  * operators, and their slots, are defined in bmesh_opdefines.c (with their
53  * execution functions prototyped in bmesh_operators_private.h), with all their
54  * operator code and slot codes defined in bmesh_operators.h.  see
55  * bmesh_opdefines.c and the BMOpDefine struct for how to define new operators.
56  *
57  * in general, operators are fed arrays of elements, created using either
58  * #BMO_slot_buffer_from_hflag or #BMO_slot_buffer_from_flag
59  * (or through one of the format specifiers in #BMO_op_callf or #BMO_op_initf).
60  *
61  * \note multiple element types (e.g. faces and edges)
62  * can be fed to the same slot array.  Operators act on this data,
63  * and possibly spit out data into output slots.
64  *
65  * \note operators should never read from header flags (e.g. element->head.flag).
66  * For example, if you want an operator to only operate on selected faces, you
67  * should use #BMO_slot_buffer_from_hflag to put the selected elements into a slot.
68  *
69  * \note when you read from an element slot array or mapping, you can either tool-flag
70  * all the elements in it, or read them using an iterator API (which is semantically
71  * similar to the iterator api in bmesh_iterators.h).
72  *
73  * \note only #BMLoop items can't be put into slots as with verts, edges & faces.
74  */
75
76 struct GHashIterator;
77
78 #define BMO_elem_flag_test(     bm, ele, oflag)      _bmo_elem_flag_test     (bm, (ele)->oflags, oflag)
79 #define BMO_elem_flag_test_bool(bm, ele, oflag)      _bmo_elem_flag_test_bool(bm, (ele)->oflags, oflag)
80 #define BMO_elem_flag_enable(   bm, ele, oflag)      _bmo_elem_flag_enable   (bm, (ele)->oflags, oflag)
81 #define BMO_elem_flag_disable(  bm, ele, oflag)      _bmo_elem_flag_disable  (bm, (ele)->oflags, oflag)
82 #define BMO_elem_flag_set(      bm, ele, oflag, val) _bmo_elem_flag_set      (bm, (ele)->oflags, oflag, val)
83 #define BMO_elem_flag_toggle(   bm, ele, oflag)      _bmo_elem_flag_toggle   (bm, (ele)->oflags, oflag)
84
85 BLI_INLINE short _bmo_elem_flag_test(     BMesh *bm, BMFlagLayer *oflags, const short oflag);
86 BLI_INLINE short _bmo_elem_flag_test_bool(BMesh *bm, BMFlagLayer *oflags, const short oflag);
87 BLI_INLINE void  _bmo_elem_flag_enable(   BMesh *bm, BMFlagLayer *oflags, const short oflag);
88 BLI_INLINE void  _bmo_elem_flag_disable(  BMesh *bm, BMFlagLayer *oflags, const short oflag);
89 BLI_INLINE void  _bmo_elem_flag_set(      BMesh *bm, BMFlagLayer *oflags, const short oflag, int val);
90 BLI_INLINE void  _bmo_elem_flag_toggle(   BMesh *bm, BMFlagLayer *oflags, const short oflag);
91
92 /* slot type arrays are terminated by the last member
93  * having a slot type of 0 */
94 enum {
95         BMO_OP_SLOT_SENTINEL = 0,
96         BMO_OP_SLOT_BOOL = 1,
97         BMO_OP_SLOT_INT = 2,
98         BMO_OP_SLOT_FLT = 3,
99
100         /* normally store pointers to object, scene,
101          * _never_ store arrays corresponding to mesh elements with this */
102         BMO_OP_SLOT_PNT = 4,
103         BMO_OP_SLOT_MAT = 5,
104         BMO_OP_SLOT_VEC = 8,
105
106         /* after BMO_OP_SLOT_VEC, everything is dynamically allocated arrays.
107          * We leave a space in the identifiers for future growth.
108          *
109          * it's very important this remain a power of two */
110         BMO_OP_SLOT_ELEMENT_BUF = 9, /* list of verts/edges/faces */
111         BMO_OP_SLOT_MAPPING = 10 /* simple hash map */
112 };
113 #define BMO_OP_SLOT_TOTAL_TYPES 11
114
115 /* please ignore all these structures, don't touch them in tool code, except
116  * for when your defining an operator with BMOpDefine.*/
117
118 typedef struct BMOpSlot {
119         int slottype;
120         int len;
121         int flag;
122         int index; /* index within slot array */
123         union {
124                 int i;
125                 float f;
126                 void *p;
127                 float vec[3];
128                 void *buf;
129                 GHash *ghash;
130         } data;
131 } BMOpSlot;
132
133 #define BMO_OP_MAX_SLOTS 16 /* way more than probably needed */
134
135 #ifdef slots
136 #undef slots
137 #endif
138
139 typedef struct BMOperator {
140         int type;
141         int slottype;
142         int needflag;
143         int flag;
144         struct BMOpSlot slots[BMO_OP_MAX_SLOTS]; void (*exec)(BMesh *bm, struct BMOperator *op);
145         struct MemArena *arena;
146 } BMOperator;
147
148 #define MAX_SLOTNAME    32
149
150 typedef struct BMOSlotType {
151         int type;
152         char name[MAX_SLOTNAME];
153 } BMOSlotType;
154
155 typedef struct BMOpDefine {
156         const char *name;
157         BMOSlotType slottypes[BMO_OP_MAX_SLOTS];
158         void (*exec)(BMesh *bm, BMOperator *op);
159         int flag;
160 } BMOpDefine;
161
162 /* BMOpDefine->flag */
163 #define BMO_OP_FLAG_UNTAN_MULTIRES              1 /*switch from multires tangent space to absolute coordinates*/
164
165 /* ensures consistent normals before operator execution,
166  * restoring the original ones windings/normals afterwards.
167  * keep in mind, this won't work if the input mesh isn't
168  * manifold.*/
169 #define BMO_OP_FLAG_RATIONALIZE_NORMALS 2
170
171 /*------------- Operator API --------------*/
172
173 /* data types that use pointers (arrays, etc) should never
174  * have it set directly.  and never use BMO_slot_ptr_set to
175  * pass in a list of edges or any arrays, really.*/
176
177 void BMO_op_init(BMesh *bm, BMOperator *op, const char *opname);
178
179 /* executes an operator, pushing and popping a new tool flag
180  * layer as appropriate.*/
181 void BMO_op_exec(BMesh *bm, BMOperator *op);
182
183 /* finishes an operator (though note the operator's tool flag is removed
184  * after it finishes executing in BMO_op_exec).*/
185 void BMO_op_finish(BMesh *bm, BMOperator *op);
186
187 /* count the number of elements with the specified flag enabled.
188  * type can be a bitmask of BM_FACE, BM_EDGE, or BM_FACE. */
189 int BMO_mesh_enabled_flag_count(BMesh *bm, const char htype, const short oflag);
190
191 /* count the number of elements with the specified flag disabled.
192  * type can be a bitmask of BM_FACE, BM_EDGE, or BM_FACE. */
193 int BMO_mesh_disabled_flag_count(BMesh *bm, const char htype, const short oflag);
194
195 /*---------formatted operator initialization/execution-----------*/
196 /*
197  * this system is used to execute or initialize an operator,
198  * using a formatted-string system.
199  *
200  * for example, BMO_op_callf(bm, "del geom=%hf context=%i", BM_ELEM_SELECT, DEL_FACES);
201  * . . .will execute the delete operator, feeding in selected faces, deleting them.
202  *
203  * the basic format for the format string is:
204  *   [operatorname] [slotname]=%[code] [slotname]=%[code]
205  *
206  * as in printf, you pass in one additional argument to the function
207  * for every code.
208  *
209  * the formatting codes are:
210  *    %d - put int in slot
211  *    %f - put float in slot
212  *    %p - put pointer in slot
213  *    %h[f/e/v] - put elements with a header flag in slot.
214  *                 the letters after %h define which element types to use,
215  *             so e.g. %hf will do faces, %hfe will do faces and edges,
216  *             %hv will do verts, etc.  must pass in at least one
217  *             element type letter.
218  *    %H[f/e/v] - same as %h, but tests if the flag is disabled
219  *    %f[f/e/v] - same as %h, except it deals with tool flags instead of
220  *                 header flags.
221  *    %F[f/e/v] - same as %f, but tests if the flag is disabled
222  *    %a[f/e/v] - pass all elements (of types specified by f/e/v) to the
223  *                 slot.
224  *    %e        - pass in a single element.
225  *    %v - pointer to a float vector of length 3.
226  *    %m[3/4] - matrix, 3/4 refers to the matrix size, 3 or 4.  the
227  *              corresponding argument must be a pointer to
228  *          a float matrix.
229  *    %s - copy a slot from another op, instead of mapping to one
230  *         argument, it maps to two, a pointer to an operator and
231  *     a slot name.
232  */
233 void BMO_push(BMesh *bm, BMOperator *op);
234 void BMO_pop(BMesh *bm);
235
236 /*executes an operator*/
237 int BMO_op_callf(BMesh *bm, const char *fmt, ...);
238
239 /* initializes, but doesn't execute an operator.  this is so you can
240  * gain access to the outputs of the operator.  note that you have
241  * to execute/finitsh (BMO_op_exec and BMO_op_finish) yourself. */
242 int BMO_op_initf(BMesh *bm, BMOperator *op, const char *fmt, ...);
243
244 /* va_list version, used to implement the above two functions,
245  * plus EDBM_op_callf in bmeshutils.c. */
246 int BMO_op_vinitf(BMesh *bm, BMOperator *op, const char *fmt, va_list vlist);
247
248 /* test whether a named slot exists */
249 int BMO_slot_exists(BMOperator *op, const char *slotname);
250
251 /* get a pointer to a slot.  this may be removed layer on from the public API. */
252 BMOpSlot *BMO_slot_get(BMOperator *op, const char *slotname);
253
254 /* copies the data of a slot from one operator to another.  src and dst are the
255  * source/destination slot codes, respectively. */
256 void BMO_slot_copy(BMOperator *source_op, BMOperator *dest_op,
257                    const char *src, const char *dst);
258
259 /* del "context" slot values, used for operator too */
260 enum {
261         DEL_VERTS = 1,
262         DEL_EDGES,
263         DEL_ONLYFACES,
264         DEL_EDGESFACES,
265         DEL_FACES,
266         DEL_ALL,
267         DEL_ONLYTAGGED
268 };
269
270 void BMO_op_flag_enable(BMesh *bm, BMOperator *op, const int op_flag);
271 void BMO_op_flag_disable(BMesh *bm, BMOperator *op, const int op_flag);
272
273 void  BMO_slot_float_set(BMOperator *op, const char *slotname, const float f);
274 float BMO_slot_float_get(BMOperator *op, const char *slotname);
275 void  BMO_slot_int_set(BMOperator *op, const char *slotname, const int i);
276 int   BMO_slot_int_get(BMOperator *op, const char *slotname);
277 void  BMO_slot_bool_set(BMOperator *op, const char *slotname, const int i);
278 int   BMO_slot_bool_get(BMOperator *op, const char *slotname);
279
280 /* don't pass in arrays that are supposed to map to elements this way.
281  *
282  * so, e.g. passing in list of floats per element in another slot is bad.
283  * passing in, e.g. pointer to an editmesh for the conversion operator is fine
284  * though. */
285 void  BMO_slot_ptr_set(BMOperator *op, const char *slotname, void *p);
286 void *BMO_slot_ptr_get(BMOperator *op, const char *slotname);
287 void  BMO_slot_vec_set(BMOperator *op, const char *slotname, const float vec[3]);
288 void  BMO_slot_vec_get(BMOperator *op, const char *slotname, float r_vec[3]);
289
290 /* only supports square mats */
291 /* size must be 3 or 4; this api is meant only for transformation matrices.
292  * note that internally the matrix is stored in 4x4 form, and it's safe to
293  * call whichever BMO_Get_Mat* function you want. */
294 void BMO_slot_mat_set(BMOperator *op, const char *slotname, const float *mat, int size);
295 void BMO_slot_mat4_get(BMOperator *op, const char *slotname, float r_mat[4][4]);
296 void BMO_slot_mat3_set(BMOperator *op, const char *slotname, float r_mat[3][3]);
297
298 void BMO_mesh_flag_disable_all(BMesh *bm, BMOperator *op, const char htype, const short oflag);
299
300 /* copies the values from another slot to the end of the output slot */
301 void BMO_slot_buffer_append(BMOperator *output_op, const char *output_op_slot,
302                             BMOperator *other_op, const char *other_op_slot);
303
304 /* puts every element of type 'type' (which is a bitmask) with tool
305  * flag 'flag', into a slot. */
306 void BMO_slot_buffer_from_enabled_flag(BMesh *bm, BMOperator *op, const char *slotname,
307                                        const char htype, const short oflag);
308
309 /* puts every element of type 'type' (which is a bitmask) without tool
310  * flag 'flag', into a slot. */
311 void BMO_slot_buffer_from_disabled_flag(BMesh *bm, BMOperator *op, const char *slotname,
312                                         const char htype, const short oflag);
313
314 /* tool-flags all elements inside an element slot array with flag flag. */
315 void BMO_slot_buffer_flag_enable(BMesh *bm, BMOperator *op, const char *slotname,
316                                  const char htype, const short oflag);
317 /* clears tool-flag flag from all elements inside a slot array. */
318 void BMO_slot_buffer_flag_disable(BMesh *bm, BMOperator *op, const char *slotname,
319                                   const char htype, const short oflag);
320
321 /* tool-flags all elements inside an element slot array with flag flag. */
322 void BMO_slot_buffer_hflag_enable(BMesh *bm, BMOperator *op, const char *slotname,
323                                   const char htype, const char hflag, const char do_flush);
324 /* clears tool-flag flag from all elements inside a slot array. */
325 void BMO_slot_buffer_hflag_disable(BMesh *bm, BMOperator *op, const char *slotname,
326                                    const char htype, const char hflag, const char do_flush);
327
328 /* puts every element of type 'type' (which is a bitmask) with header
329  * flag 'flag', into a slot.  note: ignores hidden elements
330  * (e.g. elements with header flag BM_ELEM_HIDDEN set).*/
331 void BMO_slot_buffer_from_enabled_hflag(BMesh *bm, BMOperator *op,
332                                         const char *slotname,
333                                         const char htype, const char hflag);
334
335 /* puts every element of type 'type' (which is a bitmask) without
336  * header flag 'flag', into a slot.  note: ignores hidden elements
337  * (e.g. elements with header flag BM_ELEM_HIDDEN set).*/
338 void BMO_slot_buffer_from_disabled_hflag(BMesh *bm, BMOperator *op,
339                                          const char *slotname,
340                                          const char htype, const char hflag);
341
342 /* counts number of elements inside a slot array. */
343 int BMO_slot_buffer_count(BMesh *bm, BMOperator *op, const char *slotname);
344 int BMO_slot_map_count(BMesh *bm, BMOperator *op, const char *slotname);
345
346 void BMO_slot_map_insert(BMesh *UNUSED(bm), BMOperator *op, const char *slotname,
347                          void *element, void *data, int len);
348
349 /* Counts the number of edges with tool flag toolflag around
350  */
351 int BMO_vert_edge_flags_count(BMesh *bm, BMVert *v, const short oflag);
352
353 /* flags all elements in a mapping.  note that the mapping must only have
354  * bmesh elements in it.*/
355 void BMO_slot_map_to_flag(BMesh *bm, BMOperator *op, const char *slotname,
356                           const char hflag, const short oflag);
357
358 /* this part of the API is used to iterate over element buffer or
359  * mapping slots.
360  *
361  * for example, iterating over the faces in a slot is:
362  *
363  *    BMOIter oiter;
364  *    BMFace *f;
365  *
366  *    f = BMO_iter_new(&oiter, bm, some_operator, "slotname", BM_FACE);
367  *    for (; f; f = BMO_iter_step(&oiter)) {
368  *        /do something with the face
369  *    }
370  *
371  * another example, iterating over a mapping:
372  *    BMOIter oiter;
373  *    void *key;
374  *    void *val;
375  *
376  *    key = BMO_iter_new(&oiter, bm, some_operator, "slotname", 0);
377  *    for (; key; key = BMO_iter_step(&oiter)) {
378  *        val = BMO_iter_map_value(&oiter);
379  *        //do something with the key/val pair
380  *        //note that val is a pointer to the val data,
381  *        //whether it's a float, pointer, whatever.
382  *        //
383  *        // so to get a pointer, for example, use:
384  *        //  *((void**)BMO_iter_map_value(&oiter));
385  *        //or something like that.
386  *    }
387  */
388
389 /* contents of this structure are private,
390  * don't directly access. */
391 typedef struct BMOIter {
392         BMOpSlot *slot;
393         int cur; //for arrays
394         GHashIterator giter;
395         void *val;
396         char restrictmask; /* bitwise '&' with BMHeader.htype */
397 } BMOIter;
398
399 void *BMO_slot_buffer_elem_first(BMOperator *op, const char *slotname);
400
401 void *BMO_iter_new(BMOIter *iter, BMesh *bm, BMOperator *op,
402                    const char *slotname, const char restrictmask);
403 void *BMO_iter_step(BMOIter *iter);
404
405 /* returns a pointer to the key value when iterating over mappings.
406  * remember for pointer maps this will be a pointer to a pointer.*/
407 void *BMO_iter_map_value(BMOIter *iter);
408
409 /* use this for pointer mappings */
410 void *BMO_iter_map_value_p(BMOIter *iter);
411
412 /* use this for float mappings */
413 float BMO_iter_map_value_f(BMOIter *iter);
414
415 #define BMO_ITER(ele, iter, bm, op, slotname, restrict)   \
416         for (ele = BMO_iter_new(iter, bm, op, slotname, restrict); ele; ele = BMO_iter_step(iter))
417
418 /******************* Inlined Functions********************/
419 typedef void (*opexec)(BMesh *bm, BMOperator *op);
420
421 /* mappings map elements to data, which
422  * follows the mapping struct in memory. */
423 typedef struct BMOElemMapping {
424         BMHeader *element;
425         int len;
426 } BMOElemMapping;
427
428 extern const int BMO_OPSLOT_TYPEINFO[BMO_OP_SLOT_TOTAL_TYPES];
429
430 #ifdef __cplusplus
431 }
432 #endif
433
434 #endif /* __BMESH_OPERATOR_API_H__ */