[add] features to optionally enable validation checks in production builds.

Author: vmarcella

crates/lambda-rs/Cargo.toml

@@ -37,6 +37,43 @@ with-shaderc-build-from-source=[
   "lambda-rs-platform/shader-backend-shaderc-build-from-source",
 ]
 
+# ------------------------------ RENDER VALIDATION -----------------------------
+# Granular, opt-in validation flags for release builds. Debug builds enable
+# all validations unconditionally via `debug_assertions`.
+
+# Umbrella features
+# - render-validation: enable common, configuration-time checks and logs
+# - render-validation-strict: includes render-validation + per-draw checks
+# - render-validation-all: enables all validations including device probing
+render-validation = [
+  "render-validation-msaa",
+  "render-validation-depth",
+  "render-validation-stencil",
+]
+render-validation-strict = [
+  "render-validation",
+  "render-validation-pass-compat",
+  "render-validation-encoder",
+]
+render-validation-all = [
+  "render-validation-strict",
+  "render-validation-device",
+]
+
+# Granular feature flags
+# - msaa: sample count validity and mismatch logging
+# - depth: depth clear clamping log and depth advisories
+# - stencil: stencil/format upgrade advisories
+# - pass-compat: color/depth presence compatibility checks at SetPipeline
+# - device: device/format probing advisories (may consult platform)
+# - encoder: per-draw/encoder-time checks (most expensive)
+render-validation-msaa = []
+render-validation-depth = []
+render-validation-stencil = []
+render-validation-pass-compat = []
+render-validation-device = []
+render-validation-encoder = []
+
 
 # ---------------------------- PLATFORM DEPENDENCIES ---------------------------
 

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

@@ -471,7 +471,10 @@ impl RenderContext {
               && self.depth_format
                 != platform::texture::DepthFormat::Depth24PlusStencil8
             {
-              #[cfg(debug_assertions)]
+              #[cfg(any(
+                debug_assertions,
+                feature = "render-validation-stencil",
+              ))]
               logging::error!(
                 "Render pass has stencil ops but depth format {:?} lacks stencil; upgrading to Depth24PlusStencil8",
                 self.depth_format
@@ -601,10 +604,18 @@ impl RenderContext {
     I: Iterator<Item = RenderCommand>,
   {
     Self::apply_viewport(pass, &initial_viewport);
-    // De-duplicate advisories within this pass (debug builds only)
-    #[cfg(debug_assertions)]
+    // De-duplicate advisories within this pass
+    #[cfg(any(
+      debug_assertions,
+      feature = "render-validation-depth",
+      feature = "render-validation-stencil",
+    ))]
     let mut warned_no_stencil_for_pipeline: HashSet<usize> = HashSet::new();
-    #[cfg(debug_assertions)]
+    #[cfg(any(
+      debug_assertions,
+      feature = "render-validation-depth",
+      feature = "render-validation-stencil",
+    ))]
     let mut warned_no_depth_for_pipeline: HashSet<usize> = HashSet::new();
 
     while let Some(command) = commands.next() {
@@ -620,8 +631,12 @@ impl RenderContext {
                 "Unknown pipeline {pipeline}"
               ));
             })?;
-          // Validate pass/pipeline compatibility before deferring to the platform (debug only).
-          #[cfg(debug_assertions)]
+          // Validate pass/pipeline compatibility before deferring to the platform.
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-validation-pass-compat",
+            feature = "render-validation-encoder",
+          ))]
           {
             if !uses_color && pipeline_ref.has_color_targets() {
               let label = pipeline_ref.pipeline().label().unwrap_or("unnamed");
@@ -645,8 +660,12 @@ impl RenderContext {
               )));
             }
           }
-          // Advisory checks to help reason about stencil/depth behavior (debug only).
-          #[cfg(debug_assertions)]
+          // Advisory checks to help reason about stencil/depth behavior.
+          #[cfg(any(
+            debug_assertions,
+            feature = "render-validation-depth",
+            feature = "render-validation-stencil",
+          ))]
           {
             if pass_has_stencil
               && !pipeline_ref.uses_stencil()

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

@@ -316,26 +316,20 @@ impl RenderPipelineBuilder {
 
   /// Configure multi-sampling for this pipeline.
   pub fn with_multi_sample(mut self, samples: u32) -> Self {
-    #[cfg(debug_assertions)]
-    {
-      match validation::validate_sample_count(samples) {
-        Ok(()) => {
-          self.sample_count = samples;
-        }
-        Err(msg) => {
+    // Always apply a cheap validity check; log under feature/debug gates.
+    if matches!(samples, 1 | 2 | 4 | 8) {
+      self.sample_count = samples;
+    } else {
+      #[cfg(any(debug_assertions, feature = "render-validation-msaa",))]
+      {
+        if let Err(msg) = validation::validate_sample_count(samples) {
           logging::error!(
             "{}; falling back to sample_count=1 for pipeline",
             msg
           );
-          self.sample_count = 1;
         }
       }
-    }
-    #[cfg(not(debug_assertions))]
-    {
-      // In release builds, accept the provided sample count without extra
-      // engine-level validation. Platform validation MAY still apply.
-      self.sample_count = samples;
+      self.sample_count = 1;
     }
     return self;
   }
@@ -463,7 +457,7 @@ impl RenderPipelineBuilder {
       if self.stencil.is_some()
         && dfmt != texture::DepthFormat::Depth24PlusStencil8
       {
-        #[cfg(debug_assertions)]
+        #[cfg(any(debug_assertions, feature = "render-validation-stencil",))]
         logging::error!(
           "Stencil configured but depth format {:?} lacks stencil; upgrading to Depth24PlusStencil8",
           dfmt
@@ -486,23 +480,24 @@ impl RenderPipelineBuilder {
     }
 
     // Apply multi-sampling to the pipeline.
-    // In debug builds, validate and align with the render pass; in release,
-    // defer to platform validation without engine-side checks.
+    // Always align to the pass sample count; gate logs.
     let mut pipeline_samples = self.sample_count;
-    #[cfg(debug_assertions)]
-    {
-      let pass_samples = _render_pass.sample_count();
-      if pipeline_samples != pass_samples {
-        logging::error!(
-          "Pipeline sample_count={} does not match pass sample_count={}; aligning to pass",
-          pipeline_samples,
-          pass_samples
-        );
-        pipeline_samples = pass_samples;
-      }
-      if validation::validate_sample_count(pipeline_samples).is_err() {
-        pipeline_samples = 1;
+    let pass_samples = _render_pass.sample_count();
+    if pipeline_samples != pass_samples {
+      #[cfg(any(debug_assertions, feature = "render-validation-msaa",))]
+      logging::error!(
+        "Pipeline sample_count={} does not match pass sample_count={}; aligning to pass",
+        pipeline_samples,
+        pass_samples
+      );
+      pipeline_samples = pass_samples;
+    }
+    if !matches!(pipeline_samples, 1 | 2 | 4 | 8) {
+      #[cfg(any(debug_assertions, feature = "render-validation-msaa",))]
+      {
+        let _ = validation::validate_sample_count(pipeline_samples);
       }
+      pipeline_samples = 1;
     }
     rp_builder = rp_builder.with_sample_count(pipeline_samples);
 

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

@@ -201,8 +201,21 @@ impl RenderPassBuilder {
 
   /// Enable a depth attachment with an explicit clear value.
   pub fn with_depth_clear(mut self, clear: f64) -> Self {
+    // Clamp to the valid range [0.0, 1.0] unconditionally.
+    let clamped = clear.clamp(0.0, 1.0);
+    // Optionally log when clamping is applied.
+    #[cfg(any(debug_assertions, feature = "render-validation-depth",))]
+    {
+      if (clamped - clear).abs() > f64::EPSILON {
+        logging::warn!(
+          "Depth clear value {} out of range [0,1]; clamped to {}",
+          clear,
+          clamped
+        );
+      }
+    }
     self.depth_operations = Some(DepthOperations {
-      load: DepthLoadOp::Clear(clear),
+      load: DepthLoadOp::Clear(clamped),
       store: StoreOp::Store,
     });
     return self;
@@ -243,26 +256,21 @@ impl RenderPassBuilder {
 
   /// Configure multi-sample anti-aliasing for this pass.
   pub fn with_multi_sample(mut self, samples: u32) -> Self {
-    #[cfg(debug_assertions)]
-    {
-      match validation::validate_sample_count(samples) {
-        Ok(()) => {
-          self.sample_count = samples;
-        }
-        Err(msg) => {
+    // Always apply a cheap validity check; log under feature/debug gates.
+    let allowed = matches!(samples, 1 | 2 | 4 | 8);
+    if allowed {
+      self.sample_count = samples;
+    } else {
+      #[cfg(any(debug_assertions, feature = "render-validation-msaa",))]
+      {
+        if let Err(msg) = validation::validate_sample_count(samples) {
           logging::error!(
             "{}; falling back to sample_count=1 for render pass",
             msg
           );
-          self.sample_count = 1;
         }
       }
-    }
-    #[cfg(not(debug_assertions))]
-    {
-      // In release builds, accept the provided sample count without engine
-      // validation; platform validation MAY still apply.
-      self.sample_count = samples;
+      self.sample_count = 1;
     }
     return self;
   }