Refactor rendering API

.ignore

@@ -1,4 +1,3 @@
-docs
 archive/lambda_cpp/vendor
 \.git
 target

crates/lambda-rs-args/src/lib.rs

@@ -36,8 +36,8 @@ pub struct ArgumentParser {
   is_subcommand: bool,
 }
 
-#[derive(Debug, Copy, Clone, PartialEq, PartialOrd)]
 /// Supported value types for an argument definition.
+#[derive(Debug, Copy, Clone, PartialEq, PartialOrd)]
 pub enum ArgumentType {
   /// `true`/`false` (or implied by presence when compiled as a flag).
   Boolean,
@@ -61,8 +61,8 @@ pub enum ArgumentType {
   DoubleList,
 }
 
-#[derive(Debug, Clone, PartialEq, PartialOrd)]
 /// Parsed value container used in results and defaults.
+#[derive(Debug, Clone, PartialEq, PartialOrd)]
 pub enum ArgumentValue {
   None,
   Boolean(bool),
@@ -112,8 +112,8 @@ impl Into<f64> for ArgumentValue {
   }
 }
 
-#[derive(Debug)]
 /// Declarative definition for a single CLI argument or positional parameter.
+#[derive(Debug)]
 pub struct Argument {
   name: String,
   description: String,
@@ -222,8 +222,8 @@ impl Argument {
   }
 }
 
-#[derive(Debug, Clone)]
 /// A single parsed argument result as `(name, value)`.
+#[derive(Debug, Clone)]
 pub struct ParsedArgument {
   name: String,
   value: ArgumentValue,
@@ -830,8 +830,8 @@ fn parse_value(arg: &Argument, raw: &str) -> Result<ArgumentValue, ArgsError> {
   }
 }
 
-#[derive(Debug)]
 /// Errors that may occur during argument parsing.
+#[derive(Debug)]
 pub enum ArgsError {
   /// An unknown flag or option was encountered.
   UnknownArgument(String),

crates/lambda-rs-platform/src/lib.rs

@@ -5,6 +5,10 @@
 //! (graphics) that provide consistent defaults and ergonomic builders, along
 //! with shader compilation backends and small helper modules (e.g., OBJ
 //! loading and random number generation).
+//!
+//! Stability: this is an internal support layer for `lambda-rs`. Public
+//! types are exposed as a convenience to the higher‑level crate and MAY change
+//! between releases to fit engine needs.
 pub mod obj;
 pub mod rand;
 pub mod shader;

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

@@ -6,10 +6,15 @@
 
 use std::num::NonZeroU64;
 
-use crate::wgpu::types as wgpu;
+use wgpu;
+
+use crate::wgpu::{
+  buffer,
+  gpu::Gpu,
+};
 
-#[derive(Debug)]
 /// Wrapper around `wgpu::BindGroupLayout` that preserves a label.
+#[derive(Debug)]
 pub struct BindGroupLayout {
   pub(crate) raw: wgpu::BindGroupLayout,
   pub(crate) label: Option<String>,
@@ -27,8 +32,8 @@ impl BindGroupLayout {
   }
 }
 
-#[derive(Debug)]
 /// Wrapper around `wgpu::BindGroup` that preserves a label.
+#[derive(Debug)]
 pub struct BindGroup {
   pub(crate) raw: wgpu::BindGroup,
   pub(crate) label: Option<String>,
@@ -46,8 +51,8 @@ impl BindGroup {
   }
 }
 
-#[derive(Clone, Copy, Debug)]
 /// Visibility of a binding across shader stages.
+#[derive(Clone, Copy, Debug)]
 pub enum Visibility {
   Vertex,
   Fragment,
@@ -94,8 +99,8 @@ mod tests {
   }
 }
 
-#[derive(Default)]
 /// Builder for creating a `wgpu::BindGroupLayout`.
+#[derive(Default)]
 pub struct BindGroupLayoutBuilder {
   label: Option<String>,
   entries: Vec<wgpu::BindGroupLayoutEntry>,
@@ -151,21 +156,23 @@ impl BindGroupLayoutBuilder {
   }
 
   /// Build the layout using the provided device.
-  pub fn build(self, device: &wgpu::Device) -> BindGroupLayout {
+  pub fn build(self, gpu: &Gpu) -> BindGroupLayout {
     let raw =
-      device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
-        label: self.label.as_deref(),
-        entries: &self.entries,
-      });
+      gpu
+        .device()
+        .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+          label: self.label.as_deref(),
+          entries: &self.entries,
+        });
     return BindGroupLayout {
       raw,
       label: self.label,
     };
   }
 }
 
-#[derive(Default)]
 /// Builder for creating a `wgpu::BindGroup`.
+#[derive(Default)]
 pub struct BindGroupBuilder<'a> {
   label: Option<String>,
   layout: Option<&'a wgpu::BindGroupLayout>,
@@ -198,14 +205,14 @@ impl<'a> BindGroupBuilder<'a> {
   pub fn with_uniform(
     mut self,
     binding: u32,
-    buffer: &'a wgpu::Buffer,
+    buffer: &'a buffer::Buffer,
     offset: u64,
     size: Option<NonZeroU64>,
   ) -> Self {
     self.entries.push(wgpu::BindGroupEntry {
       binding,
       resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
-        buffer,
+        buffer: buffer.raw(),
         offset,
         size,
       }),
@@ -214,11 +221,11 @@ impl<'a> BindGroupBuilder<'a> {
   }
 
   /// Build the bind group with the accumulated entries.
-  pub fn build(self, device: &wgpu::Device) -> BindGroup {
+  pub fn build(self, gpu: &Gpu) -> BindGroup {
     let layout = self
       .layout
       .expect("BindGroupBuilder requires a layout before build");
-    let raw = device.create_bind_group(&wgpu::BindGroupDescriptor {
+    let raw = gpu.device().create_bind_group(&wgpu::BindGroupDescriptor {
       label: self.label.as_deref(),
       layout,
       entries: &self.entries,

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

@@ -3,14 +3,31 @@
 //! 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,
+use wgpu::{
+  self,
+  util::DeviceExt,
 };
 
-#[derive(Clone, Copy, Debug)]
+use crate::wgpu::gpu::Gpu;
+
+/// Index format for indexed drawing.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum IndexFormat {
+  Uint16,
+  Uint32,
+}
+
+impl IndexFormat {
+  pub(crate) fn to_wgpu(self) -> wgpu::IndexFormat {
+    return match self {
+      IndexFormat::Uint16 => wgpu::IndexFormat::Uint16,
+      IndexFormat::Uint32 => wgpu::IndexFormat::Uint32,
+    };
+  }
+}
+
 /// Platform buffer usage flags.
+#[derive(Clone, Copy, Debug)]
 pub struct Usage(pub(crate) wgpu::BufferUsages);
 
 impl Usage {
@@ -43,8 +60,8 @@ impl Default for Usage {
   }
 }
 
-#[derive(Debug)]
 /// Wrapper around `wgpu::Buffer` with metadata.
+#[derive(Debug)]
 pub struct Buffer {
   pub(crate) raw: wgpu::Buffer,
   pub(crate) label: Option<String>,
@@ -54,7 +71,7 @@ pub struct Buffer {
 
 impl Buffer {
   /// Borrow the underlying `wgpu::Buffer`.
-  pub fn raw(&self) -> &wgpu::Buffer {
+  pub(crate) fn raw(&self) -> &wgpu::Buffer {
     return &self.raw;
   }
 
@@ -64,18 +81,23 @@ impl Buffer {
   }
 
   /// Size in bytes at creation time.
-  pub fn size(&self) -> wgpu::BufferAddress {
+  pub fn size(&self) -> u64 {
     return self.size;
   }
 
   /// Usage flags used to create the buffer.
-  pub fn usage(&self) -> wgpu::BufferUsages {
-    return self.usage;
+  pub fn usage(&self) -> Usage {
+    return Usage(self.usage);
+  }
+
+  /// Write raw bytes into the buffer at the given offset.
+  pub fn write_bytes(&self, gpu: &Gpu, offset: u64, data: &[u8]) {
+    gpu.queue().write_buffer(&self.raw, offset, data);
   }
 }
 
-#[derive(Default)]
 /// Builder for creating a `Buffer` with optional initial contents.
+#[derive(Default)]
 pub struct BufferBuilder {
   label: Option<String>,
   size: usize,
@@ -119,7 +141,7 @@ impl BufferBuilder {
   }
 
   /// Create a buffer initialized with `contents`.
-  pub fn build_init(self, device: &wgpu::Device, contents: &[u8]) -> Buffer {
+  pub fn build_init(self, gpu: &Gpu, contents: &[u8]) -> Buffer {
     let size = if self.size == 0 {
       contents.len()
     } else {
@@ -131,11 +153,14 @@ impl BufferBuilder {
       usage |= wgpu::BufferUsages::COPY_DST;
     }
 
-    let raw = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
-      label: self.label.as_deref(),
-      contents,
-      usage,
-    });
+    let raw =
+      gpu
+        .device()
+        .create_buffer_init(&wgpu::util::BufferInitDescriptor {
+          label: self.label.as_deref(),
+          contents,
+          usage,
+        });
 
     return Buffer {
       raw,

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

@@ -0,0 +1,50 @@
+//! Command encoding abstractions around `wgpu::CommandEncoder`, `wgpu::RenderPass`,
+//! and `wgpu::CommandBuffer` that expose only the operations needed by the
+//! engine while keeping raw `wgpu` types crate-internal.
+
+use super::gpu;
+
+/// Thin wrapper around `wgpu::CommandEncoder` with convenience helpers.
+#[derive(Debug)]
+pub struct CommandEncoder {
+  raw: wgpu::CommandEncoder,
+}
+
+/// Wrapper around `wgpu::CommandBuffer` to avoid exposing raw types upstream.
+#[derive(Debug)]
+pub struct CommandBuffer {
+  raw: wgpu::CommandBuffer,
+}
+
+impl CommandBuffer {
+  pub(crate) fn into_raw(self) -> wgpu::CommandBuffer {
+    self.raw
+  }
+}
+
+impl CommandEncoder {
+  /// Create a new command encoder with an optional label.
+  pub fn new(gpu: &gpu::Gpu, label: Option<&str>) -> Self {
+    let raw = gpu
+      .device()
+      .create_command_encoder(&wgpu::CommandEncoderDescriptor { label });
+    return Self { raw };
+  }
+
+  /// Internal helper for beginning a render pass. Used by the render pass builder.
+  pub(crate) fn begin_render_pass_raw<'view>(
+    &'view mut self,
+    desc: &wgpu::RenderPassDescriptor<'view>,
+  ) -> wgpu::RenderPass<'view> {
+    return self.raw.begin_render_pass(desc);
+  }
+
+  /// Finish recording and return the command buffer.
+  pub fn finish(self) -> CommandBuffer {
+    return CommandBuffer {
+      raw: self.raw.finish(),
+    };
+  }
+}
+
+// RenderPass wrapper and its methods now live under `wgpu::render_pass`.