[add] buffer abstraction and replace direct wgpu usage in lambda-rs.

Author: vmarcella

crates/lambda-rs-platform/src/wgpu/buffer.rs

@@ -0,0 +1,161 @@
+//! Buffer wrappers and builders for the platform layer.
+//!
+//! This module provides a thin wrapper over `wgpu::Buffer` plus a small
+//! builder that handles common initialization patterns and keeps label and
+//! usage metadata for debugging/inspection.
+
+use crate::wgpu::{
+  types as wgpu,
+  types::util::DeviceExt,
+};
+
+#[derive(Clone, Copy, Debug)]
+/// Platform buffer usage flags.
+pub struct Usage(pub(crate) wgpu::BufferUsages);
+
+impl Usage {
+  /// Vertex buffer usage.
+  pub const VERTEX: Usage = Usage(wgpu::BufferUsages::VERTEX);
+  /// Index buffer usage.
+  pub const INDEX: Usage = Usage(wgpu::BufferUsages::INDEX);
+  /// Uniform buffer usage.
+  pub const UNIFORM: Usage = Usage(wgpu::BufferUsages::UNIFORM);
+  /// Storage buffer usage.
+  pub const STORAGE: Usage = Usage(wgpu::BufferUsages::STORAGE);
+  /// Copy destination (for CPU-visible uploads).
+  pub const COPY_DST: Usage = Usage(wgpu::BufferUsages::COPY_DST);
+
+  pub(crate) fn to_wgpu(self) -> wgpu::BufferUsages {
+    return self.0;
+  }
+}
+
+impl std::ops::BitOr for Usage {
+  type Output = Usage;
+  fn bitor(self, rhs: Usage) -> Usage {
+    return Usage(self.0 | rhs.0);
+  }
+}
+
+impl Default for Usage {
+  fn default() -> Self {
+    return Usage(wgpu::BufferUsages::VERTEX);
+  }
+}
+
+#[derive(Debug)]
+/// Wrapper around `wgpu::Buffer` with metadata.
+pub struct Buffer {
+  pub(crate) raw: wgpu::Buffer,
+  pub(crate) label: Option<String>,
+  pub(crate) size: wgpu::BufferAddress,
+  pub(crate) usage: wgpu::BufferUsages,
+}
+
+impl Buffer {
+  /// Borrow the underlying `wgpu::Buffer`.
+  pub fn raw(&self) -> &wgpu::Buffer {
+    return &self.raw;
+  }
+
+  /// Optional debug label.
+  pub fn label(&self) -> Option<&str> {
+    return self.label.as_deref();
+  }
+
+  /// Size in bytes at creation time.
+  pub fn size(&self) -> wgpu::BufferAddress {
+    return self.size;
+  }
+
+  /// Usage flags used to create the buffer.
+  pub fn usage(&self) -> wgpu::BufferUsages {
+    return self.usage;
+  }
+}
+
+#[derive(Default)]
+/// Builder for creating a `Buffer` with optional initial contents.
+pub struct BufferBuilder {
+  label: Option<String>,
+  size: usize,
+  usage: Usage,
+  cpu_visible: bool,
+}
+
+impl BufferBuilder {
+  /// Create a new builder with zero size and VERTEX usage.
+  pub fn new() -> Self {
+    return Self {
+      label: None,
+      size: 0,
+      usage: Usage::VERTEX,
+      cpu_visible: false,
+    };
+  }
+
+  /// Attach a label for debugging/profiling.
+  pub fn with_label(mut self, label: &str) -> Self {
+    self.label = Some(label.to_string());
+    return self;
+  }
+
+  /// Set the total size in bytes. If zero, size is inferred from data length.
+  pub fn with_size(mut self, size: usize) -> Self {
+    self.size = size;
+    return self;
+  }
+
+  /// Set usage flags.
+  pub fn with_usage(mut self, usage: Usage) -> Self {
+    self.usage = usage;
+    return self;
+  }
+
+  /// Hint that buffer will be updated from CPU via queue writes.
+  pub fn with_cpu_visible(mut self, cpu_visible: bool) -> Self {
+    self.cpu_visible = cpu_visible;
+    return self;
+  }
+
+  /// Create a buffer initialized with `contents`.
+  pub fn build_init(self, device: &wgpu::Device, contents: &[u8]) -> Buffer {
+    let size = if self.size == 0 {
+      contents.len()
+    } else {
+      self.size
+    };
+
+    let mut usage = self.usage.to_wgpu();
+    if self.cpu_visible {
+      usage |= wgpu::BufferUsages::COPY_DST;
+    }
+
+    let raw = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
+      label: self.label.as_deref(),
+      contents,
+      usage,
+    });
+
+    return Buffer {
+      raw,
+      label: self.label,
+      size: size as wgpu::BufferAddress,
+      usage,
+    };
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn usage_bitor_combines_flags() {
+    let u = Usage::VERTEX | Usage::INDEX | Usage::UNIFORM;
+    let flags = u.to_wgpu();
+    assert!(flags.contains(wgpu::BufferUsages::VERTEX));
+    assert!(flags.contains(wgpu::BufferUsages::INDEX));
+    assert!(flags.contains(wgpu::BufferUsages::UNIFORM));
+  }
+}

crates/lambda-rs-platform/src/wgpu/mod.rs

@@ -16,6 +16,7 @@ use wgpu::rwh::{
 use crate::winit::WindowHandle;
 
 pub mod bind;
+pub mod buffer;
 
 #[derive(Debug, Clone)]
 /// Builder for creating a `wgpu::Instance` with consistent defaults.

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

@@ -2,9 +2,9 @@
 
 use std::rc::Rc;
 
-use lambda_platform::wgpu::types::{
-  self as wgpu,
-  util::DeviceExt,
+use lambda_platform::wgpu::{
+  buffer as platform_buffer,
+  types as wgpu,
 };
 
 use super::{
@@ -26,22 +26,20 @@ pub enum BufferType {
 }
 
 #[derive(Clone, Copy, Debug)]
-/// A thin newtype for `wgpu::BufferUsages` that supports bitwise ops while
-/// keeping explicit construction points in the API surface.
-pub struct Usage(wgpu::BufferUsages);
+/// Buffer usage flags (engine-facing), mapped to platform usage internally.
+pub struct Usage(platform_buffer::Usage);
 
 impl Usage {
   /// Mark buffer usable as a vertex buffer.
-  pub const VERTEX: Usage = Usage(wgpu::BufferUsages::VERTEX);
+  pub const VERTEX: Usage = Usage(platform_buffer::Usage::VERTEX);
   /// Mark buffer usable as an index buffer.
-  pub const INDEX: Usage = Usage(wgpu::BufferUsages::INDEX);
+  pub const INDEX: Usage = Usage(platform_buffer::Usage::INDEX);
   /// Mark buffer usable as a uniform buffer.
-  pub const UNIFORM: Usage = Usage(wgpu::BufferUsages::UNIFORM);
+  pub const UNIFORM: Usage = Usage(platform_buffer::Usage::UNIFORM);
   /// Mark buffer usable as a storage buffer.
-  pub const STORAGE: Usage = Usage(wgpu::BufferUsages::STORAGE);
+  pub const STORAGE: Usage = Usage(platform_buffer::Usage::STORAGE);
 
-  /// Extract the inner `wgpu` flags.
-  pub fn to_wgpu(self) -> wgpu::BufferUsages {
+  fn to_platform(self) -> platform_buffer::Usage {
     self.0
   }
 }
@@ -50,7 +48,7 @@ impl std::ops::BitOr for Usage {
   type Output = Usage;
 
   fn bitor(self, rhs: Usage) -> Usage {
-    Usage(self.0 | rhs.0)
+    return Usage(self.0 | rhs.0);
   }
 }
 
@@ -90,8 +88,8 @@ impl Default for Properties {
 /// when binding to pipeline inputs.
 #[derive(Debug)]
 pub struct Buffer {
-  buffer: Rc<wgpu::Buffer>,
-  stride: wgpu::BufferAddress,
+  buffer: Rc<platform_buffer::Buffer>,
+  stride: u64,
   buffer_type: BufferType,
 }
 
@@ -101,14 +99,10 @@ impl Buffer {
   pub fn destroy(self, _render_context: &RenderContext) {}
 
   pub(super) fn raw(&self) -> &wgpu::Buffer {
-    return self.buffer.as_ref();
+    return self.buffer.raw();
   }
 
-  pub(super) fn raw_rc(&self) -> Rc<wgpu::Buffer> {
-    return self.buffer.clone();
-  }
-
-  pub(super) fn stride(&self) -> wgpu::BufferAddress {
+  pub(super) fn stride(&self) -> u64 {
     return self.stride;
   }
 
@@ -244,7 +238,6 @@ impl BufferBuilder {
     render_context: &mut RenderContext,
     data: Vec<Data>,
   ) -> Result<Buffer, &'static str> {
-    let device = render_context.device();
     let element_size = std::mem::size_of::<Data>();
     let buffer_length = if self.buffer_length == 0 {
       element_size * data.len()
@@ -266,20 +259,19 @@ impl BufferBuilder {
       )
     };
 
-    let mut usage = self.usage.to_wgpu();
-    if self.properties.cpu_visible() {
-      usage |= wgpu::BufferUsages::COPY_DST;
+    let mut builder = platform_buffer::BufferBuilder::new()
+      .with_size(buffer_length)
+      .with_usage(self.usage.to_platform())
+      .with_cpu_visible(self.properties.cpu_visible());
+    if let Some(label) = &self.label {
+      builder = builder.with_label(label);
     }
 
-    let buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
-      label: self.label.as_deref(),
-      contents: bytes,
-      usage,
-    });
+    let buffer = builder.build_init(render_context.device(), bytes);
 
     return Ok(Buffer {
       buffer: Rc::new(buffer),
-      stride: element_size as wgpu::BufferAddress,
+      stride: element_size as u64,
       buffer_type: self.buffer_type,
     });
   }