[add] high level texture view and frame implementations.

Author: vmarcella

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

@@ -6,10 +6,7 @@
 
 use lambda_platform::wgpu as platform;
 
-use super::{
-  render_pass::RenderPass as RenderPassDesc,
-  RenderContext,
-};
+use super::surface::TextureView;
 
 #[derive(Debug, Default)]
 /// High‑level color attachments collection used when beginning a render pass.
@@ -30,20 +27,26 @@ impl<'view> RenderColorAttachments<'view> {
   }
 
   /// Append a color attachment targeting the provided texture view.
-  pub(crate) fn push_color(
-    &mut self,
-    view: platform::surface::TextureViewRef<'view>,
-  ) {
-    self.inner.push_color(view);
+  ///
+  /// Accepts a high-level `TextureView` and converts it internally to the
+  /// platform type.
+  pub(crate) fn push_color(&mut self, view: TextureView<'view>) {
+    self.inner.push_color(view.to_platform());
   }
 
   /// Append a multi‑sampled color attachment with a resolve target view.
+  ///
+  /// The `msaa_view` is the multi-sampled render target, and `resolve_view`
+  /// is the single-sample target that receives the resolved output.
+  /// Both accept high-level `TextureView` types and convert internally.
   pub(crate) fn push_msaa_color(
     &mut self,
-    msaa_view: platform::surface::TextureViewRef<'view>,
-    resolve_view: platform::surface::TextureViewRef<'view>,
+    msaa_view: TextureView<'view>,
+    resolve_view: TextureView<'view>,
   ) {
-    self.inner.push_msaa_color(msaa_view, resolve_view);
+    self
+      .inner
+      .push_msaa_color(msaa_view.to_platform(), resolve_view.to_platform());
   }
 
   /// Borrow the underlying platform attachments mutably for pass creation.
@@ -53,48 +56,35 @@ impl<'view> RenderColorAttachments<'view> {
     return &mut self.inner;
   }
 
-  /// Build color attachments for a surface‑backed render pass.
+  /// Build color attachments for a surface-backed render pass.
   ///
-  /// This helper encapsulates the logic for configuring single‑sample and
-  /// multi‑sample color attachments targeting the presentation surface,
-  /// including creation and reuse of the MSAA resolve target stored on the
-  /// `RenderContext`.
+  /// This helper configures single-sample or multi-sample color attachments
+  /// targeting the presentation surface. The MSAA view is optional and should
+  /// be provided when multi-sampling is enabled.
+  ///
+  /// # Arguments
+  /// * `uses_color` - Whether the render pass uses color output.
+  /// * `sample_count` - The MSAA sample count (1 for no MSAA).
+  /// * `msaa_view` - Optional high-level MSAA texture view (required when
+  ///   `sample_count > 1`).
+  /// * `surface_view` - The high-level surface texture view (resolve target
+  ///   for MSAA, or direct target for single-sample).
   pub(crate) fn for_surface_pass(
-    render_context: &mut RenderContext,
-    pass: &RenderPassDesc,
-    surface_view: platform::surface::TextureViewRef<'view>,
+    uses_color: bool,
+    sample_count: u32,
+    msaa_view: Option<TextureView<'view>>,
+    surface_view: TextureView<'view>,
   ) -> Self {
     let mut attachments = RenderColorAttachments::new();
-    if !pass.uses_color() {
+
+    if !uses_color {
       return attachments;
     }
 
-    let sample_count = pass.sample_count();
     if sample_count > 1 {
-      let need_recreate = match &render_context.msaa_color {
-        Some(_existing) => render_context.msaa_sample_count != sample_count,
-        None => true,
-      };
-
-      if need_recreate {
-        render_context.msaa_color = Some(
-          platform::texture::ColorAttachmentTextureBuilder::new(
-            render_context.config.format,
-          )
-          .with_size(render_context.size.0.max(1), render_context.size.1.max(1))
-          .with_sample_count(sample_count)
-          .with_label("lambda-msaa-color")
-          .build(render_context.gpu()),
-        );
-        render_context.msaa_sample_count = sample_count;
-      }
-
-      let msaa_view = render_context
-        .msaa_color
-        .as_ref()
-        .expect("MSAA color attachment should be created")
-        .view_ref();
-      attachments.push_msaa_color(msaa_view, surface_view);
+      let msaa =
+        msaa_view.expect("MSAA view must be provided when sample_count > 1");
+      attachments.push_msaa_color(msaa, surface_view);
     } else {
       attachments.push_color(surface_view);
     }

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

@@ -44,6 +44,9 @@ pub mod vertex;
 pub mod viewport;
 pub mod window;
 
+// Internal modules
+mod color_attachments;
+
 use std::{
   collections::HashSet,
   iter,
@@ -398,6 +401,40 @@ impl RenderContext {
     return self.gpu.limits().min_uniform_buffer_offset_alignment;
   }
 
+  /// Ensure the MSAA color attachment texture exists with the given sample
+  /// count, recreating it if necessary. Returns the texture view reference.
+  ///
+  /// This method manages the lifecycle of the internal MSAA texture, creating
+  /// or recreating it when the sample count changes.
+  fn ensure_msaa_color_texture(
+    &mut self,
+    sample_count: u32,
+  ) -> platform::surface::TextureViewRef<'_> {
+    let need_recreate = match &self.msaa_color {
+      Some(_) => self.msaa_sample_count != sample_count,
+      None => true,
+    };
+
+    if need_recreate {
+      self.msaa_color = Some(
+        platform::texture::ColorAttachmentTextureBuilder::new(
+          self.config.format.to_platform(),
+        )
+        .with_size(self.size.0.max(1), self.size.1.max(1))
+        .with_sample_count(sample_count)
+        .with_label("lambda-msaa-color")
+        .build(self.gpu()),
+      );
+      self.msaa_sample_count = sample_count;
+    }
+
+    return self
+      .msaa_color
+      .as_ref()
+      .expect("MSAA color attachment should exist")
+      .view_ref();
+  }
+
   /// Encode and submit GPU work for a single frame.
   fn render_internal(
     &mut self,
@@ -407,16 +444,18 @@ impl RenderContext {
       return Ok(());
     }
 
-    let mut frame = match self.surface.acquire_next_frame() {
-      Ok(frame) => frame,
+    let frame = match self.surface.acquire_next_frame() {
+      Ok(frame) => surface::Frame::from_platform(frame),
       Err(err) => {
         let high_level_err = surface::SurfaceError::from(err);
         match high_level_err {
           surface::SurfaceError::Lost | surface::SurfaceError::Outdated => {
             self.reconfigure_surface(self.size)?;
-            self.surface.acquire_next_frame().map_err(|e| {
-              RenderError::Surface(surface::SurfaceError::from(e))
-            })?
+            let platform_frame =
+              self.surface.acquire_next_frame().map_err(|e| {
+                RenderError::Surface(surface::SurfaceError::from(e))
+              })?;
+            surface::Frame::from_platform(platform_frame)
           }
           _ => return Err(RenderError::Surface(high_level_err)),
         }
@@ -436,11 +475,17 @@ impl RenderContext {
           render_pass,
           viewport,
         } => {
-          let pass = self.render_passes.get(render_pass).ok_or_else(|| {
-            RenderError::Configuration(format!(
-              "Unknown render pass {render_pass}"
-            ))
-          })?;
+          // Clone the render pass descriptor to avoid borrowing self while we
+          // need mutable access for MSAA texture creation.
+          let pass = self
+            .render_passes
+            .get(render_pass)
+            .ok_or_else(|| {
+              RenderError::Configuration(format!(
+                "Unknown render pass {render_pass}"
+              ))
+            })?
+            .clone();
 
           // Build (begin) the platform render pass using the builder API.
           let mut rp_builder = platform::render_pass::RenderPassBuilder::new();
@@ -464,39 +509,32 @@ impl RenderContext {
               rp_builder.with_store_op(platform::render_pass::StoreOp::Discard)
             }
           };
-          // Create variably sized color attachments and begin the pass.
-          let mut color_attachments =
-            platform::render_pass::RenderColorAttachments::new();
+
+          // Ensure MSAA texture exists if needed.
           let sample_count = pass.sample_count();
-          if pass.uses_color() {
-            if sample_count > 1 {
-              let need_recreate = match &self.msaa_color {
-                Some(_) => self.msaa_sample_count != sample_count,
-                None => true,
-              };
-              if need_recreate {
-                self.msaa_color = Some(
-                  platform::texture::ColorAttachmentTextureBuilder::new(
-                    self.config.format.to_platform(),
-                  )
-                  .with_size(self.size.0.max(1), self.size.1.max(1))
-                  .with_sample_count(sample_count)
-                  .with_label("lambda-msaa-color")
-                  .build(self.gpu()),
-                );
-                self.msaa_sample_count = sample_count;
-              }
-              let msaa_view = self
-                .msaa_color
-                .as_ref()
-                .expect("MSAA color attachment should be created")
-                .view_ref();
-              color_attachments.push_msaa_color(msaa_view, view);
-            } else {
-              color_attachments.push_color(view);
-            }
+          let uses_color = pass.uses_color();
+          if uses_color && sample_count > 1 {
+            self.ensure_msaa_color_texture(sample_count);
           }
 
+          // Create color attachments for the surface pass. The MSAA view is
+          // retrieved here after the mutable borrow for texture creation ends.
+          let msaa_view = if sample_count > 1 {
+            self
+              .msaa_color
+              .as_ref()
+              .map(|t| surface::TextureView::from_platform(t.view_ref()))
+          } else {
+            None
+          };
+          let mut color_attachments =
+            color_attachments::RenderColorAttachments::for_surface_pass(
+              uses_color,
+              sample_count,
+              msaa_view,
+              view,
+            );
+
           // Depth/stencil attachment when either depth or stencil requested.
           let want_depth_attachment = Self::has_depth_attachment(
             pass.depth_operations(),
@@ -583,7 +621,7 @@ impl RenderContext {
 
           let mut pass_encoder = rp_builder.build(
             &mut encoder,
-            &mut color_attachments,
+            color_attachments.as_platform_attachments_mut(),
             depth_view,
             depth_ops,
             stencil_ops,

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

@@ -5,6 +5,84 @@ use super::texture::{
   TextureUsages,
 };
 
+// ---------------------------------------------------------------------------
+// TextureView
+// ---------------------------------------------------------------------------
+
+/// High-level reference to a texture view for render pass attachments.
+///
+/// This type wraps the platform `TextureViewRef` and provides a stable
+/// engine-level API for referencing texture views without exposing `wgpu`
+/// types at call sites.
+#[derive(Clone, Copy)]
+pub struct TextureView<'a> {
+  inner: platform_surface::TextureViewRef<'a>,
+}
+
+impl<'a> TextureView<'a> {
+  /// Create a high-level texture view from a platform texture view reference.
+  #[inline]
+  pub(crate) fn from_platform(
+    view: platform_surface::TextureViewRef<'a>,
+  ) -> Self {
+    return TextureView { inner: view };
+  }
+
+  /// Convert to the platform texture view reference for internal use.
+  #[inline]
+  pub(crate) fn to_platform(&self) -> platform_surface::TextureViewRef<'a> {
+    return self.inner;
+  }
+}
+
+impl<'a> std::fmt::Debug for TextureView<'a> {
+  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    return f.debug_struct("TextureView").finish_non_exhaustive();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frame
+// ---------------------------------------------------------------------------
+
+/// A single acquired frame from the presentation surface.
+///
+/// This type wraps the platform `Frame` and provides access to its texture
+/// view for rendering. The frame must be presented after rendering is complete
+/// by calling `present()`.
+pub struct Frame {
+  inner: platform_surface::Frame,
+}
+
+impl Frame {
+  /// Create a high-level frame from a platform frame.
+  #[inline]
+  pub(crate) fn from_platform(frame: platform_surface::Frame) -> Self {
+    return Frame { inner: frame };
+  }
+
+  /// Borrow the default texture view for rendering to this frame.
+  #[inline]
+  pub fn texture_view(&self) -> TextureView<'_> {
+    return TextureView::from_platform(self.inner.texture_view());
+  }
+
+  /// Present the frame to the swapchain.
+  ///
+  /// This consumes the frame and submits it for display. After calling this
+  /// method, the frame's texture is no longer valid for rendering.
+  #[inline]
+  pub fn present(self) {
+    self.inner.present();
+  }
+}
+
+impl std::fmt::Debug for Frame {
+  fn fmt(&self, frame: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    return frame.debug_struct("Frame").finish_non_exhaustive();
+  }
+}
+
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum PresentMode {
   /// Vsync enabled; frames wait for vertical blanking interval.