Documented some of the Mesh properties (#1566)

I was fiddling with creating a mesh importer today, and decided to write some more docs. 

A lot of this is describing general renderer/GL stuff, so you'll probably find most of it self explanatory anyway, but perhaps it will be useful for someone.

Author: sdfgeoff

crates/bevy_render/src/mesh/mesh.rs

@@ -21,6 +21,7 @@ use bevy_utils::{HashMap, HashSet};
 pub const INDEX_BUFFER_ASSET_INDEX: u64 = 0;
 pub const VERTEX_ATTRIBUTE_BUFFER_ID: u64 = 10;
 
+/// An array where each entry describes a property of a single vertex.
 #[derive(Clone, Debug)]
 pub enum VertexAttributeValues {
     Float(Vec<f32>),
@@ -39,6 +40,8 @@ pub enum VertexAttributeValues {
 }
 
 impl VertexAttributeValues {
+    /// Returns the number of vertices in this VertexAttribute. For a single
+    /// mesh, all of the VertexAttributeValues must have the same length.
     pub fn len(&self) -> usize {
         match *self {
             VertexAttributeValues::Float(ref values) => values.len(),
@@ -57,11 +60,14 @@ impl VertexAttributeValues {
         }
     }
 
+    /// Returns `true` if there are no vertices in this VertexAttributeValue
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
     // TODO: add vertex format as parameter here and perform type conversions
+    /// Flattens the VertexAttributeArray into a sequence of bytes. This is
+    /// useful for serialization and sending to the GPU.
     pub fn get_bytes(&self) -> &[u8] {
         match self {
             VertexAttributeValues::Float(values) => values.as_slice().as_bytes(),
@@ -179,6 +185,9 @@ impl From<Vec<[u8; 4]>> for VertexAttributeValues {
     }
 }
 
+/// An array of indices into the VertexAttributeValues for a mesh.
+///
+/// It describes the order in which the vertex attributes should be joined into faces.
 #[derive(Debug)]
 pub enum Indices {
     U16(Vec<u16>),
@@ -204,12 +213,39 @@ pub struct Mesh {
     indices: Option<Indices>,
 }
 
+/// Contains geometry in the form of a mesh.
+///
+/// Often meshes are automatically generated by bevy's asset loaders or primitives, such as
+/// [`crate::shape::Cube`] or [`crate::shape::Box`], but you can also construct
+/// one yourself.
+///
+/// Example of constructing a mesh:
+/// ```
+/// # use bevy_render::mesh::{Mesh, Indices};
+/// # use bevy_render::pipeline::PrimitiveTopology;
+/// fn create_triangle() -> Mesh {
+///     let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
+///     mesh.set_attribute(Mesh::ATTRIBUTE_POSITION, vec![[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]]);
+///     mesh.set_indices(Some(Indices::U32(vec![0,1,2])));
+///     mesh
+/// }
+/// ```
 impl Mesh {
+    /// Per vertex coloring. Use in conjunction with [`Mesh::set_attribute`]
     pub const ATTRIBUTE_COLOR: &'static str = "Vertex_Color";
+
+    /// The direction the vertex normal is facing in. Use in conjunction with [`Mesh::set_attribute`]
     pub const ATTRIBUTE_NORMAL: &'static str = "Vertex_Normal";
+
+    /// Where the vertex is located in space. Use in conjunction with [`Mesh::set_attribute`]
     pub const ATTRIBUTE_POSITION: &'static str = "Vertex_Position";
+
+    /// Texture coordinates for the vertex. Use in conjunction with [`Mesh::set_attribute`]
     pub const ATTRIBUTE_UV_0: &'static str = "Vertex_Uv";
 
+    /// Construct a new mesh. You need to provide a PrimitiveTopology so that the
+    /// renderer knows how to treat the vertex data. Most of the time this will be
+    /// `PrimitiveTopology::TriangleList`.
     pub fn new(primitive_topology: PrimitiveTopology) -> Self {
         Mesh {
             primitive_topology,
@@ -222,6 +258,8 @@ impl Mesh {
         self.primitive_topology
     }
 
+    /// Sets the data for a vertex attribute (position, normal etc.). The name will
+    /// often be one of the associated constants such as [`Mesh::ATTRIBUTE_POSITION`]
     pub fn set_attribute(
         &mut self,
         name: impl Into<Cow<'static, str>>,
@@ -231,6 +269,7 @@ impl Mesh {
         self.attributes.insert(name.into(), values);
     }
 
+    /// Retrieve the data currently set behind a vertex attribute.
     pub fn attribute(&self, name: impl Into<Cow<'static, str>>) -> Option<&VertexAttributeValues> {
         self.attributes.get(&name.into())
     }
@@ -242,6 +281,8 @@ impl Mesh {
         self.attributes.get_mut(&name.into())
     }
 
+    /// Indices describe how triangles are constructed out of the vertex attributes.
+    /// They are only useful for the [`crate::pipeline::PrimitiveTopology`] variants that use triangles
     pub fn set_indices(&mut self, indices: Option<Indices>) {
         self.indices = indices;
     }

crates/bevy_render/src/pipeline/state_descriptors.rs

@@ -87,6 +87,7 @@ pub enum CompareFunction {
     Always = 7,
 }
 
+/// Describes how the VertexAttributes should be interpreted while rendering
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize, Reflect)]
 pub enum PrimitiveTopology {
     PointList = 0,