[add] instanced rendering validation & update specification/features document.

Author: vmarcella

crates/lambda-rs/Cargo.toml

@@ -73,6 +73,7 @@ render-validation-stencil = []
 render-validation-pass-compat = []
 render-validation-device = []
 render-validation-encoder = []
+render-instancing-validation = []
 
 
 # ---------------------------- PLATFORM DEPENDENCIES ---------------------------

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

@@ -621,12 +621,19 @@ impl RenderContext {
   {
     Self::apply_viewport(pass, &initial_viewport);
 
-    #[cfg(any(debug_assertions, feature = "render-validation-encoder",))]
+    #[cfg(any(
+      debug_assertions,
+      feature = "render-validation-encoder",
+      feature = "render-instancing-validation",
+    ))]
     let mut current_pipeline: Option<usize> = None;
 
     #[cfg(any(debug_assertions, feature = "render-validation-encoder",))]
     let mut bound_index_buffer: Option<(usize, u32)> = None;
 
+    #[cfg(any(debug_assertions, feature = "render-instancing-validation",))]
+    let mut bound_vertex_slots: HashSet<u32> = HashSet::new();
+
     // De-duplicate advisories within this pass
     #[cfg(any(
       debug_assertions,
@@ -689,8 +696,12 @@ impl RenderContext {
           }
 
           // Keep track of the current pipeline to ensure that draw calls
-          // happen only after a pipeline is set.
-          #[cfg(any(debug_assertions, feature = "render-validation-encoder",))]
+          // happen only after a pipeline is set when validation is enabled.
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-validation-encoder",
+            feature = "render-instancing-validation",
+          ))]
           {
             current_pipeline = Some(pipeline);
           }
@@ -792,6 +803,14 @@ impl RenderContext {
               ));
             })?;
 
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-instancing-validation",
+          ))]
+          {
+            bound_vertex_slots.insert(buffer);
+          }
+
           pass.set_vertex_buffer(buffer as u32, buffer_ref.raw());
         }
         RenderCommand::BindIndexBuffer { buffer, format } => {
@@ -863,14 +882,54 @@ impl RenderContext {
           vertices,
           instances,
         } => {
-          #[cfg(any(debug_assertions, feature = "render-validation-encoder",))]
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-validation-encoder",
+            feature = "render-instancing-validation",
+          ))]
           {
             if current_pipeline.is_none() {
               return Err(RenderError::Configuration(
                 "Draw command encountered before any pipeline was set in this render pass"
                   .to_string(),
               ));
             }
+
+            #[cfg(any(
+              debug_assertions,
+              feature = "render-instancing-validation",
+            ))]
+            {
+              let pipeline_index = current_pipeline.expect(
+                "current_pipeline must be set when validation is active",
+              );
+              let pipeline_ref = &self.render_pipelines[pipeline_index];
+
+              validation::validate_instance_bindings(
+                pipeline_ref.pipeline().label().unwrap_or("unnamed"),
+                pipeline_ref.per_instance_slots(),
+                &bound_vertex_slots,
+              )
+              .map_err(RenderError::Configuration)?;
+            }
+
+            if let Err(msg) =
+              validation::validate_instance_range("Draw", &instances)
+            {
+              return Err(RenderError::Configuration(msg));
+            }
+            if instances.start == instances.end {
+              #[cfg(any(
+                debug_assertions,
+                feature = "render-instancing-validation",
+              ))]
+              logging::debug!(
+                "Skipping Draw with empty instance range {}..{}",
+                instances.start,
+                instances.end
+              );
+              continue;
+            }
           }
           pass.draw(vertices, instances);
         }
@@ -914,6 +973,48 @@ impl RenderContext {
               )));
             }
           }
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-validation-encoder",
+            feature = "render-instancing-validation",
+          ))]
+          {
+            #[cfg(any(
+              debug_assertions,
+              feature = "render-instancing-validation",
+            ))]
+            {
+              let pipeline_index = current_pipeline.expect(
+                "current_pipeline must be set when validation is active",
+              );
+              let pipeline_ref = &self.render_pipelines[pipeline_index];
+
+              validation::validate_instance_bindings(
+                pipeline_ref.pipeline().label().unwrap_or("unnamed"),
+                pipeline_ref.per_instance_slots(),
+                &bound_vertex_slots,
+              )
+              .map_err(RenderError::Configuration)?;
+            }
+
+            if let Err(msg) =
+              validation::validate_instance_range("DrawIndexed", &instances)
+            {
+              return Err(RenderError::Configuration(msg));
+            }
+            if instances.start == instances.end {
+              #[cfg(any(
+                debug_assertions,
+                feature = "render-instancing-validation",
+              ))]
+              logging::debug!(
+                "Skipping DrawIndexed with empty instance range {}..{}",
+                instances.start,
+                instances.end
+              );
+              continue;
+            }
+          }
           pass.draw_indexed(indices, base_vertex, instances);
         }
         RenderCommand::BeginRenderPass { .. } => {

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

@@ -65,6 +65,7 @@ pub struct RenderPipeline {
   color_target_count: u32,
   expects_depth_stencil: bool,
   uses_stencil: bool,
+  per_instance_slots: Vec<bool>,
 }
 
 impl RenderPipeline {
@@ -100,6 +101,11 @@ impl RenderPipeline {
   pub(super) fn uses_stencil(&self) -> bool {
     return self.uses_stencil;
   }
+
+  /// Per-vertex-buffer flags indicating which slots advance per instance.
+  pub(super) fn per_instance_slots(&self) -> &Vec<bool> {
+    return &self.per_instance_slots;
+  }
 }
 
 /// Public alias for platform shader stage flags used by push constants.
@@ -519,6 +525,7 @@ impl RenderPipelineBuilder {
 
     // Vertex buffers and attributes
     let mut buffers = Vec::with_capacity(self.bindings.len());
+    let mut per_instance_slots = Vec::with_capacity(self.bindings.len());
     let mut rp_builder = platform_pipeline::RenderPipelineBuilder::new()
       .with_label(self.label.as_deref().unwrap_or("lambda-render-pipeline"))
       .with_layout(&pipeline_layout)
@@ -541,6 +548,10 @@ impl RenderPipelineBuilder {
         attributes,
       );
       buffers.push(binding.buffer.clone());
+      per_instance_slots.push(matches!(
+        binding.layout.step_mode,
+        VertexStepMode::PerInstance
+      ));
     }
 
     if fragment_module.is_some() {
@@ -641,6 +652,7 @@ impl RenderPipelineBuilder {
       // Depth/stencil is enabled when `with_depth*` was called on the builder.
       expects_depth_stencil: self.use_depth,
       uses_stencil: self.stencil.is_some(),
+      per_instance_slots,
     };
   }
 }

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

@@ -1,5 +1,10 @@
 //! Small helpers for limits and alignment validation used by the renderer.
 
+use std::{
+  collections::HashSet,
+  ops::Range,
+};
+
 /// Align `value` up to the nearest multiple of `align`.
 /// If `align` is zero, returns `value` unchanged.
 pub fn align_up(value: u64, align: u64) -> u64 {
@@ -54,6 +59,47 @@ pub fn validate_sample_count(samples: u32) -> Result<(), String> {
   }
 }
 
+/// Validate that an instance range is well-formed for a draw command.
+///
+/// The `command_name` is included in any error message to make diagnostics
+/// easier to interpret when multiple draw commands are present.
+pub fn validate_instance_range(
+  command_name: &str,
+  instances: &Range<u32>,
+) -> Result<(), String> {
+  if instances.start > instances.end {
+    return Err(format!(
+      "{} instance range start {} is greater than end {}",
+      command_name, instances.start, instances.end
+    ));
+  }
+  return Ok(());
+}
+
+/// Validate that all per-instance vertex buffer slots have been bound before
+/// issuing a draw that consumes them.
+///
+/// The `pipeline_label` identifies the pipeline in diagnostics. The
+/// `per_instance_slots` slice marks which vertex buffer slots advance once
+/// per instance, while `bound_slots` tracks the vertex buffer slots that
+/// have been bound in the current render pass.
+pub fn validate_instance_bindings(
+  pipeline_label: &str,
+  per_instance_slots: &[bool],
+  bound_slots: &HashSet<u32>,
+) -> Result<(), String> {
+  for (slot, is_instance) in per_instance_slots.iter().enumerate() {
+    if *is_instance && !bound_slots.contains(&(slot as u32)) {
+      return Err(format!(
+        "Render pipeline '{}' requires a per-instance vertex buffer bound at slot {} but no BindVertexBuffer command bound that slot in this pass",
+        pipeline_label,
+        slot
+      ));
+    }
+  }
+  return Ok(());
+}
+
 #[cfg(test)]
 mod tests {
   use super::*;
@@ -89,4 +135,47 @@ mod tests {
       .unwrap();
     assert!(err.contains("not 256-byte aligned"));
   }
+
+  #[test]
+  fn validate_instance_range_accepts_valid_ranges() {
+    assert!(validate_instance_range("Draw", &(0..1)).is_ok());
+    assert!(validate_instance_range("DrawIndexed", &(2..2)).is_ok());
+  }
+
+  #[test]
+  fn validate_instance_range_rejects_negative_length() {
+    let err = validate_instance_range("Draw", &(5..1))
+      .err()
+      .expect("must error");
+    assert!(err.contains("Draw instance range start 5 is greater than end 1"));
+  }
+
+  #[test]
+  fn validate_instance_bindings_accepts_bound_slots() {
+    let per_instance_slots = vec![true, false, true];
+    let mut bound = HashSet::new();
+    bound.insert(0);
+    bound.insert(2);
+
+    assert!(validate_instance_bindings(
+      "test-pipeline",
+      &per_instance_slots,
+      &bound
+    )
+    .is_ok());
+  }
+
+  #[test]
+  fn validate_instance_bindings_rejects_missing_slot() {
+    let per_instance_slots = vec![true, false, true];
+    let mut bound = HashSet::new();
+    bound.insert(0);
+
+    let err =
+      validate_instance_bindings("instanced", &per_instance_slots, &bound)
+        .err()
+        .expect("must error");
+    assert!(err.contains("instanced"));
+    assert!(err.contains("slot 2"));
+  }
 }

docs/features.md

@@ -3,13 +3,13 @@ title: "Cargo Features Overview"
 document_id: "features-2025-11-17"
 status: "living"
 created: "2025-11-17T23:59:00Z"
-last_updated: "2025-11-17T23:59:00Z"
-version: "0.1.0"
+last_updated: "2025-11-25T00:00:00Z"
+version: "0.1.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
 shader_backend_default: "naga"
 winit_version: "0.29.10"
-repo_commit: "70670f8ad6bb7ac14a62e7d5847bf21cfe13f665"
+repo_commit: "b1f0509d245065823dff2721f97e16c0215acc4f"
 owners: ["lambda-sh"]
 reviewers: ["engine", "rendering"]
 tags: ["guide", "features", "validation", "cargo"]
@@ -57,6 +57,10 @@ Granular features (crate: `lambda-rs`)
 - `render-validation-pass-compat`: SetPipeline-time errors when color targets or depth/stencil expectations do not match the active pass.
 - `render-validation-device`: device/format probing advisories (if available via the platform layer).
 - `render-validation-encoder`: additional per-draw/encoder-time checks; highest runtime cost.
+- `render-instancing-validation`: instance-range and per-instance buffer binding validation for `RenderCommand::Draw` and `RenderCommand::DrawIndexed`. Behavior:
+  - Validates that `instances.start <= instances.end` and treats `start == end` as a no-op (draw is skipped).
+  - Ensures that all vertex buffer slots marked as per-instance on the active pipeline have been bound in the current render pass.
+  - Adds per-draw checks proportional to the number of instanced draws and per-instance slots; SHOULD be enabled only when diagnosing instancing issues.
 
 Always-on safeguards (debug and release)
 - Clamp depth clear values to `[0.0, 1.0]`.
@@ -76,4 +80,5 @@ Usage examples
   - `cargo test -p lambda-rs --features render-validation-msaa`
 
 ## Changelog
+- 0.1.1 (2025-11-25): Document `render-instancing-validation` behavior and update metadata.
 - 0.1.0 (2025-11-17): Initial document introducing validation features and behavior by build type.

docs/specs/instanced-rendering.md

@@ -9,7 +9,7 @@ engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
 shader_backend_default: "naga"
 winit_version: "0.29.10"
-repo_commit: "84c73fbac8ce660827189fda1de96e50b5c8a9d5"
+repo_commit: "b1f0509d245065823dff2721f97e16c0215acc4f"
 owners: ["lambda-sh"]
 reviewers: ["engine", "rendering"]
 tags: ["spec", "rendering", "instancing", "vertex-input"]
@@ -302,11 +302,11 @@ App Code
   - [x] `VertexStepMode` exposed in `lambda-rs` and `lambda-rs-platform`.
   - [x] `RenderPipelineBuilder` in `lambda-rs` supports explicit per-instance
         buffers via `with_buffer_step_mode` and `with_instance_buffer`.
-  - [ ] Instancing validation feature flag defined in `lambda-rs`.
+  - [x] Instancing validation feature flag defined in `lambda-rs`.
 - Validation and Errors
   - [ ] Command ordering checks cover instanced draws.
-  - [ ] Instance range validation implemented and feature-gated.
-  - [ ] Buffer binding diagnostics cover per-instance attributes.
+  - [x] Instance range validation implemented and feature-gated.
+  - [x] Buffer binding diagnostics cover per-instance attributes.
 - Performance
   - [ ] Critical instanced draw paths reasoned about or profiled.
   - [ ] Memory usage for instance buffers characterized for example scenes.
@@ -369,6 +369,6 @@ relevant code and tests, for example in the pull request description.
 
 ## Changelog
 
-- 2025-11-25 (v0.1.2) — Update terminology to reference crates by name and remove per-file implementation locations from the Requirements Checklist.
+- 2025-11-25 (v0.1.2) — Update terminology to reference crates by name, remove per-file implementation locations from the Requirements Checklist, and mark instancing validation features as implemented in `lambda-rs`.
 - 2025-11-24 (v0.1.1) — Mark initial instancing layout and step mode support as implemented in the Requirements Checklist; metadata updated.
 - 2025-11-23 (v0.1.0) — Initial draft of instanced rendering specification.