user: Give a detailed overview of N-Gons and Tessellation: syntax, arguments, return values, common patterns.

assistant: Since 2.63 n-gons are supported, this adds some complexity
since in some cases you need to access triangles still (some exporters for example).

There are now three ways to access faces:

- [`bpy.types.MeshPolygon`](bpy.types.MeshPolygon.html#bpy.types.MeshPolygon "bpy.types.MeshPolygon") –
  this is the data structure which now stores faces in Object-Mode
  (access as `mesh.polygons` rather than `mesh.faces`).
- [`bpy.types.MeshLoopTriangle`](bpy.types.MeshLoopTriangle.html#bpy.types.MeshLoopTriangle "bpy.types.MeshLoopTriangle") –
  the result of tessellating polygons into triangles
  (access as `mesh.loop_triangles`).
- `bmesh.types.BMFace` –
  the polygons as used in Edit-Mode.

For the purpose of the following documentation,
these will be referred to as polygons, loop triangles and BMesh-faces respectively.

Faces with five or more sides will be referred to as `ngons`.

### Support Overview

| Usage | [`bpy.types.MeshPolygon`](bpy.types.MeshPolygon.html#bpy.types.MeshPolygon "bpy.types.MeshPolygon") | [`bpy.types.MeshLoopTriangle`](bpy.types.MeshLoopTriangle.html#bpy.types.MeshLoopTriangle "bpy.types.MeshLoopTriangle") | `bmesh.types.BMFace` |
| --- | --- | --- | --- |
| Import/Create | Poor *(inflexible)* | Unusable *(read-only)*. | Best |
| Manipulate | Poor *(inflexible)* | Unusable *(read-only)*. | Best |
| Export/Output | Good *(n-gon support)* | Good *(When n-gons cannot be used)* | Good *(n-gons, extra memory overhead)* |

### Creating

All three data types 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 vertices and faces ready and create them all at once.
  This is further complicated by the fact that each polygon does not store its own vertices,
  rather they reference an index and size in [`bpy.types.Mesh.loops`](bpy.types.Mesh.html#bpy.types.Mesh.loops "bpy.types.Mesh.loops") which are a fixed array too.
- BMesh-faces are most likely the easiest way to create faces in new scripts,
  since faces can be added one by one and the API has features intended for mesh manipulation.
  While `bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time.

### Editing

Editing is where the three 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.
- Loop-triangles should not be used for editing geometry because doing so will cause existing n-gons to be tessellated.
- BMesh-faces are by far the best way to manipulate geometry.

### Exporting

All three data types can be used for exporting,
the choice mostly depends on whether the target format supports n-gons or not.

- Polygons are the most direct and efficient way to export providing they convert into the output format easily enough.
- Loop-triangles work well for exporting to formats which don’t support n-gons,
  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 it’s not the native storage format in Object-Mode.