added Mesh.calc_tessface(), needed to update mesh tessface after bmesh edits.

[blender.git] / doc / python_api / rst / include__bmesh.rst

diff --git a/doc/python_api/rst/include__bmesh.rst b/doc/python_api/rst/include__bmesh.rst
index 2481c4a739cefec1ab8a42d3df3aee24cc33c5ca..24f113e7b50e60faf7384be8d392713e3420b65d 100644 (file)
--- a/doc/python_api/rst/include__bmesh.rst
+++ b/doc/python_api/rst/include__bmesh.rst
@@ -30,10 +30,19 @@ For an overview of BMesh data types and how they reference each other see:
    *Campbell Barton, 13, March 2012*
 
 
-.. todo::
+.. warning::
+
+   TODO Items Are
 
    * add access to BMesh **walkers**
    * add a way to re-tessellate an editmode bmesh.
+   * add deform vert custom-data access.
+
+
+Example Script
+--------------
+
+.. literalinclude:: ../../../release/scripts/templates/bmesh_simple.py
 
 
 Stand-Alone Module
@@ -66,16 +75,74 @@ its good practice to call :class:`bmesh.types.BMesh.free` which will remove all
 further access.
 
 
+EditMode Tessellation
+^^^^^^^^^^^^^^^^^^^^^
+
+When writing scripts that operate on editmode data you will normally want to re-calculate the tessellation after
+running the  script, this needs to be called explicitly.
+
+The BMesh its self does not store the triangulated faces, they are stored in the :class:`bpy.types.Mesh`,
+to refresh tessellation faces call :class:`bpy.types.Mesh.calc_tessface`.
+
+
+CustomData Access
+-----------------
+
+BMesh has a unified way to access mesh attributes such as UV's vertex colors, shape keys, edge crease etc.
+
+This works by having a **layers** property on bmesh data sequences to access the custom data layers which can then be
+used to access the actual data on each vert/edge/face/loop.
+
+Here are some examples ...
+
+.. code-block:: python
+
+   uv_lay = bm.loops.layers.uv.active
+
+   for face in bm.faces:
+       for loop in f.loops:
+           uv = loop[uv_lay]
+           print("Loop UV: %f, %f" % (uv.x, uv.y))
+
+
+.. code-block:: python
+
+   shape_lay = bm.verts.layers.shape["Key.001"]
+
+   for vert in bm.verts:
+               shape = vert[shape_lay]
+        print("Vert Shape: %f, %f, %f" % (shape.x, shape.y, shape.z))
+
+
+.. code-block:: python
+
+   # in this example the active vertex group index is used,
+   # this is stored in the object, not the BMesh
+   group_index = obj.vertex_groups.active_index
+
+   # only ever one deform weight layer
+   dvert_lay = bm.verts.layers.deform.active
+
+   for vert in bm.verts:
+       dvert = vert[dvert_lay]
+               
+       if group_index in dvert:
+           print("Weight %f" % dvert[group_index])
+       else:
+           print("Setting Weight")
+           dvert[group_index] = 0.5
+
+
 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.
+* when an edge is selected, its vertices are selected too.
+* when a face is selected, its edges and vertices are selected.
 * duplicate edges / faces don't exist.
-* faces have at least 3 vertices's.
+* faces have at least 3 vertices.
 
 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.
@@ -92,11 +159,5 @@ As mentioned above, it is possible to create an invalid selection state
 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
 ----------------