Mesh insert indices (#11745)

# Objective

- Fixes #11740 

## Solution

- Turned `Mesh::set_indices` into `Mesh::insert_indices` and added
related methods for completeness.

---

## Changelog

- Replaced `Mesh::set_indices(indices: Option<Indices>)` with
`Mesh::insert_indices(indices: Indices)`
- Replaced `Mesh::with_indices(indices: Option<Indices>)` with
`Mesh::with_inserted_indices(indices: Indices)` and
`Mesh::with_removed_indices()` mirroring the API for inserting /
removing attributes.
- Updated the examples and internal uses of the APIs described above.

## Migration Guide

- Use `Mesh::insert_indices` or `Mesh::with_inserted_indices` instead of
`Mesh::set_indices` / `Mesh::with_indices`.
- If you have passed `None` to `Mesh::set_indices` or
`Mesh::with_indices` you should use `Mesh::remove_indices` or
`Mesh::with_removed_indices` instead.

---------

Co-authored-by: François <mockersf@gmail.com>

crates/bevy_gltf/src/loader.rs

@@ -423,11 +423,11 @@ async fn load_gltf<'a, 'b, 'c>(
             // Read vertex indices
             let reader = primitive.reader(|buffer| Some(buffer_data[buffer.index()].as_slice()));
             if let Some(indices) = reader.read_indices() {
-                mesh.set_indices(Some(match indices {
+                mesh.insert_indices(match indices {
                     ReadIndices::U8(is) => Indices::U16(is.map(|x| x as u16).collect()),
                     ReadIndices::U16(is) => Indices::U16(is.collect()),
                     ReadIndices::U32(is) => Indices::U32(is.collect()),
-                }));
+                });
             };
 
             {

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

@@ -71,12 +71,12 @@ pub const VERTEX_ATTRIBUTE_BUFFER_ID: u64 = 10;
 ///         )
 ///         // 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![
+///         .with_inserted_indices(Indices::U32(vec![
 ///             // First triangle
 ///             0, 3, 1,
 ///             // Second triangle
 ///             1, 3, 2
-///         ])))
+///         ]))
 /// }
 /// ```
 ///
@@ -216,7 +216,7 @@ impl Mesh {
         self.primitive_topology
     }
 
-    /// Sets the data for a vertex attribute (position, normal etc.). The name will
+    /// 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`].
     ///
     /// # Panics
@@ -240,7 +240,7 @@ 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.).
+    /// 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)
@@ -322,19 +322,19 @@ impl Mesh {
     /// vertex attributes and are therefore only useful for the [`PrimitiveTopology`] variants
     /// that use triangles.
     #[inline]
-    pub fn set_indices(&mut self, indices: Option<Indices>) {
-        self.indices = indices;
+    pub fn insert_indices(&mut self, indices: Indices) {
+        self.indices = Some(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)
+    /// (Alternatively, you can use [`Mesh::insert_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);
+    pub fn with_inserted_indices(mut self, indices: Indices) -> Self {
+        self.insert_indices(indices);
         self
     }
 
@@ -356,6 +356,15 @@ impl Mesh {
         std::mem::take(&mut self.indices)
     }
 
+    /// Consumes the mesh and returns a mesh without the vertex `indices` of the mesh.
+    ///
+    /// (Alternatively, you can use [`Mesh::remove_indices`] to mutate an existing mesh in-place)
+    #[must_use]
+    pub fn with_removed_indices(mut self) -> Self {
+        self.remove_indices();
+        self
+    }
+
     /// Computes and returns the index data of the mesh as bytes.
     /// This is used to transform the index data into a GPU friendly format.
     pub fn get_index_buffer_bytes(&self) -> Option<&[u8]> {

crates/bevy_render/src/mesh/primitives/dim2.rs

@@ -166,7 +166,7 @@ impl EllipseMeshBuilder {
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(Indices::U32(indices))
     }
 }
 
@@ -222,7 +222,7 @@ impl Meshable for Triangle2d {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
@@ -254,7 +254,7 @@ impl Meshable for Rectangle {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
@@ -379,7 +379,7 @@ impl Capsule2dMeshBuilder {
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(Indices::U32(indices))
     }
 }
 

crates/bevy_render/src/mesh/primitives/dim3/capsule.rs

@@ -417,7 +417,7 @@ impl Capsule3dMeshBuilder {
         .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)))
+        .with_inserted_indices(Indices::U32(tris))
     }
 }
 

crates/bevy_render/src/mesh/primitives/dim3/cuboid.rs

@@ -67,7 +67,7 @@ impl Meshable for Cuboid {
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
     }
 }
 

crates/bevy_render/src/mesh/primitives/dim3/cylinder.rs

@@ -153,7 +153,7 @@ impl CylinderMeshBuilder {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(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/primitives/dim3/plane.rs

@@ -79,7 +79,7 @@ impl PlaneMeshBuilder {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(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/primitives/dim3/sphere.rs

@@ -169,7 +169,7 @@ impl SphereMeshBuilder {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, points)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs))
@@ -237,7 +237,7 @@ impl SphereMeshBuilder {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(Indices::U32(indices))
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, vertices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)

crates/bevy_render/src/mesh/primitives/dim3/torus.rs

@@ -135,7 +135,7 @@ impl TorusMeshBuilder {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(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/capsule.rs

@@ -374,6 +374,6 @@ impl From<Capsule> for Mesh {
         .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)))
+        .with_inserted_indices(Indices::U32(tris))
     }
 }

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

@@ -125,7 +125,7 @@ impl From<Cylinder> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(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

@@ -110,7 +110,7 @@ impl TryFrom<Icosphere> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, points)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs))

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

@@ -129,7 +129,7 @@ impl From<Box> for Mesh {
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
     }
 }
 
@@ -181,7 +181,7 @@ impl From<Quad> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(indices))
+        .with_inserted_indices(indices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
@@ -265,7 +265,7 @@ impl From<Plane> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(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/regular_polygon.rs

@@ -65,7 +65,7 @@ impl From<RegularPolygon> for Mesh {
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(Indices::U32(indices))
     }
 }
 

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

@@ -91,7 +91,7 @@ impl From<Torus> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(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/uvsphere.rs

@@ -87,7 +87,7 @@ impl From<UVSphere> for Mesh {
             PrimitiveTopology::TriangleList,
             RenderAssetUsages::default(),
         )
-        .with_indices(Some(Indices::U32(indices)))
+        .with_inserted_indices(Indices::U32(indices))
         .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, vertices)
         .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
         .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)

examples/2d/mesh2d_manual.rs

@@ -100,7 +100,7 @@ fn star(
     for i in 2..=10 {
         indices.extend_from_slice(&[0, i, i - 1]);
     }
-    star.set_indices(Some(Indices::U32(indices)));
+    star.insert_indices(Indices::U32(indices));
 
     // We can now spawn the entities for the star and the camera
     commands.spawn((

examples/3d/generate_custom_mesh.rs

@@ -230,14 +230,14 @@ fn create_cube_mesh() -> Mesh {
     // should appear counter-clockwise from the front of the triangle, in this case from outside the cube).
     // Read more about how to correctly build a mesh manually in the Bevy documentation of a Mesh,
     // further examples and the implementation of the built-in shapes.
-    .with_indices(Some(Indices::U32(vec![
+    .with_inserted_indices(Indices::U32(vec![
         0,3,1 , 1,3,2, // triangles making up the top (+y) facing side.
         4,5,7 , 5,6,7, // bottom (-y)
         8,11,9 , 9,11,10, // right (+x)
         12,13,15 , 13,14,15, // left (-x)
         16,19,17 , 17,19,18, // back (+z)
         20,21,23 , 21,22,23, // forward (-z)
-    ])))
+    ]))
 }
 
 // Function that changes the UV mapping of the mesh, to apply the other texture.

examples/animation/custom_skinned_mesh.rs

@@ -116,9 +116,9 @@ fn setup(
     )
     // Tell bevy to construct triangles from a list of vertex indices,
     //  where each 3 vertex indices form an triangle.
-    .with_indices(Some(Indices::U16(vec![
+    .with_inserted_indices(Indices::U16(vec![
         0, 1, 3, 0, 3, 2, 2, 3, 5, 2, 5, 4, 4, 5, 7, 4, 7, 6, 6, 7, 9, 6, 9, 8,
-    ])));
+    ]));
 
     let mesh = meshes.add(mesh);