Improve Mesh documentation#9061
Conversation
Selene-Amanita
added
C-Docs
IceSentry
left a comment
IceSentry
left a comment
There was a problem hiding this comment.
Couple of nits. Personally, this feels like it's touching a bit too many things, like I'm not sure the AssetServer or StandardMaterial should really be mentioned here but this really isn't targeted at someone like me so I'm not sure what the best solution is.
| /// | ||
| /// ## Common points of confusion | ||
| /// | ||
| /// - UV maps in Bevy are "flipped", `[0.0, 0.0]` = Top-Left (not Bot-Left like `OpenGL`). |
There was a problem hiding this comment.
It's only flipped compared to OpenGL, to me this implies bevy is doing something non-standard here. As far as I know, top-left is part of the gltf spec
In other words, I agree it's worth pointing out, but it should be clearer that it's flipped compared to opengl.
Something like
| /// - UV maps in Bevy are "flipped", `[0.0, 0.0]` = Top-Left (not Bot-Left like `OpenGL`). | |
| /// - UV maps in bevy start at the top-left unlike opengl which starts at the bottom-left |
| /// ## Common points of confusion | ||
| /// | ||
| /// - UV maps in Bevy are "flipped", `[0.0, 0.0]` = Top-Left (not Bot-Left like `OpenGL`). | ||
| /// - It is normal for multiple vertices to have the same [position attribute](Mesh::ATTRIBUTE_POSITION) value, |
There was a problem hiding this comment.
Maybe try to rephrase this to not use the word normal? I generally wouldn't mind, but in the context of meshes it might be worth avoiding the potential confusion with vertex normal.
|
@IceSentry Thank you for your review! I tried to fix stuff from your comments in the last commit.
I think people might want to use a Mesh in Bevy, have no idea how to, search "Mesh Bevy", and either find this doc, or Bevy's cheatbook, in the first case I think it's good to have some references to them at least. Also knowing that the "UV" and "Normals" are important to put in a mesh for StandardMaterial to work properly is also important imo. Tell me if it still needs improvement. |
Selene-Amanita
added
the
S-Ready-For-Final-Review
# Objective This PR continues #8885 It aims to improve the `Mesh` documentation in the following ways: - Put everything at the "top level" instead of the "impl". - Explain better what is a Mesh, how it can be created, and that it can be edited. - Explain it can be used with a `Material`, and mention `StandardMaterial`, `PbrBundle`, `ColorMaterial`, and `ColorMesh2dBundle` since those cover most cases - Mention the glTF/Bevy vocabulary discrepancy for "Mesh" - Add an image for the example - Various nitpicky modifications ## Note - The image I added is 90.3ko which I think is small enough? - Since rustdoc doesn't allow cross-reference not in dependencies of a subcrate [yet](rust-lang/rust#74481), I have a lot of backtick references that are not links :( - Since rustdoc doesn't allow linking to code in the crate (?) I put link to github directly. - Since rustdoc doesn't allow embed images in doc [yet](rust-lang/rust#32104), maybe [soon](rust-lang/rfcs#3397), I had to put only a link to the image. I don't think it's worth adding [embed_doc_image](https://docs.rs/embed-doc-image/latest/embed_doc_image/) as a dependency for this.
4 participants
Objective
This PR continues #8885
It aims to improve the
Meshdocumentation in the following ways:Material, and mentionStandardMaterial,PbrBundle,ColorMaterial, andColorMesh2dBundlesince those cover most casesNote