perf(lambda-rs): Avoid cloning vertices and attributes when building meshes (#190)

## Summary

Refactors `MeshBuilder` to use by-value chaining and makes `build(self)`
consume the builder, eliminating O(n) clones of vertex/attribute buffers
during mesh finalization.

## Related Issues

- N/A

## Changes

- Updated `MeshBuilder` builder methods to take/return `Self`
(`with_capacity`, `with_vertex`, `with_attributes`) and changed `build`
to `build(self) -> Mesh`.
- Updated call sites (demos + `lambda-obj-loader`) to use by-value
chaining / folds.
- Updated docs/tutorial snippets.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] Feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation (updates to docs, specs, tutorials, or comments)
- [x] Refactor (code change that neither fixes a bug nor adds a feature)
- [x] Performance (change that improves performance)
- [ ] Test (adding or updating tests)
- [ ] Build/CI (changes to build process or CI configuration)

## Affected Crates

- [x] `lambda-rs`
- [ ] `lambda-rs-platform`
- [ ] `lambda-rs-args`
- [ ] `lambda-rs-logging`
- [x] Other: `lambda-demos-render`, `lambda-demos-physics`,
`lambda-obj-loader`, docs

## Checklist

- [ ] Code follows the repository style guidelines (`cargo +nightly fmt
--all`) (not run)
- [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D
warnings`) (not run)
- [ ] Tests pass (`cargo test --workspace`) (not run)
- [x] New code includes appropriate documentation
- [x] Public API changes are documented
- [x] Breaking changes are noted in this PR description

## Testing

**Commands run:**

```bash
cargo test -p lambda-rs
cargo check -p lambda-demos-render -p lambda-demos-physics -p lambda-obj-loader
```

**Manual verification steps (if applicable):**

1. N/A

## Screenshots/Recordings

N/A

## Platform Testing

- [x] macOS
- [ ] Windows
- [ ] Linux

## Additional Notes

Author: vmarcella

crates/lambda-rs/src/render/mesh.rs

@@ -64,7 +64,7 @@ impl MeshBuilder {
 
   /// Allocates memory for the given number of vertices and fills
   /// the mesh with empty vertices.
-  pub fn with_capacity(&mut self, size: usize) -> &mut Self {
+  pub fn with_capacity(mut self, size: usize) -> Self {
     self.vertices.resize(
       size,
       Vertex {
@@ -77,34 +77,32 @@ impl MeshBuilder {
   }
 
   /// Adds a vertex to the mesh.
-  pub fn with_vertex(&mut self, vertex: Vertex) -> &mut Self {
+  pub fn with_vertex(mut self, vertex: Vertex) -> Self {
     self.vertices.push(vertex);
     return self;
   }
 
   /// Specify the attributes of the mesh. This is used to map the vertex data to
   /// the input of the vertex shader.
-  pub fn with_attributes(
-    &mut self,
-    attributes: Vec<VertexAttribute>,
-  ) -> &mut Self {
+  pub fn with_attributes(mut self, attributes: Vec<VertexAttribute>) -> Self {
     self.attributes = attributes;
     return self;
   }
 
   /// Builds a mesh from the vertices and indices that have been added to the
   /// builder and allocates the memory for the mesh on the GPU.
-  pub fn build(&self) -> Mesh {
+  pub fn build(self) -> Mesh {
     return Mesh {
-      vertices: self.vertices.clone(),
-      attributes: self.attributes.clone(),
+      vertices: self.vertices,
+      attributes: self.attributes,
     };
   }
 
   /// Builds a mesh from the vertices of an OBJ file. The mesh will have the same
   /// attributes as the OBJ file and can be allocated on to the GPU with
   /// `BufferBuilder::build_from_mesh`.
-  pub fn build_from_obj(&self, file_path: &str) -> Mesh {
+  pub fn build_from_obj(self, file_path: &str) -> Mesh {
+    let _ = self;
     let obj = load_textured_obj_from_file(file_path);
 
     let vertices = obj
@@ -170,17 +168,16 @@ mod tests {
   /// the built mesh.
   #[test]
   fn mesh_builder_capacity_and_attributes_are_applied() {
-    let mut builder = MeshBuilder::new();
-    builder.with_capacity(2);
+    let builder = MeshBuilder::new().with_capacity(2);
     assert_eq!(builder.vertices.len(), 2);
 
-    builder.with_vertex(Vertex {
-      position: [1.0, 2.0, 3.0],
-      normal: [0.0, 1.0, 0.0],
-      color: [0.5, 0.5, 0.5],
-    });
-
-    let mesh = builder.build();
+    let mesh = builder
+      .with_vertex(Vertex {
+        position: [1.0, 2.0, 3.0],
+        normal: [0.0, 1.0, 0.0],
+        color: [0.5, 0.5, 0.5],
+      })
+      .build();
     assert_eq!(mesh.vertices().len(), 3);
   }
 

demos/physics/src/bin/physics_falling_quad.rs

@@ -175,12 +175,12 @@ impl Component<ComponentResult, String> for FallingQuadDemo {
         .build(),
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    vertices.iter().for_each(|vertex| {
-      mesh_builder.with_vertex(*vertex);
-    });
-
-    let mesh = mesh_builder
+    let mesh = vertices
+      .iter()
+      .copied()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/physics/src/bin/physics_rigid_bodies_2d.rs

@@ -350,12 +350,12 @@ impl Component<ComponentResult, String> for RigidBodies2DDemo {
         .build(),
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    vertices.iter().for_each(|vertex| {
-      mesh_builder.with_vertex(*vertex);
-    });
-
-    let mesh = mesh_builder
+    let mesh = vertices
+      .iter()
+      .copied()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/render/src/bin/immediates.rs

@@ -149,12 +149,12 @@ impl Component<ComponentResult, String> for ImmediatesExample {
         .build(),
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    vertices.iter().for_each(|vertex| {
-      mesh_builder.with_vertex(*vertex);
-    });
-
-    let mesh = mesh_builder
+    let mesh = vertices
+      .iter()
+      .copied()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/render/src/bin/offscreen_post.rs

@@ -338,12 +338,11 @@ impl OffscreenPostExample {
         .build(),
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    for v in vertices {
-      mesh_builder.with_vertex(v);
-    }
-
-    return mesh_builder
+    return vertices
+      .into_iter()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/render/src/bin/reflective_room.rs

@@ -870,11 +870,11 @@ fn build_unit_cube_mesh() -> Mesh {
     [(h, -h, -h), (-h, -h, -h), (-h, h, -h), (h, h, -h)],
   );
 
-  let mut mesh_builder = MeshBuilder::new();
-  for v in verts.into_iter() {
-    mesh_builder.with_vertex(v);
-  }
-  let mesh = mesh_builder
+  let mesh = verts
+    .into_iter()
+    .fold(MeshBuilder::new(), |builder, vertex| {
+      return builder.with_vertex(vertex);
+    })
     .with_attributes(vec![
       VertexAttribute {
         location: 0,
@@ -914,18 +914,16 @@ fn build_floor_quad_mesh(extent: f32) -> Mesh {
   let p2 = v(h, h);
   let p3 = v(-h, h);
 
-  let mut mesh_builder = MeshBuilder::new();
   // Tri winding flipped to face +Y (avoid back-face cull)
-  // Tri 1
-  mesh_builder.with_vertex(p0);
-  mesh_builder.with_vertex(p2);
-  mesh_builder.with_vertex(p1);
-  // Tri 2
-  mesh_builder.with_vertex(p0);
-  mesh_builder.with_vertex(p3);
-  mesh_builder.with_vertex(p2);
-
-  let mesh = mesh_builder
+  let mesh = MeshBuilder::new()
+    // Tri 1
+    .with_vertex(p0)
+    .with_vertex(p2)
+    .with_vertex(p1)
+    // Tri 2
+    .with_vertex(p0)
+    .with_vertex(p3)
+    .with_vertex(p2)
     .with_attributes(vec![
       VertexAttribute {
         location: 0,

demos/render/src/bin/textured_cube.rs

@@ -262,11 +262,11 @@ impl Component<ComponentResult, String> for TexturedCubeExample {
       [(h, -h, -h), (-h, -h, -h), (-h, h, -h), (h, h, -h)],
     );
 
-    let mut mesh_builder = MeshBuilder::new();
-    for v in verts.into_iter() {
-      mesh_builder.with_vertex(v);
-    }
-    let mesh = mesh_builder
+    let mesh = verts
+      .into_iter()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/render/src/bin/textured_quad.rs

@@ -163,11 +163,12 @@ impl Component<ComponentResult, String> for TexturedQuadExample {
         .build(), // uv (0,1)
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    vertices.iter().for_each(|v| {
-      mesh_builder.with_vertex(*v);
-    });
-    let mesh = mesh_builder
+    let mesh = vertices
+      .iter()
+      .copied()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

demos/render/src/bin/uniform_buffer_triangle.rs

@@ -148,12 +148,12 @@ impl Component<ComponentResult, String> for UniformBufferExample {
         .build(),
     ];
 
-    let mut mesh_builder = MeshBuilder::new();
-    vertices.iter().for_each(|vertex| {
-      mesh_builder.with_vertex(*vertex);
-    });
-
-    let mesh = mesh_builder
+    let mesh = vertices
+      .iter()
+      .copied()
+      .fold(MeshBuilder::new(), |builder, vertex| {
+        return builder.with_vertex(vertex);
+      })
       .with_attributes(vec![
         VertexAttribute {
           location: 0,

docs/tutorials/physics/basics/falling-quad-kinematic.md

@@ -468,12 +468,10 @@ fn on_attach(
       .build(),
   ];
 
-  let mut mesh_builder = MeshBuilder::new();
-  vertices.iter().for_each(|vertex| {
-    mesh_builder.with_vertex(*vertex);
-  });
-
-  let mesh = mesh_builder
+  let mesh = vertices
+    .iter()
+    .copied()
+    .fold(MeshBuilder::new(), |builder, vertex| builder.with_vertex(vertex))
     .with_attributes(vec![
       VertexAttribute {
         location: 0,