re-org en App

lib/src/core/renderer.rs

@@ -0,0 +1,117 @@
+//! # Renderer Module — Executor Layer (WGPU Command Execution)
+//!
+//! The **Executor** layer of the architecture. Executes WGPU rendering commands — orchestrates draw calls by binding
+//! Material pipelines and Mesh vertex buffers into a RenderPass, then submits commands to the GPU queue.
+//! Does not own hardware resources (Device, Queue); receives references when called by the orchestrator (main.rs).
+//! Does not own RenderPipelines or shaders — those are managed by PipelineCache and accessed through Material.
+//! Does not own Surface/TextureView — acquired from Context::begin_frame().
+//!
+//! ## Interaction with Other Modules
+//! - **context**: receives Device/Queue references and TextureView; does not call begin/end_frame itself.
+//! - **pipeline_cache**: indirectly via Material — Renderer uses pipelines that PipelineCache compiled.
+//! - **mesh**: passes vertex/index buffers into set_vertex_buffer/set_index_buffer during draw.
+//! - **material**: provides the RenderPipeline reference via set_pipeline during draw.
+//!
+//! ## Architecture Notes (per ARCHI_APP.md)
+//! - **Phase d'Exécution**: Renderer executes per-frame render loops. During this phase it iterates Scene entities
+//!   and draws each one by binding the appropriate Material+Mesh pair.
+//! - **Performance**: Entity sorting within the render loop minimizes pipeline switches (batching par matériau).
+//! - **Accès Bas-Niveau**: Advanced users can bypass Scene and call Renderer directly for custom rendering paths.
+
+use crate::core::Context;
+use crate::resources::{Mesh, Material};
+use crate::core::Frame;
+
+
+/// The Executor layer of the architecture. Holds shared references to Device and Queue from Context,
+/// plus the surface texture format. Executes WGPU rendering commands by binding Materials and Meshes
+/// into RenderPasses during each frame. Does not own raw hardware resources (they are Arc-cloned from Context).
+pub struct Renderer {
+    /// GPU command submission queue — holds an Arc clone from Context; shared with other Context users.
+    queue: wgpu::Queue,
+    /// GPU device — creates buffers, textures, pipelines; holds an Arc clone from Context.
+    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 Renderer by cloning Device and Queue Arc references from the Context, plus capturing the surface format.
+    /// Called once at application startup during scene setup. The Renderer shares these resources via Arc;
+    /// Context retains ownership and can continue using them after this call.
+    pub fn new(context: &Context, format: wgpu::TextureFormat) -> Self {
+        Self {
+            queue: context.queue.clone(),
+            device: context.device.clone(),
+            format,
+        }
+    }
+
+    /// 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,
+        view: &wgpu::TextureView,
+        mesh: &Mesh,
+        material: &Material,
+    ) {
+        // 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.
+        {
+            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,
+                    ops: wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
+                        store: wgpu::StoreOp::Store,
+                    },
+                })],
+                ..Default::default()
+            });
+
+            render_pass.set_pipeline(&material.pipeline);
+            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);
+            } else {
+                render_pass.draw(0..mesh.num_vertices, 0..1);
+            }
+        }
+        self.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: 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
+    }
+}