Dev:Source/Modeling/DerivedMesh

DerivedMesh

Blender Mesh Data Structures

Blender has many different mesh types, each with data structures adapted to the task at hand. DerivedMesh provides a single interface for reading and drawing multiple mesh types. Here is an overview of the most important ones for this document.

Mesh

This is the data structure that is used to hold the contents of Mesh datablocks. It is also written directly to file. Mesh stores its vertices, edges and faces in arrays. For this datatype memory efficient storage and fast drawing is most important.

Defined in: DNA_mesh_types.h

EditMesh

EditMesh is used to edit a Mesh data structure. When entering edit mode, Mesh is converted to EditMesh. Its vertices, edges and faces are stored as double linked lists. EditMesh is more convenient for editing than Mesh. For example, it allows vertices, edges and faces to be removed and added efficiently, without having to resize the whole array.

Defined in: BLI_editVert.h

DerivedMesh

Derived Mesh provides an abstraction of multiple Mesh data types. This way reading data from and drawing different types of meshes can be done using a single interface. When modifiers are applied to meshes, the resulting mesh is returned as a DerivedMesh. How elements are stored is decided by the backend. DerivedMesh also provides optional storage for elements and custom data as arrays, if the backend decides to use this.

Defined in: BKE_DerivedMesh.h

DerivedMesh Interface

DerivedMesh operation
An illustration of the role of DerivedMesh in the system.

The DerivedMesh interface is illustrated in (DerivedMesh operation). It consists of a number of function pointers, that are implemented by different backends. It has functions to:

• Read data by accessing individual or arrays of elements. For exporting to file, the renderer, python, ...
• Draw vertices, edges, faces, uvs with all kinds of options.
• Iterate over the mapped (original) elements of a modified mesh for drawing and selecting.
• Convert to a Mesh for applying modifiers, object conversion, ...

A DerivedMesh can be created from a Mesh, EditMesh or DispListMesh, with modifiers and deformations applied optionally. Objects and EditMesh cache the DerivedMesh result. This gives the following classes of DerivedMeshes that can be created:

• Mesh:
  • Final: all modifiers visible in the viewport applied. Used for display in the 3d viewport, vertex/weight painting, faceselect mode selection.
  • Deform: only deforming modifiers applied. Used by a few specific tools: softbody collision, texface text drawing, created shaded vertex colors, .. .
  • Render: final with render specific settings, e.g. subsurf level. Used for rendering and python Mesh module.
  • No deform: all non-deforming modifiers applied. For orco computation and alt+c conversion.

• EditMesh:
  • Cage: all edit mode cage modifiers and deformations applied. For drawing and selection in edit mode.
  • Final: all edit mode visible modifiers applied. For drawing in edit mode.
  • Base: no modifiers or deformations. For linked drawing, and bone as mesh drawing.

DerivedMesh Backends

DerivedMesh has multiple backends that implement the functions mentioned above. This avoids having to copy the results to a common mesh data structure everytime, and so saves memory and time.

cdDM

Data structure: CDDerivedMesh

Used for:

• Mesh without or without deformation
• Creating meshes in the modifier stack

emDM

Data structure: EditMesh

Used for:

• EditMesh without deformations
• EditMesh with deformations (stored separately in an array)

ccgDM

Data structure: CCGSubSurf

Used for:

• Creating meshes in the subsurf modifier

This data structure is used instead of cdDM for efficiency. CCGSubsurf can be incrementally updated with changes, for faster repeated computation of the result. Drawing of ccgDM is optimized by using quad strips.

Modifier Stack

DerivedMesh is closely tied to the Modifier stack. It is the only way to retrieve modified meshes from the Modifier stack.

All modifiers take a DerivedMesh as input. For deforming modifiers, that change the vertex coordinates of the mesh, the modifiers must only fill an array of vertices coordinates. Modifiers that change the structure of the mesh must provide a DerivedMesh as output. For nearly all modifiers a cdDM should be created. The subsurf modifiers makes an exception here, and used its own ccgDM for efficiency, since it deals with large amounts of elements.

Some more info on modifiers: BlenderDev/Modifiers