Cleanup/Docs: Add comments to Mesh header, rearrange fields

Most of the fields in Mesh had no comments, or outdated misleading
comments. For example, "BMESH ONLY" referred to the BMesh project,
not the data structure. Given how much these structs are used, it should
save a lot of time to have proper comments.

I also rearranged the fields in mesh to have a more logical order. Now
the most important fields come first. In the process I was able to
remove 19 bytes of unnecessary padding (31->12). I just had to
change a `short` flag to `char`.

Differential Revision: https://developer.blender.org/D13454

source/blender/blenkernel/BKE_mesh.h

@@ -229,7 +229,7 @@ void BKE_mesh_texspace_calc(struct Mesh *me);
 void BKE_mesh_texspace_ensure(struct Mesh *me);
 void BKE_mesh_texspace_get(struct Mesh *me, float r_loc[3], float r_size[3]);
 void BKE_mesh_texspace_get_reference(struct Mesh *me,
-                                     short **r_texflag,
+                                     char **r_texflag,
                                      float **r_loc,
                                      float **r_size);
 void BKE_mesh_texspace_copy_from_object(struct Mesh *me, struct Object *ob);

source/blender/blenkernel/BKE_object.h

@@ -507,7 +507,7 @@ void BKE_object_handle_update_ex(struct Depsgraph *depsgraph,
 void BKE_object_sculpt_data_create(struct Object *ob);
 
 bool BKE_object_obdata_texspace_get(struct Object *ob,
-                                    short **r_texflag,
+                                    char **r_texflag,
                                     float **r_loc,
                                     float **r_size);
 

source/blender/blenkernel/intern/mesh.cc

@@ -1246,7 +1246,7 @@ void BKE_mesh_texspace_get(Mesh *me, float r_loc[3], float r_size[3])
   }
 }
 
-void BKE_mesh_texspace_get_reference(Mesh *me, short **r_texflag, float **r_loc, float **r_size)
+void BKE_mesh_texspace_get_reference(Mesh *me, char **r_texflag, float **r_loc, float **r_size)
 {
   BKE_mesh_texspace_ensure(me);
 
@@ -1264,7 +1264,7 @@ void BKE_mesh_texspace_get_reference(Mesh *me, short **r_texflag, float **r_loc,
 void BKE_mesh_texspace_copy_from_object(Mesh *me, Object *ob)
 {
   float *texloc, *texsize;
-  short *texflag;
+  char *texflag;
 
   if (BKE_object_obdata_texspace_get(ob, &texflag, &texloc, &texsize)) {
     me->texflag = *texflag;

source/blender/blenkernel/intern/object.cc

@@ -4454,7 +4454,7 @@ void BKE_object_sculpt_data_create(Object *ob)
   ob->sculpt->mode_type = (eObjectMode)ob->mode;
 }
 
-bool BKE_object_obdata_texspace_get(Object *ob, short **r_texflag, float **r_loc, float **r_size)
+bool BKE_object_obdata_texspace_get(Object *ob, char **r_texflag, float **r_loc, float **r_size)
 {
 
   if (ob->data == nullptr) {

source/blender/editors/transform/transform_convert_object_texspace.c

@@ -51,7 +51,7 @@ void createTransTexspace(TransInfo *t)
   TransData *td;
   Object *ob;
   ID *id;
-  short *texflag;
+  char *texflag;
 
   ob = OBACT(view_layer);
 

source/blender/makesdna/DNA_curve_types.h

@@ -228,9 +228,8 @@ typedef struct Curve {
   /** Creation-time type of curve datablock. */
   short type;
 
-  /** Keep a short because of BKE_object_obdata_texspace_get(). */
-  short texflag;
-  char _pad0[6];
+  char texflag;
+  char _pad0[7];
   short twist_mode;
   float twist_smooth, smallcaps_scale;
 

source/blender/makesdna/DNA_mesh_types.h

@@ -74,7 +74,7 @@ struct MLoopTri_Store {
   int len_alloc;
 };
 
-/* not saved in file! */
+/* Runtime data, not saved in files. */
 typedef struct Mesh_Runtime {
   /* Evaluated mesh for objects which do not have effective modifiers.
    * This mesh is used as a result of modifier stack evaluation.
@@ -82,27 +82,33 @@ typedef struct Mesh_Runtime {
   struct Mesh *mesh_eval;
   void *eval_mutex;
 
+  /** Needed to ensure some thread-safety during render data pre-processing. */
+  void *render_mutex;
+
+  /** Lazily initialized SoA data from the #edit_mesh field in #Mesh. */
   struct EditMeshData *edit_data;
+
+  /**
+   * Data used to efficiently draw the mesh in the viewport, especially useful when
+   * the same mesh is used in many objects or instances. See `draw_cache_impl_mesh.c`.
+   */
   void *batch_cache;
 
-  struct SubdivCCG *subdiv_ccg;
-  void *_pad1;
-  int subdiv_ccg_tot_level;
-  char _pad2[4];
-
-  int64_t cd_dirty_vert;
-  int64_t cd_dirty_edge;
-  int64_t cd_dirty_loop;
-  int64_t cd_dirty_poly;
-
+  /** Cache for derived triangulation of the mesh. */
   struct MLoopTri_Store looptris;
 
-  /** `BVHCache` defined in 'BKE_bvhutil.c' */
+  /** Cache for BVH trees generated for the mesh. Defined in 'BKE_bvhutil.c' */
   struct BVHCache *bvh_cache;
 
-  /** Non-manifold boundary data for Shrinkwrap Target Project. */
+  /** Cache of non-manifold boundary data for Shrinkwrap Target Project. */
   struct ShrinkwrapBoundaryData *shrinkwrap_data;
 
+  /** Needed in case we need to lazily initialize the mesh. */
+  CustomData_MeshMasks cd_mask_extra;
+
+  struct SubdivCCG *subdiv_ccg;
+  int subdiv_ccg_tot_level;
+
   /** Set by modifier stack if only deformed from original. */
   char deformed_only;
   /**
@@ -122,14 +128,15 @@ typedef struct Mesh_Runtime {
    */
   char wrapper_type_finalize;
 
-  char _pad[4];
+  /**
+   * Used to mark when derived data needs to be recalculated for a certain layer.
+   * Currently only normals.
+   */
 
-  /** Needed in case we need to lazily initialize the mesh. */
-  CustomData_MeshMasks cd_mask_extra;
-
-  /** Needed to ensure some thread-safety during render data pre-processing. */
-  void *render_mutex;
-  void *_pad3;
+  int64_t cd_dirty_vert;
+  int64_t cd_dirty_edge;
+  int64_t cd_dirty_loop;
+  int64_t cd_dirty_poly;
 
 } Mesh_Runtime;
 
@@ -141,101 +148,191 @@ typedef struct Mesh {
   /** Old animation system, deprecated for 2.5. */
   struct Ipo *ipo DNA_DEPRECATED;
   struct Key *key;
-  struct Material **mat;
-  struct MSelect *mselect;
-
-  /* BMESH ONLY */
-  /* New face structures. */
-  struct MPoly *mpoly;
-  struct MLoop *mloop;
-  struct MLoopUV *mloopuv;
-  struct MLoopCol *mloopcol;
-  /* END BMESH ONLY */
 
   /**
-   * Legacy face storage (quads & tries only),
-   * faces are now stored in #Mesh.mpoly & #Mesh.mloop arrays.
+   * An array of materials, with length #totcol. These can be overridden by material slots
+   * on #Object. Indices in #MPoly.mat_nr control which material is used for every face.
+   */
+  struct Material **mat;
+
+  /**
+   * Array of vertices. Edges and faces are defined by indices into this array.
+   * \note This pointer is for convenient access to the #CD_MVERT layer in #vdata.
+   */
+  struct MVert *mvert;
+  /**
+   * Array of edges, containing vertex indices. For simple triangle or quad meshes, edges could be
+   * calculated from the #MPoly and #MLoop arrays, however, edges need to be stored explicitly to
+   * edge domain attributes and to support loose edges that aren't connected to faces.
+   * \note This pointer is for convenient access to the #CD_MEDGE layer in #edata.
+   */
+  struct MEdge *medge;
+  /**
+   * Face topology storage of the size and offset of each face's section of the #mloop face corner
+   * array. Also stores various flags and the `material_index` attribute.
+   * \note This pointer is for convenient access to the #CD_MPOLY layer in #pdata.
+   */
+  struct MPoly *mpoly;
+  /**
+   * The vertex and edge index at each face corner.
+   * \note This pointer is for convenient access to the #CD_MLOOP layer in #ldata.
+   */
+  struct MLoop *mloop;
+
+  /** The number of vertices (#MVert) in the mesh, and the size of #vdata. */
+  int totvert;
+  /** The number of edges (#MEdge) in the mesh, and the size of #edata. */
+  int totedge;
+  /** The number of polygons/faces (#MPoly) in the mesh, and the size of #pdata. */
+  int totpoly;
+  /** The number of face corners (#MLoop) in the mesh, and the size of #ldata. */
+  int totloop;
+
+  CustomData vdata, edata, pdata, ldata;
+
+  /** "Vertex group" vertices. */
+  struct MDeformVert *dvert;
+  /**
+   * List of vertex group (#bDeformGroup) names and flags only. Actual weights are stored in dvert.
+   * \note This pointer is for convenient access to the #CD_MDEFORMVERT layer in #vdata.
+   */
+  ListBase vertex_group_names;
+  /** The active index in the #vertex_group_names list. */
+  int vertex_group_active_index;
+
+  /**
+   * The index of the active attribute in the UI. The attribute list is a combination of the
+   * generic type attributes from vertex, edge, face, and corner custom data.
+   */
+  int attributes_active_index;
+
+  /**
+   * 2D vector data used for UVs. "UV" data can also be stored as generic attributes in #ldata.
+   * \note This pointer is for convenient access to the #CD_MLOOPUV layer in #ldata.
+   */
+  struct MLoopUV *mloopuv;
+  /**
+   * The active vertex corner color layer, if it exists. Also called "Vertex Color" in Blender's
+   * UI, even though it is stored per face corner.
+   * \note This pointer is for convenient access to the #CD_MLOOPCOL layer in #ldata.
+   */
+  struct MLoopCol *mloopcol;
+
+  /**
+   * Runtime storage of the edit mode mesh. If it exists, it generally has the most up-to-date
+   * information about the mesh.
+   * \note When the object is available, the preferred access method is #BKE_editmesh_from_object.
+   */
+  struct BMEditMesh *edit_mesh;
+
+  /**
+   * This array represents the selection order when the user manually picks elements in edit-mode,
+   * some tools take advantage of this information. All elements in this array are expected to be
+   * selected, see #BKE_mesh_mselect_validate which ensures this. For procedurally created meshes,
+   * this is generally empty (selections are stored as boolean attributes in the corresponding
+   * custom data).
+   */
+  struct MSelect *mselect;
+
+  /** The length of the #mselect array. */
+  int totselect;
+
+  /**
+   * In most cases the last selected element (see #mselect) represents the active element.
+   * For faces we make an exception and store the active face separately so it can be active
+   * even when no faces are selected. This is done to prevent flickering in the material properties
+   * and UV Editor which base the content they display on the current material which is controlled
+   * by the active face.
    *
-   * \note This would be marked deprecated however the particles still use this at run-time
+   * \note This is mainly stored for use in edit-mode.
+   */
+  int act_face;
+
+  /**
+   * An optional mesh owned elsewhere (by #Main) that can be used to override
+   * the texture space #loc and #size.
+   * \note Vertex indices should be aligned for this to work usefully.
+   */
+  struct Mesh *texcomesh;
+
+  /** Texture space location and size, used for procedural coordinates when rendering. */
+  float loc[3];
+  float size[3];
+  char texflag;
+
+  /** Various flags used when editing the mesh. */
+  char editflag;
+  /** Mostly more flags used when editing or displaying the mesh. */
+  short flag;
+
+  /**
+   * The angle for auto smooth in radians. `M_PI` (180 degrees) causes all edges to be smooth.
+   */
+  float smoothresh;
+
+  /**
+   * Flag for choosing whether or not so store bevel weight and crease as custom data layers in the
+   * edit mesh (they are always stored in #MVert and #MEdge currently). In the future, this data
+   * may be stored as generic named attributes (see T89054 and T93602).
+   */
+  char cd_flag;
+
+  /**
+   * User-defined symmetry flag (#eMeshSymmetryType) that causes editing operations to maintain
+   * symmetrical geometry. Supported by operations such as transform and weight-painting.
+   */
+  char symmetry;
+
+  /** The length of the #mat array. */
+  short totcol;
+
+  /** Choice between different remesh methods in the UI. */
+  char remesh_mode;
+
+  char subdiv DNA_DEPRECATED;
+  char subdivr DNA_DEPRECATED;
+  char subsurftype DNA_DEPRECATED;
+
+  /**
+   * Deprecated. Store of runtime data for tessellation face UVs and texture.
+   *
+   * \note This would be marked deprecated, however the particles still use this at run-time
    * for placing particles on the mesh (something which should be eventually upgraded).
    */
-  struct MFace *mface;
-  /** Store tessellation face UV's and texture here. */
   struct MTFace *mtface;
   /** Deprecated, use mtface. */
   struct TFace *tface DNA_DEPRECATED;
-  /** Array of verts. */
-  struct MVert *mvert;
-  /** Array of edges. */
-  struct MEdge *medge;
-  /** Deform-group vertices. */
-  struct MDeformVert *dvert;
-  /** List of bDeformGroup names and flag only. */
-  ListBase vertex_group_names;
 
-  /* array of colors for the tessellated faces, must be number of tessellated
-   * faces * 4 in length */
+  /* Deprecated. Array of colors for the tessellated faces, must be number of tessellated
+   * faces * 4 in length. This is stored in #fdata, and deprecated. */
   struct MCol *mcol;
-  struct Mesh *texcomesh;
 
-  /* When the object is available, the preferred access method is: BKE_editmesh_from_object(ob) */
-  /** Not saved in file. */
-  struct BMEditMesh *edit_mesh;
-
-  struct CustomData vdata, edata, fdata;
-
-  /* BMESH ONLY */
-  struct CustomData pdata, ldata;
-  /* END BMESH ONLY */
-
-  int totvert, totedge, totface, totselect;
-
-  /* BMESH ONLY */
-  int totpoly, totloop;
-  /* END BMESH ONLY */
-
-  int attributes_active_index;
-  int vertex_group_active_index;
-
-  /* the last selected vertex/edge/face are used for the active face however
-   * this means the active face must always be selected, this is to keep track
-   * of the last selected face and is similar to the old active face flag where
-   * the face does not need to be selected, -1 is inactive */
-  int act_face;
-
-  /* texture space, copied as one block in editobject.c */
-  float loc[3];
-  float size[3];
-
-  short texflag, flag;
-  float smoothresh;
-
-  /* customdata flag, for bevel-weight and crease, which are now optional */
-  char cd_flag, _pad;
-
-  char subdiv DNA_DEPRECATED, subdivr DNA_DEPRECATED;
-  /** Only kept for backwards compat, not used anymore. */
-  char subsurftype DNA_DEPRECATED;
-  char editflag;
-
-  short totcol;
+  /**
+   * Deprecated face storage (quads & triangles only);
+   * faces are now pointed to by #Mesh.mpoly and #Mesh.mloop.
+   *
+   * \note This would be marked deprecated, however the particles still use this at run-time
+   * for placing particles on the mesh (something which should be eventually upgraded).
+   */
+  struct MFace *mface;
+  /* Deprecated storage of old faces (only triangles or quads). */
+  CustomData fdata;
+  /* Deprecated size of #fdata. */
+  int totface;
 
+  /** Per-mesh settings for voxel remesh. */
   float remesh_voxel_size;
   float remesh_voxel_adaptivity;
-  char remesh_mode;
-
-  /* Indicates the symmetry that a mesh has, according to the artist, so that tools can
-   * consistently ensure that this symmetry is maintained. */
-  char symmetry;
-
-  char _pad1[2];
 
   int face_sets_color_seed;
   /* Stores the initial Face Set to be rendered white. This way the overlay can be enabled by
    * default and Face Sets can be used without affecting the color of the mesh. */
   int face_sets_color_default;
 
+  char _pad1[4];
+
   void *_pad2;
+
   Mesh_Runtime runtime;
 } Mesh;
 

source/blender/makesdna/DNA_meshdata_types.h

@@ -106,19 +106,15 @@ enum {
 };
 
 /**
- * Mesh Loops.
- * Each loop represents the corner of a polygon (#MPoly).
+ * Mesh Face Corners.
+ * "Loop" is an internal name for the corner of a polygon (#MPoly).
  *
  * Typically accessed from #Mesh.mloop.
  */
 typedef struct MLoop {
-  /** Vertex index. */
+  /** Vertex index into an #MVert array. */
   unsigned int v;
-  /**
-   * Edge index.
-   *
-   * \note The e here is because we want to move away from relying on edge hashes.
-   */
+  /** Edge index into an #MEdge array. */
   unsigned int e;
 } MLoop;
 
@@ -291,8 +287,22 @@ typedef struct MDeformWeight {
   float weight;
 } MDeformWeight;
 
+/**
+ * Stores all of an element's vertex groups, and their weight values.
+ */
 typedef struct MDeformVert {
+  /**
+   * Array of weight indices and values.
+   * - There must not be any duplicate #def_nr indices.
+   * - Groups in the array are unordered.
+   * - Indices outside the usable range of groups are ignored.
+   */
   struct MDeformWeight *dw;
+  /**
+   * The length of the #dw array.
+   * \note This is not necessarily the same length as the total number of vertex groups.
+   * However, generally it isn't larger.
+   */
   int totweight;
   /** Flag is only in use as a run-time tag at the moment. */
   int flag;

source/blender/makesdna/DNA_meta_types.h

@@ -83,8 +83,8 @@ typedef struct MetaBall {
   char flag, flag2;
   short totcol;
   /** Used to store MB_AUTOSPACE. */
-  short texflag;
-  char _pad[1];
+  char texflag;
+  char _pad[2];
 
   /**
    * ID data is older than edit-mode data (TODO: move to edit-mode struct).