refactor renderer responsable + docs + schema

lib/renderer.rs

@@ -12,41 +12,56 @@
 //! - **mesh**: passes vertex/index buffers into set_vertex_buffer/set_index_buffer during draw.
 //! - **material**: provides the RenderPipeline reference via set_pipeline during draw.
 
-pub struct Renderer {}
+use crate::context::Context;
+
+/// The Executor layer of the architecture. Owns Device, Queue, and Format after initialization from Context.
+/// Orchestrates all GPU draw calls without owning raw hardware resources externally.
+pub struct Renderer {
+    /// GPU command submission queue — owned by the Renderer after initialization from Context.
+    queue: wgpu::Queue,
+    /// GPU device — creates buffers, textures, pipelines; owned by the Renderer after initialization.
+    device: wgpu::Device,
+    /// Surface texture output format — stored here so it can be passed to PipelineCache on Material creation.
+    format: wgpu::TextureFormat,
+}
 
 impl Renderer {
-    /// Creates a new Renderer instance with no internal state — it is pure execution logic only.
-    /// Called once at application startup; the same Renderer is reused for all frames.
-    pub fn new() -> Self {
-        Self {}
+    /// Creates a Renderer by taking ownership of Device, Queue, and Format from the Context.
+    /// Called once at application startup during scene setup. The Renderer becomes the sole owner of these resources.
+    pub fn new(context: &Context, format: wgpu::TextureFormat) -> Self {
+        Self {
+            queue: context.queue.clone(),
+            device: context.device.clone(),
+            format,
+        }
     }
 
-    /// Orchestrates a single draw call: creates an encoder, starts a render pass, binds pipeline + buffers, draws, then submits commands.
-    /// Inputs: device (GPU command source), queue (command submission target), view (surface texture output), mesh (geometry to draw), material (shader/pipeline).
-    /// Returns nothing — side-effect: GPU executes the draw and presents to the surface. Called by the orchestrator (main.rs) once per frame.
-    /// Internal steps: 1) create_command_encoder → 2) begin_render_pass in scoped block → 3) set_pipeline/set_vertex_buffer/draw → drop(render_pass) → 4) submit(encoder.finish()).
+    /// Orchestrates rendering of a single object: binds Material pipeline + Mesh vertex data into a RenderPass,
+    /// then submits commands to the GPU queue for execution. Called per-frame by the orchestrator (main.rs).
+    /// Internal steps: 1) create CommandEncoder → 2) begin RenderPass with color attachment →
+    /// 3) set_pipeline(material.pipeline) → 4) set_vertex_buffer(mesh.vertex_buffer) →
+    /// 5) draw_indexed or draw based on index buffer presence → 6) drop render_pass end scope →
+    /// 7) submit encoder via queue.
     pub fn render(
         &self,
-        device: &wgpu::Device,
-        queue: &wgpu::Queue,
         view: &wgpu::TextureView,
         mesh: &crate::mesh::Mesh,
         material: &crate::material::Material,
     ) {
-        // Create command encoder
-        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
+        // Create per-frame command encoder; its lifetime is scoped to this function only.
+        let mut encoder = self.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
             label: Some("render encoder"),
         });
 
+        // RenderPass borrows encoder mutably — must end (drop) before encoder.finish() below.
+        // This scope boundary enforces Rust's borrow checker rules for GPU synchronization.
         {
-            // Block creation so render_pass is dropped before queue submit
-            // RenderPass start — depth_slice is a new required field in wgpu 30 for multisampled textures.
             let mut render_pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                 label: Some("render pass"),
                 color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                     view,
                     resolve_target: None,
-                    depth_slice: None, // new field; None means no multisample resolve needed
+                    depth_slice: None,
                     ops: wgpu::Operations {
                         load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
                         store: wgpu::StoreOp::Store,
@@ -55,10 +70,13 @@ impl Renderer {
                 ..Default::default()
             });
 
-            // Pipeline call — draw with empty vertex buffers (geometry defined in shader)
             render_pass.set_pipeline(&material.pipeline);
-
-            // if any indices
+            if mesh.num_vertices > 0 {
+                render_pass.set_vertex_buffer(0, mesh.vertex_buffer.slice(..));
+            } else {
+                // If no vertices, skip drawing entirely (nothing to render)
+                return;
+            }
             if let Some(index_buffer) = &mesh.index_buffer {
                 render_pass.set_index_buffer(index_buffer.slice(..), wgpu::IndexFormat::Uint16);
                 render_pass.draw_indexed(0..mesh.num_indices, 0, 0..1);
@@ -66,13 +84,23 @@ impl Renderer {
                 render_pass.draw(0..mesh.num_vertices, 0..1);
             }
         }
-        // Queue submit
-        queue.submit(std::iter::once(encoder.finish()));
+        self.queue.submit(std::iter::once(encoder.finish()));
     }
-    /// Submits a completed command encoder to the GPU queue for execution.
-    /// Inputs: queue (GPU command submission target), encoder (completed command buffer).
-    /// Returns nothing — side-effect: GPU executes all recorded commands. Called by renderer code after render pass completion.
-    pub fn submit_commands(&self, queue: &wgpu::Queue, encoder: wgpu::CommandEncoder) {
-        queue.submit(std::iter::once(encoder.finish()));
+
+    /// Presents the rendered frame by submitting the acquired surface texture to the GPU queue.
+    /// The frame must have been obtained via Context::begin_frame() or Frame::try_new(); calling present()
+    /// twice on the same texture is undefined behavior. Called by the orchestrator after render().
+    pub fn present(&self, frame: crate::frame::Frame) {
+        self.queue.present(frame.surface_texture);
+    }
+
+    /// Returns a reference to the owned Device for direct access when needed (e.g., PipelineCache creation).
+    pub fn device(&self) -> &wgpu::Device {
+        &self.device
+    }
+
+    /// Returns the surface texture output format used for rendering.
+    pub fn format(&self) -> wgpu::TextureFormat {
+        self.format
     }
 }