This repository has been archived on 2023-10-09. You can view files and clone it, but cannot push or open issues or pull requests.
Files
blender-archive/source/blender/bmesh/bmesh_operator_api.h

542 lines
19 KiB
C++

/*
* ***** BEGIN GPL LICENSE BLOCK *****
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*
* Contributor(s): Joseph Eagar.
*
* ***** END GPL LICENSE BLOCK *****
*/
#ifndef _BMESH_OPERATOR_API_H
#define _BMESH_OPERATOR_API_H
#ifdef __cplusplus
extern "C" {
#endif
#include "BLI_memarena.h"
#include "BLI_ghash.h"
#include "BKE_utildefines.h"
#include <stdarg.h>
#include <string.h> /* for memcpy */
/*
* operators represent logical, executable mesh modules. all topological
* operations involving a bmesh has to go through them.
*
* operators are nested, as are tool flags, which are private to an operator
* when it's executed. tool flags are allocated in layers, one per operator
* execution, and are used for all internal flagging a tool needs to do.
*
* each operator has a series of "slots," which can be of the following types:
* - simple numerical types
* - arrays of elements (e.g. arrays of faces).
* - hash mappings.
*
* each slot is identified by a slot code, as are each operator.
* operators, and their slots, are defined in bmesh_opdefines.c (with their
* execution functions prototyped in bmesh_operators_private.h), with all their
* operator code and slot codes defined in bmesh_operators.h. see
* bmesh_opdefines.c and the BMOpDefine struct for how to define new operators.
*
* in general, operators are fed arrays of elements, created using either
* BM_HeaderFlag_To_Slot or BM_Flag_To_Slot (or through one of the format
* specifyers in BMO_CallOpf or BMO_InitOpf). Note that multiple element
* types (e.g. faces and edges) can be fed to the same slot array. Operators
* act on this data, and possibly spit out data into output slots.
*
* some notes:
* - operators should never read from header flags (e.g. element->head.flag). for
* example, if you want an operator to only operate on selected faces, you
* should use BM_HeaderFlag_To_Slot to put the selected elements into a slot.
* - when you read from an element slot array or mapping, you can either tool-flag
* all the elements in it, or read them using an iterator APi (which is
* semantically similar to the iterator api in bmesh_iterators.h).
*/
struct GHashIterator;
/* slot type arrays are terminated by the last member
* having a slot type of 0.*/
#define BMOP_OPSLOT_SENTINEL 0
#define BMOP_OPSLOT_INT 1
#define BMOP_OPSLOT_FLT 2
#define BMOP_OPSLOT_PNT 3
#define BMOP_OPSLOT_MAT 4
#define BMOP_OPSLOT_VEC 7
/* after BMOP_OPSLOT_VEC, everything is
* dynamically allocated arrays. we
* leave a space in the identifiers
* for future growth.
*/
//it's very important this remain a power of two
#define BMOP_OPSLOT_ELEMENT_BUF 8
#define BMOP_OPSLOT_MAPPING 9
#define BMOP_OPSLOT_TYPES 10
/* please ignore all these structures, don't touch them in tool code, except
* for when your defining an operator with BMOpDefine.*/
typedef struct BMOpSlot{
int slottype;
int len;
int flag;
int index; /* index within slot array */
union {
int i;
float f;
void *p;
float vec[3];
void *buf;
GHash *ghash;
} data;
} BMOpSlot;
#define BMOP_MAX_SLOTS 16 /* way more than probably needed */
#ifdef slots
#undef slots
#endif
typedef struct BMOperator {
int type;
int slottype;
int needflag;
int flag;
struct BMOpSlot slots[BMOP_MAX_SLOTS];
void (*exec)(struct BMesh *bm, struct BMOperator *op);
MemArena *arena;
} BMOperator;
#define MAX_SLOTNAME 32
typedef struct slottype {
int type;
char name[MAX_SLOTNAME];
} slottype;
typedef struct BMOpDefine {
const char *name;
slottype slottypes[BMOP_MAX_SLOTS];
void (*exec)(BMesh *bm, BMOperator *op);
int flag;
} BMOpDefine;
/*BMOpDefine->flag*/
#define BMOP_UNTAN_MULTIRES 1 /*switch from multires tangent space to absolute coordinates*/
/* ensures consistent normals before operator execution,
* restoring the original ones windings/normals afterwards.
* keep in mind, this won't work if the input mesh isn't
* manifold.*/
#define BMOP_RATIONALIZE_NORMALS 2
/*------------- Operator API --------------*/
/* data types that use pointers (arrays, etc) should never
* have it set directly. and never use BMO_Set_Pnt to
* pass in a list of edges or any arrays, really.*/
void BMO_Init_Op(struct BMesh *bm, struct BMOperator *op, const char *opname);
/* executes an operator, pushing and popping a new tool flag
* layer as appropriate.*/
void BMO_Exec_Op(struct BMesh *bm, struct BMOperator *op);
/* finishes an operator (though note the operator's tool flag is removed
* after it finishes executing in BMO_Exec_Op).*/
void BMO_Finish_Op(struct BMesh *bm, struct BMOperator *op);
/* tool flag API. never, ever ever should tool code put junk in
* header flags (element->head.flag), nor should they use
* element->head.eflag1/eflag2. instead, use this api to set
* flags.
*
* if you need to store a value per element, use a
* ghash or a mapping slot to do it. */
/* flags 15 and 16 (1<<14 and 1<<15) are reserved for bmesh api use */
#define BMO_TestFlag(bm, element, flag) (((BMHeader*)(element))->flags[bm->stackdepth-1].f & (flag))
#define BMO_SetFlag(bm, element, flag) (((BMHeader*)(element))->flags[bm->stackdepth-1].f |= (flag))
#define BMO_ClearFlag(bm, element, flag) (((BMHeader*)(element))->flags[bm->stackdepth-1].f &= ~(flag))
#define BMO_ToggleFlag(bm, element, flag) (((BMHeader*)(element))->flags[bm->stackdepth-1].f ^= (flag))
/*profiling showed a significant amount of time spent in BMO_TestFlag
void BMO_SetFlag(struct BMesh *bm, void *element, int flag);
void BMO_ClearFlag(struct BMesh *bm, void *element, int flag);
int BMO_TestFlag(struct BMesh *bm, void *element, int flag);*/
/* count the number of elements with a specific flag.
* type can be a bitmask of BM_FACE, BM_EDGE, or BM_FACE. */
int BMO_CountFlag(struct BMesh *bm, int flag, const char htype);
/*---------formatted operator initialization/execution-----------*/
/*
* this system is used to execute or initialize an operator,
* using a formatted-string system.
*
* for example, BMO_CallOpf(bm, "del geom=%hf context=%d", BM_SELECT, DEL_FACES);
* . . .will execute the delete operator, feeding in selected faces, deleting them.
*
* the basic format for the format string is:
* [operatorname] [slotname]=%[code] [slotname]=%[code]
*
* as in printf, you pass in one additional argument to the function
* for every code.
*
* the formatting codes are:
* %d - put int in slot
* %f - put float in slot
* %p - put pointer in slot
* %h[f/e/v] - put elements with a header flag in slot.
* the letters after %h define which element types to use,
* so e.g. %hf will do faces, %hfe will do faces and edges,
* %hv will do verts, etc. must pass in at least one
* element type letter.
* %f[f/e/v] - same as %h, except it deals with tool flags instead of
* header flags.
* %a[f/e/v] - pass all elements (of types specified by f/e/v) to the
* slot.
* %e - pass in a single element.
* %v - pointer to a float vector of length 3.
* %m[3/4] - matrix, 3/4 refers to the matrix size, 3 or 4. the
* corrusponding argument must be a pointer to
* a float matrix.
* %s - copy a slot from another op, instead of mapping to one
* argument, it maps to two, a pointer to an operator and
* a slot name.
*/
void BMO_push(BMesh *bm, BMOperator *op);
void BMO_pop(BMesh *bm);
/*executes an operator*/
int BMO_CallOpf(BMesh *bm, const char *fmt, ...);
/* initializes, but doesn't execute an operator. this is so you can
* gain access to the outputs of the operator. note that you have
* to execute/finitsh (BMO_Exec_Op and BMO_Finish_Op) yourself. */
int BMO_InitOpf(BMesh *bm, BMOperator *op, const char *fmt, ...);
/* va_list version, used to implement the above two functions,
* plus EDBM_CallOpf in bmeshutils.c. */
int BMO_VInitOpf(BMesh *bm, BMOperator *op, const char *fmt, va_list vlist);
/* test whether a named slot exists */
int BMO_HasSlot(struct BMOperator *op, const char *slotname);
/* get a pointer to a slot. this may be removed layer on from the public API. */
BMOpSlot *BMO_GetSlot(struct BMOperator *op, const char *slotname);
/* copies the data of a slot from one operator to another. src and dst are the
* source/destination slot codes, respectively. */
void BMO_CopySlot(struct BMOperator *source_op, struct BMOperator *dest_op,
const char *src, const char *dst);
/*remove tool flagged elements*/
void BM_remove_tagged_faces(struct BMesh *bm, int flag);
void BM_remove_tagged_edges(struct BMesh *bm, int flag);
void BM_remove_tagged_verts(struct BMesh *bm, int flag);
void BMO_Set_OpFlag(struct BMesh *bm, struct BMOperator *op, int flag);
void BMO_Clear_OpFlag(struct BMesh *bm, struct BMOperator *op, int flag);
void BMO_Set_Float(struct BMOperator *op, const char *slotname, float f);
float BMO_Get_Float(BMOperator *op, const char *slotname);
void BMO_Set_Int(struct BMOperator *op, const char *slotname, int i);
int BMO_Get_Int(BMOperator *op, const char *slotname);
/* don't pass in arrays that are supposed to map to elements this way.
*
* so, e.g. passing in list of floats per element in another slot is bad.
* passing in, e.g. pointer to an editmesh for the conversion operator is fine
* though. */
void BMO_Set_Pnt(struct BMOperator *op, const char *slotname, void *p);
void *BMO_Get_Pnt(BMOperator *op, const char *slotname);
void BMO_Set_Vec(struct BMOperator *op, const char *slotname, const float vec[3]);
void BMO_Get_Vec(BMOperator *op, const char *slotname, float r_vec[3]);
/* only supports square mats */
/* size must be 3 or 4; this api is meant only for transformation matrices.
* note that internally the matrix is stored in 4x4 form, and it's safe to
* call whichever BMO_Get_Mat* function you want. */
void BMO_Set_Mat(struct BMOperator *op, const char *slotname, float *mat, int size);
void BMO_Get_Mat4(struct BMOperator *op, const char *slotname, float mat[4][4]);
void BMO_Get_Mat3(struct BMOperator *op, const char *slotname, float mat[3][3]);
void BMO_Clear_Flag_All(BMesh *bm, BMOperator *op, const char htype, int flag);
/* puts every element of type type (which is a bitmask) with tool flag flag,
* into a slot. */
void BMO_Flag_To_Slot(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const int flag, const char htype);
/* tool-flags all elements inside an element slot array with flag flag. */
void BMO_Flag_Buffer(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const int hflag, const char htype);
/* clears tool-flag flag from all elements inside a slot array. */
void BMO_Unflag_Buffer(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const int flag, const char htype);
/* tool-flags all elements inside an element slot array with flag flag. */
void BMO_HeaderFlag_Buffer(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const char hflag, const char htype);
/* clears tool-flag flag from all elements inside a slot array. */
void BMO_UnHeaderFlag_Buffer(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const char hflag, const char htype);
/* puts every element of type type (which is a bitmask) with header flag
* flag, into a slot. note: ignores hidden elements (e.g. elements with
* header flag BM_HIDDEN set).*/
void BMO_HeaderFlag_To_Slot(struct BMesh *bm, struct BMOperator *op, const char *slotname,
const char hflag, const char htype);
/* counts number of elements inside a slot array. */
int BMO_CountSlotBuf(struct BMesh *bm, struct BMOperator *op, const char *slotname);
int BMO_CountSlotMap(struct BMesh *bm, struct BMOperator *op, const char *slotname);
/* Counts the number of edges with tool flag toolflag around
*/
int BMO_Vert_CountEdgeFlags(BMesh *bm, BMVert *v, int toolflag);
/* inserts a key/value mapping into a mapping slot. note that it copies the
* value, it doesn't store a reference to it. */
//BM_INLINE void BMO_Insert_Mapping(BMesh *bm, BMOperator *op, const char *slotname,
//void *element, void *data, int len);
/* inserts a key/float mapping pair into a mapping slot. */
//BM_INLINE void BMO_Insert_MapFloat(BMesh *bm, BMOperator *op, const char *slotname,
//void *element, float val);
//returns 1 if the specified pointer is in the map.
//BM_INLINE int BMO_InMap(BMesh *bm, BMOperator *op, const char *slotname, void *element);
/* returns a point to the value of a specific key. */
//BM_INLINE void *BMO_Get_MapData(BMesh *bm, BMOperator *op, const char *slotname, void *element);
/* returns the float part of a key/float pair. */
//BM_INLINE float BMO_Get_MapFloat(BMesh *bm, BMOperator *op, const char *slotname, void *element);
/* flags all elements in a mapping. note that the mapping must only have
* bmesh elements in it.*/
void BMO_Mapping_To_Flag(struct BMesh *bm, struct BMOperator *op,
const char *slotname, int flag);
/* pointer versoins of BMO_Get_MapFloat and BMO_Insert_MapFloat.
*
* do NOT use these for non-operator-api-allocated memory! instead
* use BMO_Get_MapData and BMO_Insert_Mapping, which copies the data. */
//BM_INLINE void BMO_Insert_MapPointer(BMesh *bm, BMOperator *op, const char *slotname,
//void *key, void *val);
//BM_INLINE void *BMO_Get_MapPointer(BMesh *bm, BMOperator *op, const char *slotname,
//void *key);
/* this part of the API is used to iterate over element buffer or
* mapping slots.
*
* for example, iterating over the faces in a slot is:
*
* BMOIter oiter;
* BMFace *f;
*
* f = BMO_IterNew(&oiter, bm, some_operator, "slotname", BM_FACE);
* for (; f; f=BMO_IterStep(&oiter)) {
* /do something with the face
* }
*
* another example, iterating over a mapping:
* BMOIter oiter;
* void *key;
* void *val;
*
* key = BMO_IterNew(&oiter, bm, some_operator, "slotname", 0);
* for (; key; key=BMO_IterStep(&oiter)) {
* val = BMO_IterMapVal(&oiter);
* //do something with the key/val pair
* //note that val is a pointer to the val data,
* //whether it's a float, pointer, whatever.
* //
* // so to get a pointer, for example, use:
* // *((void**)BMO_IterMapVal(&oiter));
* //or something like that.
* }
*/
/* contents of this structure are private,
* don't directly access. */
typedef struct BMOIter {
BMOpSlot *slot;
int cur; //for arrays
struct GHashIterator giter;
void *val;
char restrictmask; /* bitwise '&' with BMHeader.htype */
} BMOIter;
void *BMO_FirstElem(BMOperator *op, const char *slotname);
/* restrictmask restricts the iteration to certain element types
* (e.g. combination of BM_VERT, BM_EDGE, BM_FACE), if iterating
* over an element buffer (not a mapping).*/
void *BMO_IterNew(BMOIter *iter, BMesh *bm, BMOperator *op,
const char *slotname, const char restrictmask);
void *BMO_IterStep(BMOIter *iter);
/* returns a pointer to the key value when iterating over mappings.
* remember for pointer maps this will be a pointer to a pointer.*/
void *BMO_IterMapVal(BMOIter *iter);
/* use this for pointer mappings */
void *BMO_IterMapValp(BMOIter *iter);
/* use this for float mappings */
float BMO_IterMapValf(BMOIter *iter);
#define BMO_ITER(ele, iter, bm, op, slotname, restrict) \
ele = BMO_IterNew(iter, bm, op, slotname, restrict); \
for ( ; ele; ele=BMO_IterStep(iter))
/******************* Inlined Functions********************/
typedef void (*opexec)(struct BMesh *bm, struct BMOperator *op);
/* mappings map elements to data, which
* follows the mapping struct in memory. */
typedef struct element_mapping {
BMHeader *element;
int len;
} element_mapping;
extern const int BMOP_OPSLOT_TYPEINFO[];
BM_INLINE void BMO_Insert_Mapping(BMesh *UNUSED(bm), BMOperator *op, const char *slotname,
void *element, void *data, int len) {
element_mapping *mapping;
BMOpSlot *slot = BMO_GetSlot(op, slotname);
/*sanity check*/
if (slot->slottype != BMOP_OPSLOT_MAPPING) return;
mapping = (element_mapping*) BLI_memarena_alloc(op->arena, sizeof(*mapping) + len);
mapping->element = (BMHeader*) element;
mapping->len = len;
memcpy(mapping+1, data, len);
if (!slot->data.ghash) {
slot->data.ghash = BLI_ghash_new(BLI_ghashutil_ptrhash,
BLI_ghashutil_ptrcmp, "bmesh op");
}
BLI_ghash_insert(slot->data.ghash, element, mapping);
}
BM_INLINE void BMO_Insert_MapInt(BMesh *bm, BMOperator *op, const char *slotname,
void *element, int val)
{
BMO_Insert_Mapping(bm, op, slotname, element, &val, sizeof(int));
}
BM_INLINE void BMO_Insert_MapFloat(BMesh *bm, BMOperator *op, const char *slotname,
void *element, float val)
{
BMO_Insert_Mapping(bm, op, slotname, element, &val, sizeof(float));
}
BM_INLINE void BMO_Insert_MapPointer(BMesh *bm, BMOperator *op, const char *slotname,
void *element, void *val)
{
BMO_Insert_Mapping(bm, op, slotname, element, &val, sizeof(void*));
}
BM_INLINE int BMO_InMap(BMesh *UNUSED(bm), BMOperator *op, const char *slotname, void *element)
{
BMOpSlot *slot = BMO_GetSlot(op, slotname);
/*sanity check*/
if (slot->slottype != BMOP_OPSLOT_MAPPING) return 0;
if (!slot->data.ghash) return 0;
return BLI_ghash_haskey(slot->data.ghash, element);
}
BM_INLINE void *BMO_Get_MapData(BMesh *UNUSED(bm), BMOperator *op, const char *slotname,
void *element)
{
element_mapping *mapping;
BMOpSlot *slot = BMO_GetSlot(op, slotname);
/*sanity check*/
if (slot->slottype != BMOP_OPSLOT_MAPPING) return NULL;
if (!slot->data.ghash) return NULL;
mapping = (element_mapping*) BLI_ghash_lookup(slot->data.ghash, element);
if (!mapping) return NULL;
return mapping + 1;
}
BM_INLINE float BMO_Get_MapFloat(BMesh *bm, BMOperator *op, const char *slotname,
void *element)
{
float *val = (float*) BMO_Get_MapData(bm, op, slotname, element);
if (val) return *val;
return 0.0f;
}
BM_INLINE int BMO_Get_MapInt(BMesh *bm, BMOperator *op, const char *slotname,
void *element)
{
int *val = (int*) BMO_Get_MapData(bm, op, slotname, element);
if (val) return *val;
return 0;
}
BM_INLINE void *BMO_Get_MapPointer(BMesh *bm, BMOperator *op, const char *slotname,
void *element)
{
void **val = (void**) BMO_Get_MapData(bm, op, slotname, element);
if (val) return *val;
return NULL;
}
BM_INLINE void BMO_SetIndex(BMesh *bm, const void *element, int index)
{
BMHeader *header = (BMHeader *)element;
header->flags[bm->stackdepth-1].index = index;
}
BM_INLINE int BMO_GetIndex(BMesh *bm, void *element)
{
BMHeader *header = (BMHeader *)element;
return header->flags[bm->stackdepth-1].index;
}
#ifdef __cplusplus
}
#endif
#endif /* _BMESH_OPERATOR_API_H */