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