[fix] warnings and add documentation around frame acquisition

Author: vmarcella

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

@@ -188,10 +188,7 @@ mod tests {
   /// expected vertex + attribute counts.
   #[test]
   fn mesh_build_from_obj_parses_vertices() {
-    use std::{
-      fs,
-      path::PathBuf,
-    };
+    use std::fs;
 
     // Minimal OBJ with one triangle, normals, and texture coordinates.
     let obj = r#"
@@ -205,7 +202,7 @@ vn 0.0 0.0 1.0
 f 1/1/1 2/2/1 3/3/1
 "#;
 
-    let mut path = PathBuf::from(std::env::temp_dir());
+    let mut path = std::env::temp_dir();
     path.push("lambda_mesh_test.obj");
     fs::write(&path, obj).expect("write temp obj");
 

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

@@ -562,41 +562,52 @@ impl RenderContext {
       return Ok(());
     }
 
-    let requires_surface = commands.iter().any(|cmd| match cmd {
-      RenderCommand::BeginRenderPass { .. } => true,
-      RenderCommand::BeginRenderPassTo {
-        destination: RenderDestination::Surface,
-        ..
-      } => true,
-      _ => false,
+    // Determine whether this command list needs access to the presentation
+    // surface. We only acquire a surface frame when a surface-backed pass is
+    // requested; offscreen-only command lists can render without a window.
+    let requires_surface = commands.iter().any(|cmd| {
+      return matches!(
+        cmd,
+        RenderCommand::BeginRenderPass { .. }
+          | RenderCommand::BeginRenderPassTo {
+            destination: RenderDestination::Surface,
+            ..
+          }
+      );
     });
 
     let mut frame = if requires_surface {
-      Some(
-        match {
-          let surface = self.surface.as_mut().ok_or_else(|| {
-            RenderError::Configuration(
-              "No surface attached to RenderContext".to_string(),
-            )
-          })?;
-          surface.acquire_frame()
-        } {
-          Ok(frame) => frame,
-          Err(err) => match err {
-            targets::surface::SurfaceError::Lost
-            | targets::surface::SurfaceError::Outdated => {
-              self.reconfigure_surface(self.size)?;
-              let surface = self.surface.as_mut().ok_or_else(|| {
-                RenderError::Configuration(
-                  "No surface attached to RenderContext".to_string(),
-                )
-              })?;
-              surface.acquire_frame().map_err(RenderError::Surface)?
-            }
-            _ => return Err(RenderError::Surface(err)),
-          },
+      // Acquire exactly one surface frame up-front and reuse its `TextureView`
+      // for all surface-backed render passes in this command list. The acquired
+      // frame is presented after encoding completes.
+      //
+      // If acquisition fails due to surface loss/outdated config, attempt to
+      // reconfigure the surface to the current context size and retry once.
+      let acquired = {
+        let surface = self.surface.as_mut().ok_or_else(|| {
+          RenderError::Configuration(
+            "No surface attached to RenderContext".to_string(),
+          )
+        })?;
+        surface.acquire_frame()
+      };
+
+      Some(match acquired {
+        Ok(frame) => frame,
+        Err(err) => match err {
+          targets::surface::SurfaceError::Lost
+          | targets::surface::SurfaceError::Outdated => {
+            self.reconfigure_surface(self.size)?;
+            let surface = self.surface.as_mut().ok_or_else(|| {
+              RenderError::Configuration(
+                "No surface attached to RenderContext".to_string(),
+              )
+            })?;
+            surface.acquire_frame().map_err(RenderError::Surface)?
+          }
+          _ => return Err(RenderError::Surface(err)),
         },
-      )
+      })
     } else {
       None
     };