Cleanup: mesh data header

This file had become disorganized, it wasn't clear which structs/flags
were deprecated.

- Add comments explaining what each struct is for.
- Use doxy sections.
- Remove outdated notes, unused flags.
- Group custom-data.
- Group deprecated structs in their own section.

T

1 files changed, 320 insertions, 210 deletions

diff --git a/source/blender/makesdna/DNA_meshdata_types.h b/source/blender/makesdna/DNA_meshdata_types.h
index ebaaf72b3ae..57f8cb2b289 100644
--- a/source/blender/makesdna/DNA_meshdata_types.h
+++ b/source/blender/makesdna/DNA_meshdata_types.h
@@ -27,50 +27,67 @@
 #include "DNA_customdata_types.h"
 #include "DNA_listBase.h"
 
-/*tessellation face, see MLoop/MPoly for the real face data*/
-typedef struct MFace {
-  unsigned int v1, v2, v3, v4;
-  short mat_nr;
-  /** We keep edcode, for conversion to edges draw flags in old files. */
-  char edcode, flag;
-} MFace;
-
-typedef struct MEdge {
-  unsigned int v1, v2;
-  char crease, bweight;
-  short flag;
-} MEdge;
-
-typedef struct MDeformWeight {
-  int def_nr;
-  float weight;
-} MDeformWeight;
-
-typedef struct MDeformVert {
-  struct MDeformWeight *dw;
-  int totweight;
-  /** Flag only in use for weightpaint now. */
-  int flag;
-} MDeformVert;
+/* -------------------------------------------------------------------- */
+/** \name Geometry Elements
+ * \{ */
 
+/**
+ * Mesh Vertices.
+ *
+ * Typically accessed from #Mesh.mvert
+ */
 typedef struct MVert {
   float co[3];
+  /**
+   * Cache the normal, can always be recalculated from surrounding faces.
+   * See #CD_CUSTOMLOOPNORMAL for custom normals.
+   */
   short no[3];
   char flag, bweight;
 } MVert;
 
+/** #MVert.flag */
+enum {
+  /*  SELECT = (1 << 0), */
+  ME_VERT_TMP_TAG = (1 << 2),
+  ME_HIDE = (1 << 4),
+  ME_VERT_FACEDOT = (1 << 5),
+  /*  ME_VERT_MERGED = (1 << 6), */
+  ME_VERT_PBVH_UPDATE = (1 << 7),
+};
+
 /**
- * Tessellation vertex color data.
- * at the moment alpha is abused for vertex painting and not used for transparency,
- * note that red and blue are swapped.
+ * Mesh Edges.
+ *
+ * Typically accessed from #Mesh.medge
  */
-typedef struct MCol {
-  unsigned char a, r, g, b;
-} MCol;
+typedef struct MEdge {
+  /** Un-ordered vertex indices (cannot match). */
+  unsigned int v1, v2;
+  char crease, bweight;
+  short flag;
+} MEdge;
 
-/* new face structure, replaces MFace, which is now only used for storing tessellations.*/
+/** #MEdge.flag */
+enum {
+  /*  SELECT = (1 << 0), */
+  ME_EDGEDRAW = (1 << 1),
+  ME_SEAM = (1 << 2),
+  /*  ME_HIDE = (1 << 4), */
+  ME_EDGERENDER = (1 << 5),
+  ME_LOOSEEDGE = (1 << 7),
+  ME_EDGE_TMP_TAG = (1 << 8),
+  ME_SHARP = (1 << 9), /* only reason this flag remains a 'short' */
+};
+
+/**
+ * Mesh Faces
+ * This only stores the polygon size & flags, the vertex & edge indices are stored in the #MLoop.
+ *
+ * Typically accessed from #Mesh.mpoly.
+ */
 typedef struct MPoly {
-  /* offset into loop array and number of loops in the face */
+  /** Offset into loop array and number of loops in the face. */
   int loopstart;
   /** Keep signed since we need to subtract when getting the previous loop. */
   int totloop;
@@ -78,14 +95,62 @@ typedef struct MPoly {
   char flag, _pad;
 } MPoly;
 
-/* the e here is because we want to move away from relying on edge hashes.*/
+/** #MPoly.flag */
+enum {
+  ME_SMOOTH = (1 << 0),
+  ME_FACE_SEL = (1 << 1),
+  /* ME_HIDE = (1 << 4), */
+};
+
+/**
+ * Mesh Loops.
+ * Each loop represents the corner of a polygon (#MPoly).
+ *
+ * Typically accessed from #Mesh.mloop.
+ */
 typedef struct MLoop {
   /** Vertex index. */
   unsigned int v;
-  /** Edge index. */
+  /**
+   * Edge index.
+   *
+   * \note The e here is because we want to move away from relying on edge hashes.
+   */
   unsigned int e;
 } MLoop;
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Ordered Selection Storage
+ * \{ */
+
+/**
+ * Optionally store the order of selected elements.
+ * This wont always be set since only some selection operations have an order.
+ *
+ * Typically accessed from #Mesh.mselect
+ */
+typedef struct MSelect {
+  /** Index in the vertex, edge or polygon array. */
+  int index;
+  /** #ME_VSEL, #ME_ESEL, #ME_FSEL. */
+  int type;
+} MSelect;
+
+/** #MSelect.type */
+enum {
+  ME_VSEL = 0,
+  ME_ESEL = 1,
+  ME_FSEL = 2,
+};
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loop Tesselation Runtime Data
+ * \{ */
+
 /**
  * #MLoopTri's are lightweight triangulation data,
  * for functionality that doesn't support ngons (#MPoly).
@@ -187,12 +252,84 @@ typedef struct MVertTri {
   unsigned int tri[3];
 } MVertTri;
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data (Generic)
+ * \{ */
+
+/** Custom Data Properties */
+typedef struct MFloatProperty {
+  float f;
+} MFloatProperty;
+typedef struct MIntProperty {
+  int i;
+} MIntProperty;
+typedef struct MStringProperty {
+  char s[255], s_len;
+} MStringProperty;
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data (Vertex)
+ * \{ */
+
+/**
+ * Vertex group index and weight for #MDeformVert.dw
+ */
+typedef struct MDeformWeight {
+  /** The index for the vertex group, must *always* be unique when in an array. */
+  int def_nr;
+  /** Weight between 0.0 and 1.0. */
+  float weight;
+} MDeformWeight;
+
+typedef struct MDeformVert {
+  struct MDeformWeight *dw;
+  int totweight;
+  /** Flag is only in use as a run-time tag at the moment. */
+  int flag;
+} MDeformVert;
+
+typedef struct MVertSkin {
+  /**
+   * Radii of the skin, define how big the generated frames are.
+   * Currently only the first two elements are used.
+   */
+  float radius[3];
+
+  /** #eMVertSkinFlag */
+  int flag;
+} MVertSkin;
+
+typedef enum eMVertSkinFlag {
+  /** Marks a vertex as the edge-graph root, used for calculating rotations for all connected
+   * edges (recursively). Also used to choose a root when generating an armature.
+   */
+  MVERT_SKIN_ROOT = 1,
+
+  /** Marks a branch vertex (vertex with more than two connected edges), so that it's neighbors
+   * are directly hulled together, rather than the default of generating intermediate frames.
+   */
+  MVERT_SKIN_LOOSE = 2,
+} eMVertSkinFlag;
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data (Loop)
+ * \{ */
+
+/**
+ * UV coordinate for a polygon face & flag for selection & other options.
+ */
 typedef struct MLoopUV {
   float uv[2];
   int flag;
 } MLoopUV;
 
-/*mloopuv->flag*/
+/** #MLoopUV.flag */
 enum {
   MLOOPUV_EDGESEL = (1 << 0),
   MLOOPUV_VERTSEL = (1 << 1),
@@ -200,17 +337,153 @@ enum {
 };
 
 /**
- * at the moment alpha is abused for vertex painting,
- * otherwise it should _always_ be initialized to 255
- * Mostly its not used for transparency...
- * (except for blender-internal rendering, see [#34096]).
- *
- * \note red and blue are _not_ swapped, as they are with #MCol
+ * \note While alpha is currently is not in the view-port,
+ * this may eventually be added back, keep this value set to 255.
  */
 typedef struct MLoopCol {
   unsigned char r, g, b, a;
 } MLoopCol;
 
+/** Multi-Resolution loop data. */
+typedef struct MDisps {
+  /* Strange bug in SDNA: if disps pointer comes first, it fails to see totdisp */
+  int totdisp;
+  int level;
+  float (*disps)[3];
+
+  /**
+   * Used for hiding parts of a multires mesh.
+   * Essentially the multires equivalent of #MVert.flag's ME_HIDE bit.
+   *
+   * \note This is a bitmap, keep in sync with type used in BLI_bitmap.h
+   */
+  unsigned int *hidden;
+} MDisps;
+
+/** Multi-Resolution grid loop data. */
+typedef struct GridPaintMask {
+  /**
+   * The data array contains `grid_size * grid_size` elements.
+   * Where `grid_size = (1 << (level - 1)) + 1`.
+   */
+  float *data;
+
+  /** The maximum multires level associated with this grid. */
+  unsigned int level;
+
+  char _pad[4];
+} GridPaintMask;
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data (Original Space for Poly, Face)
+ * \{ */
+
+/**
+ * Original space within a face (similar to UV coordinates),
+ * however they are used to determine the original position in a face.
+ *
+ * Unlike UV's these are not user editable and always start out using a fixed 0-1 range.
+ * Currently only used for particle placement.
+ */
+typedef struct OrigSpaceFace {
+  float uv[4][2];
+} OrigSpaceFace;
+
+typedef struct OrigSpaceLoop {
+  float uv[2];
+} OrigSpaceLoop;
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data (FreeStyle for Edge, Face)
+ * \{ */
+
+typedef struct FreestyleEdge {
+  char flag;
+  char _pad[3];
+} FreestyleEdge;
+
+/** #FreestyleEdge.flag */
+enum {
+  FREESTYLE_EDGE_MARK = 1,
+};
+
+typedef struct FreestyleFace {
+  char flag;
+  char _pad[3];
+} FreestyleFace;
+
+/** #FreestyleFace.flag */
+enum {
+  FREESTYLE_FACE_MARK = 1,
+};
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Utility Macros
+ * \{ */
+
+#define ME_POLY_LOOP_PREV(mloop, mp, i) \
+  (&(mloop)[(mp)->loopstart + (((i) + (mp)->totloop - 1) % (mp)->totloop)])
+#define ME_POLY_LOOP_NEXT(mloop, mp, i) (&(mloop)[(mp)->loopstart + (((i) + 1) % (mp)->totloop)])
+
+/** Number of tri's that make up this polygon once tessellated. */
+#define ME_POLY_TRI_TOT(mp) ((mp)->totloop - 2)
+
+/**
+ * Check out-of-bounds material, note that this is nearly always prevented,
+ * yet its still possible in rare cases.
+ * So usage such as array lookup needs to check.
+ */
+#define ME_MAT_NR_TEST(mat_nr, totmat) \
+  (CHECK_TYPE_ANY(mat_nr, short, const short), \
+   CHECK_TYPE_ANY(totmat, short, const short), \
+   (LIKELY(mat_nr < totmat) ? mat_nr : 0))
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Deprecated Structs
+ * \{ */
+
+/**
+ * Used in Blender pre 2.63, See #MLoop, #MPoly for face data stored in the blend file.
+ * Use for reading old files and in a handful of cases which should be removed eventually.
+ */
+typedef struct MFace {
+  unsigned int v1, v2, v3, v4;
+  short mat_nr;
+  /** We keep edcode, for conversion to edges draw flags in old files. */
+  char edcode, flag;
+} MFace;
+
+/** #MFace.edcode */
+enum {
+  ME_V1V2 = (1 << 0),
+  ME_V2V3 = (1 << 1),
+  ME_V3V1 = (1 << 2),
+  ME_V3V4 = ME_V3V1,
+  ME_V4V1 = (1 << 3),
+};
+
+/** Tessellation uv face data. */
+typedef struct MTFace {
+  float uv[4][2];
+} MTFace;
+
+/**
+ * Tessellation vertex color data.
+ *
+ * \note The red and blue are swapped for historical reasons.
+ */
+typedef struct MCol {
+  unsigned char a, r, g, b;
+} MCol;
+
 #define MESH_MLOOPCOL_FROM_MCOL(_mloopcol, _mcol) \
   { \
     MLoopCol *mloopcol__tmp = _mloopcol; \
@@ -233,50 +506,10 @@ typedef struct MLoopCol {
   } \
   (void)0
 
-typedef struct MSelect {
-  int index;
-  /** ME_VSEL/ME_ESEL/ME_FSEL. */
-  int type;
-} MSelect;
-
-/*tessellation uv face data*/
-typedef struct MTFace {
-  float uv[4][2];
-} MTFace;
-
-/*Custom Data Properties*/
-typedef struct MFloatProperty {
-  float f;
-} MFloatProperty;
-typedef struct MIntProperty {
+/** Old game engine recast navigation data, while unused 2.7x files may contain this. */
+typedef struct MRecast {
   int i;
-} MIntProperty;
-typedef struct MStringProperty {
-  char s[255], s_len;
-} MStringProperty;
-
-typedef struct OrigSpaceFace {
-  float uv[4][2];
-} OrigSpaceFace;
-
-typedef struct OrigSpaceLoop {
-  float uv[2];
-} OrigSpaceLoop;
-
-typedef struct MDisps {
-  /* Strange bug in SDNA: if disps pointer comes first, it fails to see totdisp */
-  int totdisp;
-  int level;
-  float (*disps)[3];
-
-  /**
-   * Used for hiding parts of a multires mesh.
-   * Essentially the multires equivalent of MVert.flag's ME_HIDE bit.
-   *
-   * \note This is a bitmap, keep in sync with type used in BLI_bitmap.h
-   */
-  unsigned int *hidden;
-} MDisps;
+} MRecast;
 
 /** Multires structs kept for compatibility with old files. */
 typedef struct MultiresCol {
@@ -326,131 +559,8 @@ typedef struct Multires {
   short *edge_flags;
   char *edge_creases;
 } Multires;
+/* End multi-res structs. */
 
-/* End Multires */
-
-typedef struct MRecast {
-  int i;
-} MRecast;
-
-typedef struct GridPaintMask {
-  /* The data array contains gridsize*gridsize elements */
-  float *data;
-
-  /* The maximum multires level associated with this grid */
-  unsigned int level;
-
-  char _pad[4];
-} GridPaintMask;
-
-typedef enum eMVertSkinFlag {
-  /** Marks a vertex as the edge-graph root, used for calculating rotations for all connected
-   * edges (recursively). Also used to choose a root when generating an armature.
-   */
-  MVERT_SKIN_ROOT = 1,
-
-  /** Marks a branch vertex (vertex with more than two connected edges), so that it's neighbors
-   * are directly hulled together, rather than the default of generating intermediate frames.
-   */
-  MVERT_SKIN_LOOSE = 2,
-} eMVertSkinFlag;
-
-typedef struct MVertSkin {
-  /* Radii of the skin, define how big the generated frames are.
-   * Currently only the first two elements are used. */
-  float radius[3];
-
-  /* eMVertSkinFlag */
-  int flag;
-} MVertSkin;
-
-typedef struct FreestyleEdge {
-  char flag;
-  char _pad[3];
-} FreestyleEdge;
-
-/* FreestyleEdge->flag */
-enum {
-  FREESTYLE_EDGE_MARK = 1,
-};
-
-typedef struct FreestyleFace {
-  char flag;
-  char _pad[3];
-} FreestyleFace;
-
-/* FreestyleFace->flag */
-enum {
-  FREESTYLE_FACE_MARK = 1,
-};
-
-/* mvert->flag */
-enum {
-  /*  SELECT              = (1 << 0), */
-  ME_VERT_TMP_TAG = (1 << 2),
-  ME_HIDE = (1 << 4),
-  ME_VERT_FACEDOT = (1 << 5),
-  /*  ME_VERT_MERGED      = (1 << 6), */
-  ME_VERT_PBVH_UPDATE = (1 << 7),
-};
-
-/* medge->flag */
-enum {
-  /*  SELECT              = (1 << 0), */
-  ME_EDGEDRAW = (1 << 1),
-  ME_SEAM = (1 << 2),
-  /*  ME_HIDE             = (1 << 4), */
-  ME_EDGERENDER = (1 << 5),
-  ME_LOOSEEDGE = (1 << 7),
-  ME_EDGE_TMP_TAG = (1 << 8),
-  ME_SHARP = (1 << 9), /* only reason this flag remains a 'short' */
-};
-
-/* puno = vertexnormal (mface) */
-enum {
-  ME_PROJXY = (1 << 4),
-  ME_PROJXZ = (1 << 5),
-  ME_PROJYZ = (1 << 6),
-};
-
-/* edcode (mface) */
-enum {
-  ME_V1V2 = (1 << 0),
-  ME_V2V3 = (1 << 1),
-  ME_V3V1 = (1 << 2),
-  ME_V3V4 = ME_V3V1,
-  ME_V4V1 = (1 << 3),
-};
-
-/* flag (mface) */
-enum {
-  ME_SMOOTH = (1 << 0),
-  ME_FACE_SEL = (1 << 1),
-  /*  ME_HIDE     = (1 << 4), */
-};
-
-#define ME_POLY_LOOP_PREV(mloop, mp, i) \
-  (&(mloop)[(mp)->loopstart + (((i) + (mp)->totloop - 1) % (mp)->totloop)])
-#define ME_POLY_LOOP_NEXT(mloop, mp, i) (&(mloop)[(mp)->loopstart + (((i) + 1) % (mp)->totloop)])
-
-/* number of tri's that make up this polygon once tessellated */
-#define ME_POLY_TRI_TOT(mp) ((mp)->totloop - 2)
-
-/**
- * Check out-of-bounds material, note that this is nearly always prevented,
- * yet its still possible in rare cases.
- * So usage such as array lookup needs to check.
- */
-#define ME_MAT_NR_TEST(mat_nr, totmat) \
-  (CHECK_TYPE_ANY(mat_nr, short, const short), \
-   CHECK_TYPE_ANY(totmat, short, const short), \
-   (LIKELY(mat_nr < totmat) ? mat_nr : 0))
-
-/* mselect->type */
-enum {
-  ME_VSEL = 0,
-  ME_ESEL = 1,
-  ME_FSEL = 2,
-};
+/** \} */
 
 #endif /* __DNA_MESHDATA_TYPES_H__ */