[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [45094] trunk/blender: rna/ python api change: rename Mesh.faces --> tessfaces, since existing scripts are using this to modify the mesh and its confusing that the edits are not kept .

Campbell Barton ideasman42 at gmail.com
Fri Mar 23 01:28:41 CET 2012


Revision: 45094
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=45094
Author:   campbellbarton
Date:     2012-03-23 00:28:29 +0000 (Fri, 23 Mar 2012)
Log Message:
-----------
rna/python api change: rename Mesh.faces --> tessfaces, since existing scripts are using this to modify the mesh and its confusing that the edits are not kept.

This also makes it clearer that the faces are for tessellated results only.

Added a section on the Gotcha's about upgrading scripts, the pros and cons of MeshTessFace/MeshPoly/BMFace.
and spesifically how to upgrade importers and exporters for 2.63+.

Modified Paths:
--------------
    trunk/blender/doc/python_api/rst/info_gotcha.rst
    trunk/blender/doc/python_api/sphinx_doc_gen.py
    trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py
    trunk/blender/release/scripts/modules/bpy_types.py
    trunk/blender/source/blender/makesrna/RNA_access.h
    trunk/blender/source/blender/makesrna/intern/rna_mesh.c

Modified: trunk/blender/doc/python_api/rst/info_gotcha.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_gotcha.rst	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/doc/python_api/rst/info_gotcha.rst	2012-03-23 00:28:29 UTC (rev 45094)
@@ -132,6 +132,86 @@
 For the time being this limitation just has to be worked around but we're aware its frustrating needs to be addressed.
 
 
+NGons and Tessellation Faces
+============================
+
+Since 2.63 NGons are supported, this adds some complexity since in some cases you need to access triangles still (some exporters for example).
+
+There are now 3 ways to access faces:
+
+* :class:`bpy.types.MeshPolygon` - this is the data stricture which now stores faces in object mode (access as ``mesh.polygons`` rather then ``mesh.faces``).
+* :class:`bpy.types.MeshTessFace` - the result of triangulating (tessellated) polygons, the main method of face access in 2.62 or older.
+* :class:`bmesh.types.BMFace` - the polygons as used in editmode.
+
+For the purpose of the following documentation, these will be referred to as polygons, tessfaces and bmesh-faces respectively.
+
+5+ sided faces will be referred to as ``ngons``.
+
+Support Overview
+----------------
+
++--------------+------------------------------+--------------------------------+--------------------------------+
+|Usage         |:class:`bpy.types.MeshPolygon`|:class:`bpy.types.MeshTessFace` |:class:`bmesh.types.BMFace`     |
++==============+==============================+================================+================================+
+|Import/Create |Bad (inflexible)              |Fine (supported as upgrade path)|Best                            |
++--------------+------------------------------+--------------------------------+--------------------------------+
+|Manipulate    |Bad (inflexible)              |Bad (looses ngons)              |Best                            |
++--------------+------------------------------+--------------------------------+--------------------------------+
+|Export/Output |Good (ngons)                  |Good (When ngons can't be used) |Good (ngons, memory overhead)   |
++--------------+------------------------------+--------------------------------+--------------------------------+
+
+
+Creating
+--------
+
+All 3 datatypes can be used for face creation.
+
+* polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in :class:`bpy.types.Mesh.loops` which in-turn is a fixed array.
+* tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. The obvious limitation is ngons cant be created this way.
+* bmesh-faces are most likely the easiest way for new scripts to create faces, since faces can be added one by one and the api has features intended for mesh manipulation. While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time.
+
+
+Editing
+-------
+
+Editing is where the 3 data types vary most.
+
+* polygons are very limited for editing, changing materials and options like smooth works but for anything else they are too inflexible and are only intended for storage.
+* tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated.
+* bmesh-faces are by far the best way to manipulate geometry.
+
+Exporting
+---------
+
+All 3 data types can be used for exporting, the choice mostly depends on weather the target format supports ngons or not.
+
+* polygons are the most direct & efficient way to export providing they convert into the output format easily enough.
+* tessfaces work well for exporting to formats which dont support ngons, in fact this is the only place where their use is encouraged.
+* bmesh-faces can work for exporting too but may not be necessary if polygons can be used since using bmesh gives some overhead because its not the native storage format in object mode.
+
+
+Upgrading Importers from 2.62
+-----------------------------
+
+Importers can be upgraded to work with only minor changes.
+
+The main change to be made is used the tessellation versions of each function.
+
+* mesh.faces --> :class:`bpy.types.Mesh.tessfaces`
+* mesh.uv_textures --> :class:`bpy.types.Mesh.tessface_uv_textures`
+* mesh.vertex_colors --> :class:`bpy.types.Mesh.tessface_vertex_colors`
+
+Once the data is created call :class:`bpy.types.Mesh.update` to convert the tessfaces into polygons.
+
+
+Upgrading Exporters from 2.62
+-----------------------------
+
+For exporters the most direct way to upgrade is to use tessfaces as with importing however its important to know that tessfaces may **not** exist for a mesh, the array will be empty as if there are no faces.
+
+So before accessing tessface data call: :class:`bmesh.types.BMesh.update` ``(calc_tessface=True)``.
+
+
 EditBones, PoseBones, Bone... Bones
 ===================================
 

Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py	2012-03-23 00:28:29 UTC (rev 45094)
@@ -270,6 +270,9 @@
     import fnmatch
     m = None
     EXCLUDE_MODULES = tuple([m for m in EXCLUDE_MODULES if not fnmatch.fnmatchcase(m, ARGS.partial)])
+
+    EXCLUDE_INFO_DOCS = (not fnmatch.fnmatchcase("info", ARGS.partial))
+
     del m
     del fnmatch
 

Modified: trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/release/scripts/modules/bpy_extras/mesh_utils.py	2012-03-23 00:28:29 UTC (rev 45094)
@@ -127,7 +127,7 @@
     :arg mesh: the mesh used to get edge loops from.
     :type mesh: :class:`bpy.types.Mesh`
     :arg faces: optional face list to only use some of the meshes faces.
-    :type faces: :class:`bpy.types.MeshFaces`, sequence or or NoneType
+    :type faces: :class:`bpy.types.MeshTessFace`, sequence or or NoneType
     :return: return a list of edge vertex index lists.
     :rtype: list
     """
@@ -449,7 +449,7 @@
     :arg num_points: the number of random points to generate on each face.
     :type int:
     :arg faces: list of the faces to generate points on.
-    :type faces: :class:`bpy.types.MeshFaces`, sequence
+    :type faces: :class:`bpy.types.MeshTessFace`, sequence
     :return: list of random points over all faces.
     :rtype: list
     """

Modified: trunk/blender/release/scripts/modules/bpy_types.py
===================================================================
--- trunk/blender/release/scripts/modules/bpy_types.py	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/release/scripts/modules/bpy_types.py	2012-03-23 00:28:29 UTC (rev 45094)
@@ -411,7 +411,7 @@
         return ord_ind(*tuple(self.vertices))
 
 
-class MeshFace(StructRNA):
+class MeshTessFace(StructRNA):
     __slots__ = ()
 
     @property

Modified: trunk/blender/source/blender/makesrna/RNA_access.h
===================================================================
--- trunk/blender/source/blender/makesrna/RNA_access.h	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/source/blender/makesrna/RNA_access.h	2012-03-23 00:28:29 UTC (rev 45094)
@@ -311,8 +311,8 @@
 extern StructRNA RNA_MeshLoopColorLayer;
 extern StructRNA RNA_MeshDeformModifier;
 extern StructRNA RNA_MeshEdge;
-extern StructRNA RNA_MeshFace;
 extern StructRNA RNA_MeshPolygon;
+extern StructRNA RNA_MeshTessFace;
 extern StructRNA RNA_MeshLoop;
 extern StructRNA RNA_MeshFloatProperty;
 extern StructRNA RNA_MeshFloatPropertyLayer;

Modified: trunk/blender/source/blender/makesrna/intern/rna_mesh.c
===================================================================
--- trunk/blender/source/blender/makesrna/intern/rna_mesh.c	2012-03-22 21:33:52 UTC (rev 45093)
+++ trunk/blender/source/blender/makesrna/intern/rna_mesh.c	2012-03-23 00:28:29 UTC (rev 45094)
@@ -225,7 +225,7 @@
 	return mesh_calc_poly_area(mp, me->mloop+mp->loopstart, me->mvert, NULL);
 }
 
-static void rna_MeshFace_normal_get(PointerRNA *ptr, float *values)
+static void rna_MeshTessFace_normal_get(PointerRNA *ptr, float *values)
 {
 	Mesh *me = rna_mesh(ptr);
 	MFace *mface = (MFace*)ptr->data;
@@ -237,7 +237,7 @@
 		normal_tri_v3(values, me->mvert[mface->v1].co, me->mvert[mface->v2].co, me->mvert[mface->v3].co);
 }
 
-static float rna_MeshFace_area_get(PointerRNA *ptr)
+static float rna_MeshTessFace_area_get(PointerRNA *ptr)
 {
 	Mesh *me = rna_mesh(ptr);
 	MFace *mface = (MFace*)ptr->data;
@@ -466,14 +466,6 @@
 		rna_iterator_array_begin(iter, NULL, 0, 0, 0, NULL);
 }
 
-static void rna_MeshFace_material_index_range(PointerRNA *ptr, int *min, int *max)
-{
-	Mesh *me = rna_mesh(ptr);
-	*min = 0;
-	*max = me->totcol-1;
-	*max = MAX2(0, *max);
-}
-
 static int rna_CustomDataLayer_active_get(PointerRNA *ptr, CustomData *data, int type, int render)
 {
 	int n = ((CustomDataLayer*)ptr->data) - data->layers;
@@ -884,7 +876,7 @@
 	return DEG2RADF((float)me->smoothresh);
 }
 
-static int rna_MeshFace_verts_get_length(PointerRNA *ptr, int length[RNA_MAX_ARRAY_DIMENSION])
+static int rna_MeshTessFace_verts_get_length(PointerRNA *ptr, int length[RNA_MAX_ARRAY_DIMENSION])
 {
 	MFace *face = (MFace*)ptr->data;
 
@@ -896,13 +888,13 @@
 	return length[0];
 }
 
-static void rna_MeshFace_verts_get(PointerRNA *ptr, int *values)
+static void rna_MeshTessFace_verts_get(PointerRNA *ptr, int *values)
 {
 	MFace *face = (MFace*)ptr->data;
 	memcpy(values, &face->v1, (face->v4 ? 4 : 3) * sizeof(int));
 }
 
-static void rna_MeshFace_verts_set(PointerRNA *ptr, const int *values)
+static void rna_MeshTessFace_verts_set(PointerRNA *ptr, const int *values)
 {
 	MFace *face = (MFace*)ptr->data;

@@ Diff output truncated at 10240 characters. @@



More information about the Bf-blender-cvs mailing list