Cleanup: python doc-strings
[blender.git] / source / blender / python / bmesh / bmesh_py_api.c
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  * The Original Code is Copyright (C) 2012 Blender Foundation.
19  * All rights reserved.
20  *
21  * Contributor(s): Campbell Barton
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  */
25
26 /** \file blender/python/bmesh/bmesh_py_api.c
27  *  \ingroup pybmesh
28  *
29  * This file defines the 'bmesh' module.
30  */
31
32 #include <Python.h>
33
34 #include "BLI_utildefines.h"
35
36 #include "bmesh.h"
37
38 #include "bmesh_py_types.h"
39 #include "bmesh_py_types_select.h"
40 #include "bmesh_py_types_customdata.h"
41 #include "bmesh_py_types_meshdata.h"
42
43 #include "bmesh_py_ops.h"
44 #include "bmesh_py_utils.h"
45 #include "bmesh_py_geometry.h"
46
47 #include "BKE_editmesh.h"
48
49 #include "DNA_mesh_types.h"
50
51 #include "../generic/py_capi_utils.h"
52
53 #include "bmesh_py_api.h" /* own include */
54
55 PyDoc_STRVAR(bpy_bm_new_doc,
56 ".. method:: new(use_operators=True)\n"
57 "\n"
58 "   :arg use_operators: Support calling operators in :mod:`bmesh.ops` (uses some extra memory per vert/edge/face).\n"
59 "   :type use_operators: bool\n"
60 "   :return: Return a new, empty BMesh.\n"
61 "   :rtype: :class:`bmesh.types.BMesh`\n"
62 );
63
64 static PyObject *bpy_bm_new(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
65 {
66         static const char *kwlist[] = {"use_operators", NULL};
67         BMesh *bm;
68
69         bool use_operators = true;
70
71         if (!PyArg_ParseTupleAndKeywords(
72                 args, kw, "|$O&:new", (char **)kwlist,
73                 PyC_ParseBool, &use_operators))
74         {
75                 return NULL;
76         }
77
78         bm = BM_mesh_create(
79                 &bm_mesh_allocsize_default,
80                 &((struct BMeshCreateParams){.use_toolflags = use_operators,}));
81
82         return BPy_BMesh_CreatePyObject(bm, BPY_BMFLAG_NOP);
83 }
84
85 PyDoc_STRVAR(bpy_bm_from_edit_mesh_doc,
86 ".. method:: from_edit_mesh(mesh)\n"
87 "\n"
88 "   Return a BMesh from this mesh, currently the mesh must already be in editmode.\n"
89 "\n"
90 "   :arg mesh: The editmode mesh.\n"
91 "   :type mesh: :class:`bpy.types.Mesh`\n"
92 "   :return: the BMesh associated with this mesh.\n"
93 "   :rtype: :class:`bmesh.types.BMesh`\n"
94 );
95 static PyObject *bpy_bm_from_edit_mesh(PyObject *UNUSED(self), PyObject *value)
96 {
97         BMesh *bm;
98         Mesh *me = PyC_RNA_AsPointer(value, "Mesh");
99
100         if (me == NULL) {
101                 return NULL;
102         }
103
104         if (me->edit_btmesh == NULL) {
105                 PyErr_SetString(PyExc_ValueError,
106                                 "The mesh must be in editmode");
107                 return NULL;
108         }
109
110         bm = me->edit_btmesh->bm;
111
112         return BPy_BMesh_CreatePyObject(bm, BPY_BMFLAG_IS_WRAPPED);
113 }
114
115 PyDoc_STRVAR(bpy_bm_update_edit_mesh_doc,
116 ".. method:: update_edit_mesh(mesh, loop_triangles=True, destructive=True)\n"
117 "\n"
118 "   Update the mesh after changes to the BMesh in editmode,\n"
119 "   optionally recalculating n-gon tessellation.\n"
120 "\n"
121 "   :arg mesh: The editmode mesh.\n"
122 "   :type mesh: :class:`bpy.types.Mesh`\n"
123 "   :arg loop_triangles: Option to recalculate n-gon tessellation.\n"
124 "   :type loop_triangles: boolean\n"
125 "   :arg destructive: Use when geometry has been added or removed.\n"
126 "   :type destructive: boolean\n"
127 );
128 static PyObject *bpy_bm_update_edit_mesh(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
129 {
130         static const char *kwlist[] = {"mesh", "loop_triangles", "destructive", NULL};
131         PyObject *py_me;
132         Mesh *me;
133         bool do_loop_triangles = true;
134         bool is_destructive = true;
135
136         if (!PyArg_ParseTupleAndKeywords(
137                 args, kw, "O|O&O&:update_edit_mesh", (char **)kwlist,
138                 &py_me,
139                 PyC_ParseBool, &do_loop_triangles,
140                 PyC_ParseBool, &is_destructive))
141         {
142                 return NULL;
143         }
144
145         me = PyC_RNA_AsPointer(py_me, "Mesh");
146
147         if (me == NULL) {
148                 return NULL;
149         }
150
151         if (me->edit_btmesh == NULL) {
152                 PyErr_SetString(PyExc_ValueError,
153                                 "The mesh must be in editmode");
154                 return NULL;
155         }
156
157         {
158                 extern void EDBM_update_generic(BMEditMesh *em, const bool do_tessface, const bool is_destructive);
159
160                 EDBM_update_generic(me->edit_btmesh, do_loop_triangles, is_destructive);
161         }
162
163         Py_RETURN_NONE;
164 }
165
166 static struct PyMethodDef BPy_BM_methods[] = {
167         {"new",            (PyCFunction)bpy_bm_new,            METH_VARARGS | METH_KEYWORDS,  bpy_bm_new_doc},
168         {"from_edit_mesh", (PyCFunction)bpy_bm_from_edit_mesh, METH_O,       bpy_bm_from_edit_mesh_doc},
169         {"update_edit_mesh", (PyCFunction)bpy_bm_update_edit_mesh, METH_VARARGS | METH_KEYWORDS, bpy_bm_update_edit_mesh_doc},
170         {NULL, NULL, 0, NULL}
171 };
172
173 PyDoc_STRVAR(BPy_BM_doc,
174 "This module provides access to blenders bmesh data structures.\n"
175 "\n"
176 ".. include:: include__bmesh.rst\n"
177 );
178 static struct PyModuleDef BPy_BM_module_def = {
179         PyModuleDef_HEAD_INIT,
180         "bmesh",  /* m_name */
181         BPy_BM_doc,  /* m_doc */
182         0,  /* m_size */
183         BPy_BM_methods,  /* m_methods */
184         NULL,  /* m_reload */
185         NULL,  /* m_traverse */
186         NULL,  /* m_clear */
187         NULL,  /* m_free */
188 };
189
190 PyObject *BPyInit_bmesh(void)
191 {
192         PyObject *mod;
193         PyObject *submodule;
194         PyObject *sys_modules = PyImport_GetModuleDict();
195
196         BPy_BM_init_types();
197         BPy_BM_init_types_select();
198         BPy_BM_init_types_customdata();
199         BPy_BM_init_types_meshdata();
200
201         mod = PyModule_Create(&BPy_BM_module_def);
202
203         /* bmesh.types */
204         PyModule_AddObject(mod, "types", (submodule = BPyInit_bmesh_types()));
205         PyDict_SetItem(sys_modules, PyModule_GetNameObject(submodule), submodule);
206
207         /* bmesh.ops (not a real module, exposes module like access). */
208         PyModule_AddObject(mod, "ops", (submodule = BPyInit_bmesh_ops()));
209         /* PyDict_SetItemString(sys_modules, PyModule_GetNameObject(submodule), submodule); */
210         PyDict_SetItemString(sys_modules, "bmesh.ops", submodule); /* fake module */
211
212         PyModule_AddObject(mod, "utils", (submodule = BPyInit_bmesh_utils()));
213         PyDict_SetItem(sys_modules, PyModule_GetNameObject(submodule), submodule);
214
215         PyModule_AddObject(mod, "geometry", (submodule = BPyInit_bmesh_geometry()));
216         PyDict_SetItem(sys_modules, PyModule_GetNameObject(submodule), submodule);
217
218         return mod;
219 }