diff options
| -rw-r--r-- | CMakeLists.txt | 4 | ||||
| -rw-r--r-- | doc/python_api/rst/include__bmesh.rst | 103 | ||||
| -rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 40 | ||||
| -rw-r--r-- | intern/ghost/GHOST_ISystem.h | 2 | ||||
| -rw-r--r-- | source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c | 2 | ||||
| -rw-r--r-- | source/blender/python/bmesh/bmesh_py_api.c | 5 | ||||
| -rw-r--r-- | source/blender/python/intern/bpy_rna.c | 2 | ||||
| -rw-r--r-- | source/blender/python/mathutils/mathutils_Matrix.c | 2 | ||||
| -rw-r--r-- | source/gameengine/Ketsji/KX_GameObject.cpp | 2 | ||||
| -rw-r--r-- | source/gameengine/Ketsji/KX_GameObject.h | 2 |
10 files changed, 143 insertions, 21 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index 8a13851b8d4..c06567103f0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -124,7 +124,7 @@ mark_as_advanced(WITH_PYTHON) # dont want people disabling this unless they rea mark_as_advanced(WITH_PYTHON_SECURITY) # some distrobutions see this as a security issue, rather than have them patch it, make a build option. option(WITH_PYTHON_SAFETY "Enable internal API error checking to track invalid data to prevent crash on access (at the expense of some effeciency, only enable for development)." OFF) -option(WITH_PYTHON_MODULE "Enable building as a python module (experemental, only enable for development)" OFF) +option(WITH_PYTHON_MODULE "Enable building as a python module (experimental, only enable for development)" OFF) option(WITH_BUILDINFO "Include extra build details (only disable for development & faster builds)" ON) option(WITH_IK_ITASC "Enable ITASC IK solver (only disable for development & for incompatible C++ compilers)" ON) option(WITH_FFTW3 "Enable FFTW3 support (Used for smoke and audio effects)" OFF) @@ -176,7 +176,7 @@ option(WITH_MOD_SMOKE "Enable Smoke Modifier (Smoke Simulation)" ON) option(WITH_MOD_DECIMATE "Enable Decimate Modifier" ON) option(WITH_MOD_BOOLEAN "Enable Boolean Modifier" ON) option(WITH_MOD_REMESH "Enable Remesh Modifier" ON) -option(WITH_MOD_CLOTH_ELTOPO "Enable Experemental cloth solver" OFF) +option(WITH_MOD_CLOTH_ELTOPO "Enable Experimental cloth solver" OFF) mark_as_advanced(WITH_MOD_CLOTH_ELTOPO) option(WITH_MOD_OCEANSIM "Enable Ocean Modifier" OFF) diff --git a/doc/python_api/rst/include__bmesh.rst b/doc/python_api/rst/include__bmesh.rst new file mode 100644 index 00000000000..1c702275f62 --- /dev/null +++ b/doc/python_api/rst/include__bmesh.rst @@ -0,0 +1,103 @@ +.. + This document is appended to the auto generated bmesh api doc to avoid clogging up the C files with details. + to test this run: + ./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py -- --partial bmesh* ; cd doc/python_api ; sphinx-build sphinx-in sphinx-out ; cd ../../ + + +Intro +----- + +This API gives access the blenders internal mesh editing api, featuring geometry connectivity data and +access to editing operations such as split, separate, collapse and dissolve. + +The features exposed closely follow the C API, +giving python access to the functions used by blenders own mesh editing tools. + +For an overview of BMesh data types and how they reference each other see: +`BMesh Design Document <http://wiki.blender.org/index.php/Dev:2.6/Source/Modeling/BMesh/Design>`_ . + + +.. note:: + + **Disk** and **Radial** data is not exposed by the python api since this is for internal use only. + + +.. warning:: + + This API is still in development and experimental, while we don't expect to see large changes, + many areas are not well tested yet and so its possible changes will be made that break scripts. + + *Campbell Barton, 13, March 2012* + + +.. todo:: + + * add access to BMesh **walkers** + * add access selection history (readonly access done) + * add a way to re-tessellate an editmode bmesh. + + +Stand-Alone Module +^^^^^^^^^^^^^^^^^^ + +The bmesh module is written to be standalone except for :mod:`mathutils` +which is used for vertex locations and normals. + +The only other exception to this are when converting mesh data to and from :class:`bpy.types.Mesh`. + + +Mesh Access +----------- + +There are 2 ways to access BMesh data, you can create a new BMesh by converting a mesh from +:class:`bpy.types.BlendData.meshes` or by accessing the current edit mode mesh. +see: :class:`bmesh.types.BMesh.from_mesh` and :mod:`bmesh.from_edit_mesh` respectively. + +When explicitly converting from mesh data python **owns** the data, that is to say - that the mesh only exists while +python holds a reference to it, and the script is responsible for putting it back into a mesh data-block when the edits +are done. + +Note that unlike :mod:`bpy`, a BMesh does not necessarily correspond to data in the currently open blend file, +a BMesh can be created, edited and freed without the user ever seeing or having access to it. +Unlike edit mode, the bmesh module can use multiple BMesh instances at once. + +Take care when dealing with multiple BMesh instances since the mesh data can use a lot of memory, while a mesh that +python owns will be freed in when the script holds no references to it, +its good practice to call :class:`bmesh.types.BMesh.free` which will remove all the mesh data immediately and disable +further access. + + +Keeping a Correct State +----------------------- + +When modeling in blender there are certain assumptions made about the state of the mesh. + +* hidden geometry isn't selected. +* when an edge is selected, its vertices's are selected too. +* when a face is selected, its edges and vertices's are selected. +* duplicate edges / faces don't exist. +* faces have at least 3 vertices's. + +To give developers flexibility these conventions are not enforced, +however tools must leave the mesh in a valid state else other tools may behave incorrectly. + +Any errors that arise from not following these conventions is considered a bug in the script, +not a bug in blender. + + +Selection / Flushing +^^^^^^^^^^^^^^^^^^^^ + +As mentioned above, it is possible to create an invalid selection state +(by selecting a state and then de-selecting one of its vertices's for example), mostly the best way to solve this is to +flush the selection after performing a series of edits. this validates the selection state. + + +Example Script +-------------- + +.. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py + + +Module Functions +---------------- diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index d8407121ae1..49193ad8f22 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -37,6 +37,7 @@ API dump in RST files For quick builds: ./blender.bin -b -P doc/python_api/sphinx_doc_gen.py -- -q + Sphinx: HTML generation ----------------------- After you have built doc/python_api/sphinx-in (see above), @@ -47,6 +48,7 @@ Sphinx: HTML generation This requires sphinx 1.0.7 to be installed. + Sphinx: PDF generation ---------------------- After you have built doc/python_api/sphinx-in (see above), @@ -139,11 +141,11 @@ def handle_args(): help="Rewrite all rst files in sphinx-in/ (default=False)", required=False) - parser.add_argument("-t", "--testdump", - dest="test_dump", - default=False, - action='store_true', - help="Dumps a small part of the API (default=False)", + parser.add_argument("-p", "--partial", + dest="partial", + type=str, + default="", + help="Use a wildcard to only build spesific module(s)", required=False) parser.add_argument("-b", "--bpy", @@ -173,7 +175,7 @@ sphinx-build doc/python_api/sphinx-in doc/python_api/sphinx-out """ # Switch for quick testing so doc-builds don't take so long -if not ARGS.test_dump: +if not ARGS.partial: # full build FILTER_BPY_OPS = None FILTER_BPY_TYPES = None @@ -181,6 +183,7 @@ if not ARGS.test_dump: EXCLUDE_MODULES = () else: + # can manually edit this too: FILTER_BPY_OPS = ("import.scene", ) # allow FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow EXCLUDE_INFO_DOCS = True @@ -195,9 +198,9 @@ else: "bge.types", "bgl", "blf", - #"bmesh", - #"bmesh.types", - #"bmesh.utils", + "bmesh", + "bmesh.types", + "bmesh.utils", "bpy.app", "bpy.app.handlers", "bpy.context", @@ -214,6 +217,22 @@ else: "mathutils.noise", ) + # ------ + # Filter + # + # TODO, support bpy.ops and bpy.types filtering + import fnmatch + m = None + EXCLUDE_MODULES = tuple([m for m in EXCLUDE_MODULES if not fnmatch.fnmatchcase(m, ARGS.partial)]) + del m + del fnmatch + + print("Partial Doc Build, Skipping: %s\n" % "\n ".join(sorted(EXCLUDE_MODULES))) + + # + # done filtering + # -------------- + try: __import__("aud") except ImportError: @@ -1527,6 +1546,9 @@ def copy_handwritten_rsts(basepath): "bge.constraints", "bgl", # "Blender OpenGl wrapper" "gpu", # "GPU Shader Module" + + # includes... + "include__bmesh", ] for mod_name in handwritten_modules: if mod_name not in EXCLUDE_MODULES: diff --git a/intern/ghost/GHOST_ISystem.h b/intern/ghost/GHOST_ISystem.h index be44bbee99a..eeee8c0477b 100644 --- a/intern/ghost/GHOST_ISystem.h +++ b/intern/ghost/GHOST_ISystem.h @@ -82,7 +82,7 @@ class GHOST_IEventConsumer; * <li> OSX Carbon.</li> * <li> Windows.</li> * <li> X11.</li> - * <li> SDL1.3 (experemental).</li> + * <li> SDL1.3 (experimental).</li> * <li> NULL (headless mode).</li> * </ul> * diff --git a/source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c b/source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c index 7b2e682e968..d3c6561ac34 100644 --- a/source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c +++ b/source/blender/nodes/composite/nodes/node_composite_doubleEdgeMask.c @@ -998,7 +998,7 @@ static void do_fillGradientBuffer(unsigned int rw, float *res, unsigned short *g purpose of GO for the proportion calculation. For the purposes of the minimun distance comparisons, we only check - the sums-of-squares against eachother, since they are in the same + the sums-of-squares against each other, since they are in the same mathematical sort-order as if we did go ahead and take square roots Loop through all gradient pixels. diff --git a/source/blender/python/bmesh/bmesh_py_api.c b/source/blender/python/bmesh/bmesh_py_api.c index d3dcc979015..5526926ec8e 100644 --- a/source/blender/python/bmesh/bmesh_py_api.c +++ b/source/blender/python/bmesh/bmesh_py_api.c @@ -108,10 +108,7 @@ PyDoc_STRVAR(BPy_BM_doc, "* :mod:`bmesh.types`\n" "\n" "\n" -"Example Script\n" -"--------------\n" -"\n" -".. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py\n" +".. include:: include__bmesh.rst\n" ); static struct PyModuleDef BPy_BM_module_def = { PyModuleDef_HEAD_INIT, diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c index b543f426751..1af1f8fc9e4 100644 --- a/source/blender/python/intern/bpy_rna.c +++ b/source/blender/python/intern/bpy_rna.c @@ -4524,7 +4524,7 @@ static struct PyMethodDef pyrna_struct_methods[] = { {"type_recast", (PyCFunction)pyrna_struct_type_recast, METH_NOARGS, pyrna_struct_type_recast_doc}, {"__dir__", (PyCFunction)pyrna_struct_dir, METH_NOARGS, NULL}, - /* experemental */ + /* experimental */ {"callback_add", (PyCFunction)pyrna_callback_add, METH_VARARGS, NULL}, {"callback_remove", (PyCFunction)pyrna_callback_remove, METH_VARARGS, NULL}, {NULL, NULL, 0, NULL} diff --git a/source/blender/python/mathutils/mathutils_Matrix.c b/source/blender/python/mathutils/mathutils_Matrix.c index ea329b17013..1d9bda02311 100644 --- a/source/blender/python/mathutils/mathutils_Matrix.c +++ b/source/blender/python/mathutils/mathutils_Matrix.c @@ -780,7 +780,7 @@ PyDoc_STRVAR(C_Matrix_Shear_doc, " :arg size: The size of the shear matrix to construct [2, 4].\n" " :type size: int\n" " :arg factor: The factor of shear to apply. For a 3 or 4 *size* matrix\n" -" pass a pair of floats corrasponding with the *plane* axis.\n" +" pass a pair of floats corresponding with the *plane* axis.\n" " :type factor: float or float pair\n" " :return: A new shear matrix.\n" " :rtype: :class:`Matrix`\n" diff --git a/source/gameengine/Ketsji/KX_GameObject.cpp b/source/gameengine/Ketsji/KX_GameObject.cpp index 5db9958f269..11129248338 100644 --- a/source/gameengine/Ketsji/KX_GameObject.cpp +++ b/source/gameengine/Ketsji/KX_GameObject.cpp @@ -1662,7 +1662,7 @@ PyAttributeDef KX_GameObject::Attributes[] = { KX_PYATTRIBUTE_RO_FUNCTION("attrDict", KX_GameObject, pyattr_get_attrDict), KX_PYATTRIBUTE_RW_FUNCTION("color", KX_GameObject, pyattr_get_obcolor, pyattr_set_obcolor), - /* Experemental, dont rely on these yet */ + /* experimental, don't rely on these yet */ KX_PYATTRIBUTE_RO_FUNCTION("sensors", KX_GameObject, pyattr_get_sensors), KX_PYATTRIBUTE_RO_FUNCTION("controllers", KX_GameObject, pyattr_get_controllers), KX_PYATTRIBUTE_RO_FUNCTION("actuators", KX_GameObject, pyattr_get_actuators), diff --git a/source/gameengine/Ketsji/KX_GameObject.h b/source/gameengine/Ketsji/KX_GameObject.h index cf3aae2bc90..a173ef1ed8f 100644 --- a/source/gameengine/Ketsji/KX_GameObject.h +++ b/source/gameengine/Ketsji/KX_GameObject.h @@ -995,7 +995,7 @@ public: static PyObject* pyattr_get_obcolor(void *selv_v, const KX_PYATTRIBUTE_DEF *attrdef); static int pyattr_set_obcolor(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef, PyObject *value); - /* Experemental! */ + /* Experimental! */ static PyObject* pyattr_get_sensors(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef); static PyObject* pyattr_get_controllers(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef); static PyObject* pyattr_get_actuators(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef); |