[add] new module targets for implementing explicit render targets (surface & offscreen)

Author: vmarcella

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

@@ -25,7 +25,7 @@ use lambda_platform::wgpu as platform;
 
 use super::{
   instance::Instance,
-  render_target::WindowSurface,
+  targets::surface::WindowSurface,
   texture::{
     DepthFormat,
     TextureFormat,

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

@@ -38,11 +38,10 @@ pub mod instance;
 pub mod mesh;
 pub mod pipeline;
 pub mod render_pass;
-pub mod render_target;
 pub mod scene_math;
 pub mod shader;
 pub mod surface;
-pub mod target;
+pub mod targets;
 pub mod texture;
 pub mod validation;
 pub mod vertex;
@@ -71,7 +70,7 @@ use self::{
   },
   pipeline::RenderPipeline,
   render_pass::RenderPass as RenderPassDesc,
-  render_target::RenderTarget,
+  targets::surface::RenderTarget,
 };
 
 /// Builder for configuring a `RenderContext` tied to one window.
@@ -127,13 +126,13 @@ impl RenderContextBuilder {
       .with_label(&format!("{} Instance", name))
       .build();
 
-    let mut surface = render_target::WindowSurface::new(&instance, window)
+    let mut surface = targets::surface::WindowSurface::new(&instance, window)
       .map_err(|e| {
-        RenderContextError::SurfaceCreate(format!(
-          "Failed to create rendering surface: {:?}",
-          e
-        ))
-      })?;
+      RenderContextError::SurfaceCreate(format!(
+        "Failed to create rendering surface: {:?}",
+        e
+      ))
+    })?;
 
     let gpu = gpu::GpuBuilder::new()
       .with_label(&format!("{} Device", name))
@@ -225,7 +224,7 @@ impl RenderContextBuilder {
 pub struct RenderContext {
   label: String,
   instance: instance::Instance,
-  surface: render_target::WindowSurface,
+  surface: targets::surface::WindowSurface,
   gpu: gpu::Gpu,
   config: surface::SurfaceConfig,
   texture_usage: texture::TextureUsages,
@@ -235,7 +234,7 @@ pub struct RenderContext {
   depth_sample_count: u32,
   msaa_color: Option<texture::ColorAttachmentTexture>,
   msaa_sample_count: u32,
-  offscreen_targets: Vec<target::OffscreenTarget>,
+  offscreen_targets: Vec<targets::offscreen::OffscreenTarget>,
   render_passes: Vec<RenderPassDesc>,
   render_pipelines: Vec<RenderPipeline>,
   bind_group_layouts: Vec<bind::BindGroupLayout>,
@@ -276,7 +275,7 @@ impl RenderContext {
   /// Attach an offscreen target and return a handle for use in destinations.
   pub fn attach_offscreen_target(
     &mut self,
-    target: target::OffscreenTarget,
+    target: targets::offscreen::OffscreenTarget,
   ) -> ResourceId {
     let id = self.offscreen_targets.len();
     self.offscreen_targets.push(target);
@@ -290,7 +289,7 @@ impl RenderContext {
   pub fn replace_offscreen_target(
     &mut self,
     id: ResourceId,
-    target: target::OffscreenTarget,
+    target: targets::offscreen::OffscreenTarget,
   ) -> Result<(), String> {
     let slot = match self.offscreen_targets.get_mut(id) {
       Some(slot) => slot,
@@ -411,7 +410,7 @@ impl RenderContext {
   pub fn get_offscreen_target(
     &self,
     id: ResourceId,
-  ) -> &target::OffscreenTarget {
+  ) -> &targets::offscreen::OffscreenTarget {
     return &self.offscreen_targets[id];
   }
 
@@ -780,17 +779,6 @@ impl RenderContext {
       ));
     }
 
-    #[cfg(any(debug_assertions, feature = "render-validation-render-targets",))]
-    {
-      if target.defaulted_from_surface_size() && target.size() != self.size {
-        logging::warn!(
-          "Offscreen target size {:?} does not match surface size {:?}; rebuild the target to match the new surface size",
-          target.size(),
-          self.size
-        );
-      }
-    }
-
     let depth_texture_ref = if want_depth_attachment {
       target.depth_texture()
     } else {

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

@@ -0,0 +1,8 @@
+//! Render targets for surface presentation and offscreen rendering.
+//!
+//! This module owns the engine-level APIs for:
+//! - Surface presentation (`targets::surface`)
+//! - Offscreen render-to-texture (`targets::offscreen`)
+
+pub mod offscreen;
+pub mod surface;

crates/lambda-rs/src/render/target.rs …ambda-rs/src/render/targets/offscreen.rscrates/lambda-rs/src/render/target.rs renamed to crates/lambda-rs/src/render/targets/offscreen.rs crates/lambda-rs/src/render/target.rs renamed to crates/lambda-rs/src/render/targets/offscreen.rs

@@ -3,14 +3,13 @@
 //! Provides `OffscreenTarget` and `OffscreenTargetBuilder` for render‑to‑texture
 //! workflows without exposing platform texture types at call sites.
 
-use logging;
-
-use super::{
+use crate::render::{
+  gpu::Gpu,
   surface,
   texture,
+  validation,
   RenderContext,
 };
-use crate::render::validation;
 
 #[derive(Debug)]
 /// Offscreen render target with color and optional depth attachments.
@@ -27,7 +26,6 @@ pub struct OffscreenTarget {
   depth_format: Option<texture::DepthFormat>,
   sample_count: u32,
   label: Option<String>,
-  defaulted_from_surface_size: bool,
 }
 
 impl OffscreenTarget {
@@ -81,10 +79,6 @@ impl OffscreenTarget {
     return self.label.as_deref();
   }
 
-  pub(crate) fn defaulted_from_surface_size(&self) -> bool {
-    return self.defaulted_from_surface_size;
-  }
-
   /// Explicitly destroy this render target.
   ///
   /// Dropping the value also releases the underlying GPU resources; this
@@ -97,7 +91,7 @@ impl OffscreenTarget {
 pub enum OffscreenTargetError {
   /// Color attachment was not configured.
   MissingColorAttachment,
-  /// Width or height was zero after resolving defaults.
+  /// Width or height was zero.
   InvalidSize { width: u32, height: u32 },
   /// Sample count is not supported for the chosen format or device limits.
   UnsupportedSampleCount { requested: u32 },
@@ -131,10 +125,6 @@ impl OffscreenTargetBuilder {
   }
 
   /// Configure the color attachment format and size.
-  ///
-  /// When `width` or `height` is zero, the builder falls back to the current
-  /// `RenderContext` surface size during `build`. A resolved size of zero in
-  /// either dimension is treated as an error.
   pub fn with_color(
     mut self,
     format: texture::TextureFormat,
@@ -154,7 +144,6 @@ impl OffscreenTargetBuilder {
   }
 
   /// Configure multi‑sampling for this target.
-  ///
   pub fn with_multi_sample(mut self, samples: u32) -> Self {
     self.sample_count = samples.max(1);
     return self;
@@ -169,16 +158,14 @@ impl OffscreenTargetBuilder {
   /// Create the render target color (and optional depth) attachments.
   pub fn build(
     self,
-    render_context: &mut RenderContext,
+    gpu: &Gpu,
   ) -> Result<OffscreenTarget, OffscreenTargetError> {
     let format = match self.color_format {
       Some(format) => format,
       None => return Err(OffscreenTargetError::MissingColorAttachment),
     };
 
-    let surface_size = render_context.surface_size();
-    let defaulted_from_surface_size = self.width == 0 || self.height == 0;
-    let (width, height) = self.resolve_size(surface_size)?;
+    let (width, height) = self.resolve_size()?;
 
     let sample_count = self.sample_count.max(1);
     if let Err(_) = validation::validate_sample_count(sample_count) {
@@ -188,9 +175,7 @@ impl OffscreenTargetBuilder {
     }
 
     if sample_count > 1
-      && !render_context
-        .gpu()
-        .supports_sample_count_for_format(format, sample_count)
+      && !gpu.supports_sample_count_for_format(format, sample_count)
     {
       return Err(OffscreenTargetError::UnsupportedSampleCount {
         requested: sample_count,
@@ -199,9 +184,7 @@ impl OffscreenTargetBuilder {
 
     if let Some(depth_format) = self.depth_format {
       if sample_count > 1
-        && !render_context
-          .gpu()
-          .supports_sample_count_for_depth(depth_format, sample_count)
+        && !gpu.supports_sample_count_for_depth(depth_format, sample_count)
       {
         return Err(OffscreenTargetError::UnsupportedSampleCount {
           requested: sample_count,
@@ -221,7 +204,7 @@ impl OffscreenTargetBuilder {
       }
     }
 
-    let resolve_texture = match color_builder.build(render_context.gpu()) {
+    let resolve_texture = match color_builder.build(gpu) {
       Ok(texture) => texture,
       Err(message) => {
         return Err(OffscreenTargetError::DeviceError(message.to_string()));
@@ -236,7 +219,7 @@ impl OffscreenTargetBuilder {
       if let Some(ref label) = self.label {
         msaa_builder = msaa_builder.with_label(&format!("{}-msaa", label));
       }
-      Some(msaa_builder.build(render_context.gpu()))
+      Some(msaa_builder.build(gpu))
     } else {
       None
     };
@@ -251,7 +234,7 @@ impl OffscreenTargetBuilder {
         depth_builder = depth_builder.with_label(&format!("{}-depth", label));
       }
 
-      Some(depth_builder.build(render_context.gpu()))
+      Some(depth_builder.build(gpu))
     } else {
       None
     };
@@ -265,26 +248,14 @@ impl OffscreenTargetBuilder {
       depth_format: self.depth_format,
       sample_count,
       label: self.label,
-      defaulted_from_surface_size,
     });
   }
 
-  /// Resolve the final size using an optional explicit size and surface default.
-  ///
-  /// When no explicit size was provided, the builder falls back to
-  /// `surface_size`. A resolved size with zero width or height is treated as
-  /// an error.
   pub(crate) fn resolve_size(
     &self,
-    surface_size: (u32, u32),
   ) -> Result<(u32, u32), OffscreenTargetError> {
-    let mut width = self.width;
-    let mut height = self.height;
-    if width == 0 || height == 0 {
-      width = surface_size.0;
-      height = surface_size.1;
-    }
-
+    let width = self.width;
+    let height = self.height;
     if width == 0 || height == 0 {
       return Err(OffscreenTargetError::InvalidSize { width, height });
     }
@@ -294,47 +265,34 @@ impl OffscreenTargetBuilder {
 }
 
 #[deprecated(
-  note = "Use `lambda::render::target::OffscreenTarget` to avoid confusion with `lambda::render::render_target::RenderTarget`."
+  note = "Use `lambda::render::targets::offscreen::OffscreenTarget` to avoid confusion with `lambda::render::targets::surface::RenderTarget`."
 )]
 pub type RenderTarget = OffscreenTarget;
 
 #[deprecated(
-  note = "Use `lambda::render::target::OffscreenTargetBuilder` to avoid confusion with `lambda::render::render_target::RenderTarget`."
+  note = "Use `lambda::render::targets::offscreen::OffscreenTargetBuilder` to avoid confusion with `lambda::render::targets::surface::RenderTarget`."
 )]
 pub type RenderTargetBuilder = OffscreenTargetBuilder;
 
-#[deprecated(note = "Use `lambda::render::target::OffscreenTargetError`.")]
+#[deprecated(
+  note = "Use `lambda::render::targets::offscreen::OffscreenTargetError`."
+)]
 pub type RenderTargetError = OffscreenTargetError;
 
 #[cfg(test)]
 mod tests {
   use super::*;
 
-  /// Defaults size to the surface when no explicit dimensions are provided.
-  #[test]
-  fn resolve_size_defaults_to_surface_size() {
-    let builder = OffscreenTargetBuilder::new().with_color(
-      texture::TextureFormat::Rgba8Unorm,
-      0,
-      0,
-    );
-    let surface_size = (800, 600);
-
-    let resolved = builder.resolve_size(surface_size).unwrap();
-    assert_eq!(resolved, surface_size);
-  }
-
-  /// Fails when the resolved size has a zero dimension.
+  /// Fails when the builder has a zero dimension.
   #[test]
   fn resolve_size_rejects_zero_dimensions() {
     let builder = OffscreenTargetBuilder::new().with_color(
       texture::TextureFormat::Rgba8Unorm,
       0,
       0,
     );
-    let surface_size = (0, 0);
 
-    let resolved = builder.resolve_size(surface_size);
+    let resolved = builder.resolve_size();
     assert_eq!(
       resolved,
       Err(OffscreenTargetError::InvalidSize {