Page MenuHome

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

Authored by Hans Goudey (HooglyBoogly) on Dec 2 2021, 6:19 PM.

Details

Summary

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.

Diff Detail

Repository
rB Blender
Branch
mesh-struct-docs (branched from master)
Build Status
Buildable 19181
Build 19181: arc lint + arc unit

Event Timeline

Hans Goudey (HooglyBoogly) requested review of this revision.Dec 2 2021, 6:19 PM
Hans Goudey (HooglyBoogly) created this revision.
Campbell Barton (campbellbarton) requested changes to this revision.Dec 3 2021, 8:09 AM
Campbell Barton (campbellbarton) added inline comments.
source/blender/makesdna/DNA_mesh_types.h
153

Typo overriden.

154

May as well reference the struct member #MPoly.mat_nr.

160

Reads strangely, could be: \note This for convenient access to the #CD_MVERT layer in #vdata.

... same for similar notes elsewhere in this patch.

164–166

Don't think it's correct to say they are "technically redundant"... in some cases they could be redundant - in the sense that the edges could be calculated based on polys+loops.
If we did not support edges that aren't connected to any faces or edge-flags / edge-custom-data.

Perhaps it could be rephrased that edge data is needed to support edges that aren't connected to faces (wire edges) and edge flags & custom-data.

172

Typo varios.

210

Worth noting this is #CD_MLOOPUV in #ldata.

211

Typo convience (elsewhere in this patch too).

230–232

This paragraph notes that this is often not used for procedural meshes, but doesn't say when they are used (maybe obvious but could be stated explicitly).

Something like this:

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.
241–243

Attempt to make the purpose of this struct-member more clear:

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 set
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 is mainly stored for use in edit-mode.
251–259

Could add: \note Vertex indices should be aligned for this to work usefully.

268–270

Worth mentioning:

... in radians, (M_PI` (180 degrees) causes all edges to be smooth).`

274–275

re: In the future, this data will be stored as built-in attributes anyway.

Prefer to avoid these kinds of comments, unless they're very explicit, occasionally I stumble over historic comments that state something will be changed/rewritten soon - without giving any details.

If there are plans to do this - is there a task ID this can reference?

280–286

This seems a bit vague, For example, parts of the mesh can be asymmetrical.

Attempt to reword this more clearly:

User-defined symmetry flag that cause editing operations to maintain symmetrical geometry.
Supported by operations such as transform and weight-painting.
308–309

Don't think this needs to be a TODO, as far as I can see this needs to be kept for versioning (the text could be updated to say so).

source/blender/makesdna/DNA_meshdata_types.h
110

Why "historical" ?

290

Some additional useful information could be added here (or to dw).

  • Must not be any duplicates.
  • Groups in the array are unordered.
  • Indices outside the usable range of groups are ignored.
302

Worth noting that it typically won't exceed the number vertex groups.

This revision now requires changes to proceed.Dec 3 2021, 8:09 AM
Hans Goudey (HooglyBoogly) marked 17 inline comments as done.
  • Merge branch 'master' into mesh-struct-docs
  • Changes based on review
source/blender/makesdna/DNA_mesh_types.h
164–166

Your phrasing is much better, thanks!

230–232

Much better, thanks. I kept the note about boolean attributes at the end though.

241–243

Thanks, that's better.

274–275

Good point. I made the comment a bit clearer and referenced two tasks, T93602 and T89054

308–309

The TODO referred to the question in the patch description about this struct. But yeah, agreed.

source/blender/makesdna/DNA_meshdata_types.h
110

Well, though the name is used in the code everywhere, we've been using "Face Corner" in the UI more recently, which is a much friendlier term.
Based on conversations I've had with others, these are just called "loops" because that's what was used long ago, not really because it's the most intuitive name.
I can remove it if you'd like though.

290

Great, thanks.

source/blender/makesdna/DNA_meshdata_types.h
110

In that case the distinction is between internal-code and UI terminology not old/new.

Since this is documenting the MLoop struct the "Face Corner" part can be mentioned, however this is already the case in the existing comment.

  • Merge branch 'master' into mesh-struct-docs
  • Remove "historical"
  • Merge branch 'master' into mesh-struct-docs
This revision is now accepted and ready to land.Dec 10 2021, 4:14 AM