wsg/lib/renderer.rs

//! # Renderer Module
//!
//! The **Specialist** (Executor) layer of the architecture. Owns rendering logic — 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.

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 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 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: &crate::mesh::Mesh,
        material: &crate::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: 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
    }
}