[refactor] instance, gpu, and render passes.

Author: vmarcella

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

@@ -10,7 +10,7 @@ use wgpu;
 
 use crate::wgpu::{
   buffer,
-  Gpu,
+  gpu::Gpu,
 };
 
 #[derive(Debug)]

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

@@ -8,7 +8,7 @@ use wgpu::{
   util::DeviceExt,
 };
 
-use crate::wgpu::Gpu;
+use crate::wgpu::gpu::Gpu;
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 /// Index format for indexed drawing.

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;
+
+#[derive(Debug)]
+/// Thin wrapper around `wgpu::CommandEncoder` with convenience helpers.
+pub struct CommandEncoder {
+  raw: wgpu::CommandEncoder,
+}
+
+#[derive(Debug)]
+/// Wrapper around `wgpu::CommandBuffer` to avoid exposing raw types upstream.
+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`.

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

@@ -1,8 +1,9 @@
 use pollster::block_on;
 
 use super::{
+  command::CommandBuffer,
+  instance::Instance,
   surface::Surface,
-  Instance,
 };
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -239,7 +240,7 @@ impl Gpu {
   /// Submit one or more command buffers to the device queue.
   pub fn submit<I>(&self, list: I)
   where
-    I: IntoIterator<Item = super::CommandBuffer>,
+    I: IntoIterator<Item = CommandBuffer>,
   {
     let iter = list.into_iter().map(|cb| cb.into_raw());
     self.queue.submit(iter);

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

@@ -0,0 +1,216 @@
+//! Instance abstractions and type wrappers to avoid leaking raw `wgpu` types
+//! at higher layers. This keeps the platform crate free to evolve with `wgpu`
+//! while presenting a stable surface to the engine.
+
+use pollster::block_on;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+/// Wrapper over `wgpu::Backends` as a bitset.
+pub struct Backends(wgpu::Backends);
+
+impl Backends {
+  /// Primary desktop backends (Vulkan/Metal/DX12) per `wgpu` defaults.
+  pub const PRIMARY: Backends = Backends(wgpu::Backends::PRIMARY);
+  /// Vulkan backend.
+  pub const VULKAN: Backends = Backends(wgpu::Backends::VULKAN);
+  /// Metal backend (macOS/iOS).
+  pub const METAL: Backends = Backends(wgpu::Backends::METAL);
+  /// DirectX 12 backend (Windows).
+  pub const DX12: Backends = Backends(wgpu::Backends::DX12);
+  /// OpenGL / WebGL backend.
+  pub const GL: Backends = Backends(wgpu::Backends::GL);
+  /// Browser WebGPU backend.
+  pub const BROWSER_WEBGPU: Backends = Backends(wgpu::Backends::BROWSER_WEBGPU);
+
+  pub(crate) fn to_wgpu(self) -> wgpu::Backends {
+    self.0
+  }
+}
+
+impl Default for Backends {
+  fn default() -> Self {
+    return Backends::PRIMARY;
+  }
+}
+
+impl std::ops::BitOr for Backends {
+  type Output = Backends;
+  fn bitor(self, rhs: Backends) -> Backends {
+    return Backends(self.0 | rhs.0);
+  }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+/// Wrapper over `wgpu::InstanceFlags` as a bitset.
+pub struct InstanceFlags(wgpu::InstanceFlags);
+
+impl InstanceFlags {
+  /// Validation flags (debugging and validation).
+  pub const VALIDATION: InstanceFlags =
+    InstanceFlags(wgpu::InstanceFlags::VALIDATION);
+  /// Enable additional debugging features where available.
+  pub const DEBUG: InstanceFlags = InstanceFlags(wgpu::InstanceFlags::DEBUG);
+
+  pub(crate) fn to_wgpu(self) -> wgpu::InstanceFlags {
+    self.0
+  }
+}
+
+impl Default for InstanceFlags {
+  fn default() -> Self {
+    return InstanceFlags(wgpu::InstanceFlags::default());
+  }
+}
+
+impl std::ops::BitOr for InstanceFlags {
+  type Output = InstanceFlags;
+  fn bitor(self, rhs: InstanceFlags) -> InstanceFlags {
+    return InstanceFlags(self.0 | rhs.0);
+  }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+/// Which DX12 shader compiler to use on Windows platforms.
+pub enum Dx12Compiler {
+  Fxc,
+}
+
+impl Dx12Compiler {
+  pub(crate) fn to_wgpu(self) -> wgpu::Dx12Compiler {
+    return match self {
+      Dx12Compiler::Fxc => wgpu::Dx12Compiler::Fxc,
+    };
+  }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+/// OpenGL ES 3 minor version (used by GL/Web targets).
+pub enum Gles3MinorVersion {
+  Automatic,
+  Version0,
+  Version1,
+  Version2,
+}
+
+impl Gles3MinorVersion {
+  pub(crate) fn to_wgpu(self) -> wgpu::Gles3MinorVersion {
+    return match self {
+      Gles3MinorVersion::Automatic => wgpu::Gles3MinorVersion::Automatic,
+      Gles3MinorVersion::Version0 => wgpu::Gles3MinorVersion::Version0,
+      Gles3MinorVersion::Version1 => wgpu::Gles3MinorVersion::Version1,
+      Gles3MinorVersion::Version2 => wgpu::Gles3MinorVersion::Version2,
+    };
+  }
+}
+
+#[derive(Debug, Clone)]
+/// Builder for creating a `wgpu::Instance` with consistent defaults.
+///
+/// Defaults to primary backends and no special flags. Options map to
+/// `wgpu::InstanceDescriptor` internally without leaking raw types.
+pub struct InstanceBuilder {
+  label: Option<String>,
+  backends: Backends,
+  flags: InstanceFlags,
+  // Keep backend options/memory thresholds internal; expose focused knobs via
+  // typed methods to avoid leaking raw structs.
+  backend_options: wgpu::BackendOptions,
+  memory_budget_thresholds: wgpu::MemoryBudgetThresholds,
+}
+
+impl InstanceBuilder {
+  /// Construct a new builder with Lambda defaults.
+  pub fn new() -> Self {
+    Self {
+      label: None,
+      backends: Backends::PRIMARY,
+      flags: InstanceFlags::default(),
+      backend_options: wgpu::BackendOptions::default(),
+      memory_budget_thresholds: wgpu::MemoryBudgetThresholds::default(),
+    }
+  }
+
+  /// Attach a debug label to the instance.
+  pub fn with_label(mut self, label: &str) -> Self {
+    self.label = Some(label.to_string());
+    self
+  }
+
+  /// Select which graphics backends to enable.
+  pub fn with_backends(mut self, backends: Backends) -> Self {
+    self.backends = backends;
+    self
+  }
+
+  /// Set additional instance flags (e.g., debugging/validation).
+  pub fn with_flags(mut self, flags: InstanceFlags) -> Self {
+    self.flags = flags;
+    self
+  }
+
+  /// Choose a DX12 shader compiler variant when on Windows.
+  pub fn with_dx12_shader_compiler(mut self, compiler: Dx12Compiler) -> Self {
+    self.backend_options.dx12.shader_compiler = compiler.to_wgpu();
+    self
+  }
+
+  /// Configure the GLES minor version for WebGL/OpenGL ES targets.
+  pub fn with_gles_minor_version(mut self, version: Gles3MinorVersion) -> Self {
+    self.backend_options.gl.gles_minor_version = version.to_wgpu();
+    self
+  }
+
+  /// Build the `Instance` wrapper from the accumulated options.
+  pub fn build(self) -> Instance {
+    let descriptor = wgpu::InstanceDescriptor {
+      backends: self.backends.to_wgpu(),
+      flags: self.flags.to_wgpu(),
+      memory_budget_thresholds: self.memory_budget_thresholds,
+      backend_options: self.backend_options,
+    };
+
+    Instance {
+      label: self.label,
+      instance: wgpu::Instance::new(&descriptor),
+    }
+  }
+}
+
+#[derive(Debug)]
+/// Thin wrapper over `wgpu::Instance` that preserves a user label and exposes
+/// a blocking `request_adapter` convenience.
+pub struct Instance {
+  pub(crate) label: Option<String>,
+  pub(crate) instance: wgpu::Instance,
+}
+
+impl Instance {
+  /// Borrow the underlying `wgpu::Instance`.
+  pub fn raw(&self) -> &wgpu::Instance {
+    &self.instance
+  }
+
+  /// Return the optional label attached at construction time.
+  pub fn label(&self) -> Option<&str> {
+    self.label.as_deref()
+  }
+
+  /// Request a compatible GPU adapter synchronously.
+  pub(crate) fn request_adapter<'surface, 'window>(
+    &self,
+    options: &wgpu::RequestAdapterOptions<'surface, 'window>,
+  ) -> Result<wgpu::Adapter, wgpu::RequestAdapterError> {
+    block_on(self.instance.request_adapter(options))
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn instance_builder_sets_label() {
+    let instance = InstanceBuilder::new().with_label("Test").build();
+    assert_eq!(instance.label(), Some("Test"));
+  }
+}