forked from bartvdbraak/blender
bmesh py api: more comprehensive intro page, also fix some spelling errors.
This commit is contained in:
Campbell Barton
parent
a69585573e
commit
2fbb5ce833
@ -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)
|
||||
|
||||
|
||||
103
doc/python_api/rst/include__bmesh.rst
Normal file
103
doc/python_api/rst/include__bmesh.rst
Normal file
@ -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
|
||||
----------------
|
||||
@ -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:
|
||||
|
||||
@ -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>
|
||||
*
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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}
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user