mirror of
https://github.com/bevyengine/bevy
synced 2024-11-10 15:14:50 +00:00
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:
parent
64b29617d6
commit
006848311c
2 changed files with 42 additions and 0 deletions
|
@ -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;
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
|
|
Loading…
Reference in a new issue