[add] vertex step mode and layout mappings.

Author: vmarcella

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

@@ -4,6 +4,7 @@ use std::ops::Range;
 
 use wgpu;
 
+pub use crate::wgpu::vertex::VertexStepMode;
 use crate::wgpu::{
   bind,
   gpu::Gpu,
@@ -81,6 +82,14 @@ pub struct VertexAttributeDesc {
   pub format: ColorFormat,
 }
 
+/// Description of a single vertex buffer layout used by a pipeline.
+#[derive(Clone, Debug)]
+struct VertexBufferLayoutDesc {
+  array_stride: u64,
+  step_mode: VertexStepMode,
+  attributes: Vec<VertexAttributeDesc>,
+}
+
 /// Compare function used for depth and stencil tests.
 #[derive(Clone, Copy, Debug)]
 pub enum CompareFunction {
@@ -301,7 +310,7 @@ impl RenderPipeline {
 pub struct RenderPipelineBuilder<'a> {
   label: Option<String>,
   layout: Option<&'a wgpu::PipelineLayout>,
-  vertex_buffers: Vec<(u64, Vec<VertexAttributeDesc>)>,
+  vertex_buffers: Vec<VertexBufferLayoutDesc>,
   cull_mode: CullingMode,
   color_target_format: Option<wgpu::TextureFormat>,
   depth_stencil: Option<wgpu::DepthStencilState>,
@@ -340,7 +349,26 @@ impl<'a> RenderPipelineBuilder<'a> {
     array_stride: u64,
     attributes: Vec<VertexAttributeDesc>,
   ) -> Self {
-    self.vertex_buffers.push((array_stride, attributes));
+    self = self.with_vertex_buffer_step_mode(
+      array_stride,
+      VertexStepMode::Vertex,
+      attributes,
+    );
+    return self;
+  }
+
+  /// Add a vertex buffer layout with attributes and an explicit step mode.
+  pub fn with_vertex_buffer_step_mode(
+    mut self,
+    array_stride: u64,
+    step_mode: VertexStepMode,
+    attributes: Vec<VertexAttributeDesc>,
+  ) -> Self {
+    self.vertex_buffers.push(VertexBufferLayoutDesc {
+      array_stride,
+      step_mode,
+      attributes,
+    });
     return self;
   }
 
@@ -431,11 +459,12 @@ impl<'a> RenderPipelineBuilder<'a> {
     // storage stable for layout lifetimes.
     let mut attr_storage: Vec<Box<[wgpu::VertexAttribute]>> = Vec::new();
     let mut strides: Vec<u64> = Vec::new();
-    for (stride, attrs) in &self.vertex_buffers {
+    let mut step_modes: Vec<VertexStepMode> = Vec::new();
+    for buffer_desc in &self.vertex_buffers {
       let mut raw_attrs: Vec<wgpu::VertexAttribute> =
-        Vec::with_capacity(attrs.len());
+        Vec::with_capacity(buffer_desc.attributes.len());
 
-      for attribute in attrs.iter() {
+      for attribute in buffer_desc.attributes.iter() {
         raw_attrs.push(wgpu::VertexAttribute {
           shader_location: attribute.shader_location,
           offset: attribute.offset,
@@ -444,15 +473,16 @@ impl<'a> RenderPipelineBuilder<'a> {
       }
       let boxed: Box<[wgpu::VertexAttribute]> = raw_attrs.into_boxed_slice();
       attr_storage.push(boxed);
-      strides.push(*stride);
+      strides.push(buffer_desc.array_stride);
+      step_modes.push(buffer_desc.step_mode);
     }
     // Now build layouts referencing the stable storage in `attr_storage`.
     let mut vbl: Vec<wgpu::VertexBufferLayout<'_>> = Vec::new();
     for (i, boxed) in attr_storage.iter().enumerate() {
       let slice = boxed.as_ref();
       vbl.push(wgpu::VertexBufferLayout {
         array_stride: strides[i],
-        step_mode: wgpu::VertexStepMode::Vertex,
+        step_mode: step_modes[i].to_wgpu(),
         attributes: slice,
       });
     }
@@ -511,3 +541,37 @@ impl<'a> RenderPipelineBuilder<'a> {
     };
   }
 }
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn vertex_step_mode_maps_to_wgpu() {
+    let vertex_mode = VertexStepMode::Vertex.to_wgpu();
+    let instance_mode = VertexStepMode::Instance.to_wgpu();
+
+    assert_eq!(vertex_mode, wgpu::VertexStepMode::Vertex);
+    assert_eq!(instance_mode, wgpu::VertexStepMode::Instance);
+  }
+
+  #[test]
+  fn with_vertex_buffer_defaults_to_per_vertex_step_mode() {
+    let builder = RenderPipelineBuilder::new().with_vertex_buffer(
+      16,
+      vec![VertexAttributeDesc {
+        shader_location: 0,
+        offset: 0,
+        format: ColorFormat::Rgb32Sfloat,
+      }],
+    );
+
+    let vertex_buffers = &builder.vertex_buffers;
+
+    assert_eq!(vertex_buffers.len(), 1);
+    assert!(matches!(
+      vertex_buffers[0].step_mode,
+      VertexStepMode::Vertex
+    ));
+  }
+}

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

@@ -26,3 +26,24 @@ impl ColorFormat {
     };
   }
 }
+
+/// Step mode applied to a vertex buffer layout.
+///
+/// `Vertex` advances attributes per vertex; `Instance` advances attributes per
+/// instance. This mirrors `wgpu::VertexStepMode` without exposing the raw
+/// dependency to higher layers.
+#[derive(Clone, Copy, Debug)]
+pub enum VertexStepMode {
+  Vertex,
+  Instance,
+}
+
+impl VertexStepMode {
+  /// Map the engine step mode to the underlying graphics API.
+  pub(crate) fn to_wgpu(self) -> wgpu::VertexStepMode {
+    return match self {
+      VertexStepMode::Vertex => wgpu::VertexStepMode::Vertex,
+      VertexStepMode::Instance => wgpu::VertexStepMode::Instance,
+    };
+  }
+}

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

@@ -45,7 +45,11 @@ use super::{
   render_pass::RenderPass,
   shader::Shader,
   texture,
-  vertex::VertexAttribute,
+  vertex::{
+    VertexAttribute,
+    VertexBufferLayout,
+    VertexStepMode,
+  },
   RenderContext,
 };
 use crate::render::validation;
@@ -106,6 +110,7 @@ pub type PushConstantUpload = (PipelineStage, Range<u32>);
 
 struct BufferBinding {
   buffer: Rc<Buffer>,
+  layout: VertexBufferLayout,
   attributes: Vec<VertexAttribute>,
 }
 
@@ -159,6 +164,15 @@ impl CullingMode {
   }
 }
 
+fn to_platform_step_mode(
+  step_mode: VertexStepMode,
+) -> platform_pipeline::VertexStepMode {
+  return match step_mode {
+    VertexStepMode::PerVertex => platform_pipeline::VertexStepMode::Vertex,
+    VertexStepMode::PerInstance => platform_pipeline::VertexStepMode::Instance,
+  };
+}
+
 /// Engine-level stencil operation.
 #[derive(Clone, Copy, Debug)]
 pub enum StencilOperation {
@@ -265,9 +279,23 @@ impl RenderPipelineBuilder {
 
   /// Declare a vertex buffer and the vertex attributes consumed by the shader.
   pub fn with_buffer(
+    self,
+    buffer: Buffer,
+    attributes: Vec<VertexAttribute>,
+  ) -> Self {
+    return self.with_buffer_step_mode(
+      buffer,
+      attributes,
+      VertexStepMode::PerVertex,
+    );
+  }
+
+  /// Declare a vertex buffer with an explicit step mode.
+  pub fn with_buffer_step_mode(
     mut self,
     buffer: Buffer,
     attributes: Vec<VertexAttribute>,
+    step_mode: VertexStepMode,
   ) -> Self {
     #[cfg(any(debug_assertions, feature = "render-validation-encoder",))]
     {
@@ -278,13 +306,32 @@ impl RenderPipelineBuilder {
         );
       }
     }
+
+    let layout = VertexBufferLayout {
+      stride: buffer.stride(),
+      step_mode,
+    };
     self.bindings.push(BufferBinding {
       buffer: Rc::new(buffer),
+      layout,
       attributes,
     });
     return self;
   }
 
+  /// Declare a per-instance vertex buffer.
+  pub fn with_instance_buffer(
+    self,
+    buffer: Buffer,
+    attributes: Vec<VertexAttribute>,
+  ) -> Self {
+    return self.with_buffer_step_mode(
+      buffer,
+      attributes,
+      VertexStepMode::PerInstance,
+    );
+  }
+
   /// Declare a push constant range for a shader stage in bytes.
   pub fn with_push_constant(
     mut self,
@@ -488,8 +535,11 @@ impl RenderPipelineBuilder {
         })
         .collect();
 
-      rp_builder =
-        rp_builder.with_vertex_buffer(binding.buffer.stride(), attributes);
+      rp_builder = rp_builder.with_vertex_buffer_step_mode(
+        binding.layout.stride,
+        to_platform_step_mode(binding.layout.step_mode),
+        attributes,
+      );
       buffers.push(binding.buffer.clone());
     }
 
@@ -594,3 +644,23 @@ impl RenderPipelineBuilder {
     };
   }
 }
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn engine_step_mode_maps_to_platform_step_mode() {
+    let per_vertex = to_platform_step_mode(VertexStepMode::PerVertex);
+    let per_instance = to_platform_step_mode(VertexStepMode::PerInstance);
+
+    assert!(matches!(
+      per_vertex,
+      platform_pipeline::VertexStepMode::Vertex
+    ));
+    assert!(matches!(
+      per_instance,
+      platform_pipeline::VertexStepMode::Instance
+    ));
+  }
+}

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

@@ -26,6 +26,28 @@ impl ColorFormat {
   }
 }
 
+/// Step mode applied to a vertex buffer layout.
+///
+/// `PerVertex` advances attributes once per vertex; `PerInstance` advances
+/// attributes once per instance. This mirrors the platform step mode without
+/// exposing backend types.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum VertexStepMode {
+  PerVertex,
+  PerInstance,
+}
+
+/// Layout for a single vertex buffer slot.
+///
+/// `stride` describes the size in bytes of one element in the buffer. The
+/// `step_mode` field determines whether attributes sourced from this buffer
+/// advance per vertex or per instance.
+#[derive(Clone, Copy, Debug)]
+pub struct VertexBufferLayout {
+  pub stride: u64,
+  pub step_mode: VertexStepMode,
+}
+
 /// A single vertex element (format + byte offset).
 #[derive(Clone, Copy, Debug)]
 ///