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.
This commit is contained in:
sdfgeoff 2021-03-06 01:57:02 +00:00
parent 64b29617d6
commit 006848311c
2 changed files with 42 additions and 0 deletions

View file

@ -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;
}

View file

@ -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,