Add consuming builder methods for more ergonomic Mesh creation

crates/bevy_pbr/src/pbr_material.rs

@@ -152,11 +152,13 @@ pub struct StandardMaterial {
  /// - Vertex normals
  ///
  /// Tangents do not have to be stored in your model,
- /// they can be generated using the [`Mesh::generate_tangents`] method.
+ /// they can be generated using the [`Mesh::generate_tangents`] or
+ /// [`Mesh::with_generated_tangents`] methods.
  /// If your material has a normal map, but still renders as a flat surface,
  /// make sure your meshes have their tangents set.
  ///
  /// [`Mesh::generate_tangents`]: bevy_render::mesh::Mesh::generate_tangents
+ /// [`Mesh::with_generated_tangents`]: bevy_render::mesh::Mesh::with_generated_tangents
  #[texture(9)]
  #[sampler(10)]
  #[dependency]

crates/bevy_render/src/mesh/mesh/mod.rs

@@ -49,32 +49,32 @@ pub const VERTEX_ATTRIBUTE_BUFFER_ID: u64 = 10;
 /// # use bevy_render::mesh::{Mesh, Indices};
 /// # use bevy_render::render_resource::PrimitiveTopology;
 /// fn create_simple_parallelogram() -> Mesh {
-/// // Create a new mesh, add 4 vertices, each with its own position attribute (coordinate in
-/// // 3D space), for each of the corners of the parallelogram.
-/// let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
-/// mesh.insert_attribute(
-/// Mesh::ATTRIBUTE_POSITION,
-/// vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [2.0, 2.0, 0.0], [1.0, 0.0, 0.0]]
-/// );
-/// // Assign a UV coordinate to each vertex.
-/// mesh.insert_attribute(
-/// Mesh::ATTRIBUTE_UV_0,
-/// vec![[0.0, 1.0], [0.5, 0.0], [1.0, 0.0], [0.5, 1.0]]
-/// );
-/// // Assign normals (everything points outwards)
-/// mesh.insert_attribute(
-/// Mesh::ATTRIBUTE_NORMAL,
-/// vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0]]
-/// );
-/// // After defining all the vertices and their attributes, build each triangle using the
-/// // indices of the vertices that make it up in a counter-clockwise order.
-/// mesh.set_indices(Some(Indices::U32(vec![
-/// // First triangle
-/// 0, 3, 1,
-/// // Second triangle
-/// 1, 3, 2
-/// ])));
-/// mesh
+/// // Create a new mesh using a triangle list topology, where each set of 3 vertices composes a triangle.
+/// Mesh::new(PrimitiveTopology::TriangleList)
+///  // Add 4 vertices, each with its own position attribute (coordinate in
+///  // 3D space), for each of the corners of the parallelogram.
+/// .with_inserted_attribute(
+///  Mesh::ATTRIBUTE_POSITION,
+///  vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [2.0, 2.0, 0.0], [1.0, 0.0, 0.0]]
+///  )
+///  // Assign a UV coordinate to each vertex.
+/// .with_inserted_attribute(
+///  Mesh::ATTRIBUTE_UV_0,
+///  vec![[0.0, 1.0], [0.5, 0.0], [1.0, 0.0], [0.5, 1.0]]
+///  )
+///  // Assign normals (everything points outwards)
+///  .with_inserted_attribute(
+///  Mesh::ATTRIBUTE_NORMAL,
+///  vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0]]
+///  )
+///  // After defining all the vertices and their attributes, build each triangle using the
+///  // indices of the vertices that make it up in a counter-clockwise order.
+/// .with_indices(Some(Indices::U32(vec![
+///  // First triangle
+///  0, 3, 1,
+///  // Second triangle
+///  1, 3, 2
+///  ])))
 /// }
 /// ```
 ///
@@ -126,16 +126,18 @@ pub struct Mesh {
 }
 
 impl Mesh {
- /// Where the vertex is located in space. Use in conjunction with [`Mesh::insert_attribute`].
+ /// Where the vertex is located in space. Use in conjunction with [`Mesh::insert_attribute`]
+ /// or [`Mesh::with_inserted_attribute`].
  pub const ATTRIBUTE_POSITION: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_Position", 0, VertexFormat::Float32x3);
 
  /// The direction the vertex normal is facing in.
- /// Use in conjunction with [`Mesh::insert_attribute`].
+ /// Use in conjunction with [`Mesh::insert_attribute`] or [`Mesh::with_inserted_attribute`].
  pub const ATTRIBUTE_NORMAL: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_Normal", 1, VertexFormat::Float32x3);
 
- /// Texture coordinates for the vertex. Use in conjunction with [`Mesh::insert_attribute`].
+ /// Texture coordinates for the vertex. Use in conjunction with [`Mesh::insert_attribute`]
+ /// or [`Mesh::with_inserted_attribute`].
  ///
  /// Values are generally between 0. and 1., with `StandardMaterial` and `ColorMaterial`
  /// `[0.,0.]` is the top left of the texture, and [1.,1.] the bottom-right.
@@ -147,27 +149,31 @@ impl Mesh {
  MeshVertexAttribute::new("Vertex_Uv", 2, VertexFormat::Float32x2);
 
  /// Alternate texture coordinates for the vertex. Use in conjunction with
- /// [`Mesh::insert_attribute`].
+ /// [`Mesh::insert_attribute`] or [`Mesh::with_inserted_attribute`].
  ///
  /// Typically, these are used for lightmaps, textures that provide
  /// precomputed illumination.
  pub const ATTRIBUTE_UV_1: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_Uv_1", 3, VertexFormat::Float32x2);
 
  /// The direction of the vertex tangent. Used for normal mapping.
- /// Usually generated with [`generate_tangents`](Mesh::generate_tangents).
+ /// Usually generated with [`generate_tangents`](Mesh::generate_tangents) or
+ /// [`with_generated_tangents`](Mesh::with_generated_tangents).
  pub const ATTRIBUTE_TANGENT: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_Tangent", 4, VertexFormat::Float32x4);
 
- /// Per vertex coloring. Use in conjunction with [`Mesh::insert_attribute`].
+ /// Per vertex coloring. Use in conjunction with [`Mesh::insert_attribute`]
+ /// or [`Mesh::with_inserted_attribute`].
  pub const ATTRIBUTE_COLOR: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_Color", 5, VertexFormat::Float32x4);
 
- /// Per vertex joint transform matrix weight. Use in conjunction with [`Mesh::insert_attribute`].
+ /// Per vertex joint transform matrix weight. Use in conjunction with [`Mesh::insert_attribute`]
+ /// or [`Mesh::with_inserted_attribute`].
  pub const ATTRIBUTE_JOINT_WEIGHT: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_JointWeight", 6, VertexFormat::Float32x4);
 
- /// Per vertex joint transform matrix index. Use in conjunction with [`Mesh::insert_attribute`].
+ /// Per vertex joint transform matrix index. Use in conjunction with [`Mesh::insert_attribute`]
+ /// or [`Mesh::with_inserted_attribute`].
  pub const ATTRIBUTE_JOINT_INDEX: MeshVertexAttribute =
  MeshVertexAttribute::new("Vertex_JointIndex", 7, VertexFormat::Uint16x4);
 
@@ -224,6 +230,24 @@ impl Mesh {
  .insert(attribute.id, MeshAttributeData { attribute, values });
  }
 
+ /// Consumes the mesh and returns a mesh with data set for a vertex attribute (position, normal etc.).
+ /// The name will often be one of the associated constants such as [`Mesh::ATTRIBUTE_POSITION`].
+ ///
+ /// (Alternatively, you can use [`Mesh::insert_attribute`] to mutate an existing mesh in-place)
+ ///
+ /// # Panics
+ /// Panics when the format of the values does not match the attribute's format.
+ #[must_use]
+ #[inline]
+ pub fn with_inserted_attribute(
+ mut self,
+ attribute: MeshVertexAttribute,
+ values: impl Into<VertexAttributeValues>,
+ ) -> Self {
+ self.insert_attribute(attribute, values);
+ self
+ }
+
  /// Removes the data for a vertex attribute
  pub fn remove_attribute(
  &mut self,
@@ -234,6 +258,15 @@ impl Mesh {
  .map(|data| data.values)
  }
 
+ /// Consumes the mesh and returns a mesh without the data for a vertex attribute
+ ///
+ /// (Alternatively, you can use [`Mesh::remove_attribute`] to mutate an existing mesh in-place)
+ #[must_use]
+ pub fn with_removed_attribute(mut self, attribute: impl Into<MeshVertexAttributeId>) -> Self {
+ self.remove_attribute(attribute);
+ self
+ }
+
  #[inline]
  pub fn contains_attribute(&self, id: impl Into<MeshVertexAttributeId>) -> bool {
  self.attributes.contains_key(&id.into())
@@ -283,6 +316,18 @@ impl Mesh {
  self.indices = indices;
  }
 
+ /// Consumes the mesh and returns a mesh with the given vertex indices. They describe how triangles
+ /// are constructed out of the vertex attributes and are therefore only useful for the
+ /// [`PrimitiveTopology`] variants that use triangles.
+ ///
+ /// (Alternatively, you can use [`Mesh::set_indices`] to mutate an existing mesh in-place)
+ #[must_use]
+ #[inline]
+ pub fn with_indices(mut self, indices: Option<Indices>) -> Self {
+ self.set_indices(indices);
+ self
+ }
+
  /// Retrieves the vertex `indices` of the mesh.
  #[inline]
  pub fn indices(&self) -> Option<&Indices> {
@@ -436,6 +481,18 @@ impl Mesh {
  }
  }
 
+ /// Consumes the mesh and returns a mesh with no shared vertices.
+ ///
+ /// This can dramatically increase the vertex count, so make sure this is what you want.
+ /// Does nothing if no [Indices] are set.
+ ///
+ /// (Alternatively, you can use [`Mesh::duplicate_vertices`] to mutate an existing mesh in-place)
+ #[must_use]
+ pub fn with_duplicated_vertices(mut self) -> Self {
+ self.duplicate_vertices();
+ self
+ }
+
  /// Calculates the [`Mesh::ATTRIBUTE_NORMAL`] of a mesh.
  ///
  /// # Panics
@@ -465,6 +522,20 @@ impl Mesh {
  self.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
  }
 
+ /// Consumes the mesh and returns a mesh with calculated [`Mesh::ATTRIBUTE_NORMAL`].
+ ///
+ /// (Alternatively, you can use [`Mesh::compute_flat_normals`] to mutate an existing mesh in-place)
+ ///
+ /// # Panics
+ /// Panics if [`Indices`] are set or [`Mesh::ATTRIBUTE_POSITION`] is not of type `float3` or
+ /// if the mesh has any other topology than [`PrimitiveTopology::TriangleList`].
+ /// Consider calling [`Mesh::with_duplicated_vertices`] or export your mesh with normal attributes.
+ #[must_use]
+ pub fn with_computed_flat_normals(mut self) -> Self {
+ self.compute_flat_normals();
+ self
+ }
+
  /// Generate tangents for the mesh using the `mikktspace` algorithm.
  ///
  /// Sets the [`Mesh::ATTRIBUTE_TANGENT`] attribute if successful.
@@ -475,6 +546,18 @@ impl Mesh {
  Ok(())
  }
 
+ /// Consumes the mesh and returns a mesh with tangents generated using the `mikktspace` algorithm.
+ ///
+ /// The resulting mesh will have the [`Mesh::ATTRIBUTE_TANGENT`] attribute if successful.
+ ///
+ /// (Alternatively, you can use [`Mesh::generate_tangents`] to mutate an existing mesh in-place)
+ ///
+ /// Requires a [`PrimitiveTopology::TriangleList`] topology and the [`Mesh::ATTRIBUTE_POSITION`], [`Mesh::ATTRIBUTE_NORMAL`] and [`Mesh::ATTRIBUTE_UV_0`] attributes set.
+ pub fn with_generated_tangents(mut self) -> Result<Mesh, GenerateTangentsError> {
+ self.generate_tangents()?;
+ Ok(self)
+ }
+
  /// Compute the Axis-Aligned Bounding Box of the mesh vertices in model space
  pub fn compute_aabb(&self) -> Option<Aabb> {
  let Some(VertexAttributeValues::Float32x3(values)) =
@@ -498,11 +581,34 @@ impl Mesh {
  self.morph_targets = Some(morph_targets);
  }
 
+ /// Consumes the mesh and returns a mesh with the given [morph targets].
+ ///
+ /// This requires a "morph target image". See [`MorphTargetImage`](crate::mesh::morph::MorphTargetImage) for info.
+ ///
+ /// (Alternatively, you can use [`Mesh::set_morph_targets`] to mutate an existing mesh in-place)
+ ///
+ /// [morph targets]: https://en.wikipedia.org/wiki/Morph_target_animation
+ #[must_use]
+ pub fn with_morph_targets(mut self, morph_targets: Handle<Image>) -> Self {
+ self.set_morph_targets(morph_targets);
+ self
+ }
+
  /// Sets the names of each morph target. This should correspond to the order of the morph targets in `set_morph_targets`.
  pub fn set_morph_target_names(&mut self, names: Vec<String>) {
  self.morph_target_names = Some(names);
  }
 
+ /// Consumes the mesh and returns a mesh with morph target names.
+ /// Names should correspond to the order of the morph targets in `set_morph_targets`.
+ ///
+ /// (Alternatively, you can use [`Mesh::set_morph_target_names`] to mutate an existing mesh in-place)
+ #[must_use]
+ pub fn with_morph_target_names(mut self, names: Vec<String>) -> Self {
+ self.set_morph_target_names(names);
+ self
+ }
+
  /// Gets a list of all morph target names, if they exist.
  pub fn morph_target_names(&self) -> Option<&[String]> {
  self.morph_target_names.as_deref()
@@ -1123,7 +1229,7 @@ mod tests {
  #[test]
  #[should_panic]
  fn panic_invalid_format() {
- let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
- mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, vec![[0.0, 0.0, 0.0]]);
+ let _mesh = Mesh::new(PrimitiveTopology::TriangleList)
+  .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, vec![[0.0, 0.0, 0.0]]);
  }
 }

crates/bevy_render/src/mesh/shape/capsule.rs

@@ -364,11 +364,10 @@ impl From<Capsule> for Mesh {
  assert_eq!(vs.len(), vert_len);
  assert_eq!(tris.len(), fs_len);
 
- let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
- mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, vs);
- mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, vns);
- mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, vts);
- mesh.set_indices(Some(Indices::U32(tris)));
- mesh
+ Mesh::new(PrimitiveTopology::TriangleList)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, vs)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, vns)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, vts)
+ .with_indices(Some(Indices::U32(tris)))
  }
 }

crates/bevy_render/src/mesh/shape/cylinder.rs

@@ -118,11 +118,10 @@ impl From<Cylinder> for Mesh {
  build_cap(true);
  build_cap(false);
 
- let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
- mesh.set_indices(Some(Indices::U32(indices)));
- mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
- mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
- mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, uvs);
- mesh
+ Mesh::new(PrimitiveTopology::TriangleList)
+ .with_indices(Some(Indices::U32(indices)))
+ .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
  }
 }

crates/bevy_render/src/mesh/shape/icosphere.rs

@@ -103,11 +103,10 @@ impl TryFrom<Icosphere> for Mesh {
 
  let indices = Indices::U32(indices);
 
- let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
- mesh.set_indices(Some(indices));
- mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, points);
- mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
- mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, uvs);
- Ok(mesh)
+ Ok(Mesh::new(PrimitiveTopology::TriangleList)
+ .with_indices(Some(indices))
+ .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, points)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
+ .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs))
  }
 }