rust_pixel 2.4.0

//! # WGPU Rendering Module
//! 
//! Modern GPU-accelerated rendering subsystem for RustPixel, implementing
//! the complete graphics mode pipeline using WebGPU standard via wgpu.
//! 
//! This module serves as a modern replacement for the OpenGL rendering pipeline,
//! providing better performance, safety, and cross-platform compatibility.
//! 
//! ## Architecture Overview
//! 
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │                WGPU Rendering Architecture                  │
//! │                                                             │
//! │  ┌─────────────────────────────────────────────────────────┐ │
//! │  │                  Core Components                        │ │
//! │  │  ┌─────────────┬─────────────┬─────────────────────┐   │ │
//! │  │  │   Shader    │  Transform  │      Texture        │   │ │
//! │  │  │ Management  │   System    │     Management      │   │ │
//! │  │  └─────────────┴─────────────┴─────────────────────┘   │ │
//! │  └─────────────────────────────────────────────────────────┘ │
//! │                            │                                 │
//! │  ┌─────────────────────────▼───────────────────────────────┐ │
//! │  │              Rendering Components                       │ │
//! │  │  ┌─────────────┬─────────────┬─────────────────────┐   │ │
//! │  │  │   Symbols   │ Transition  │     General2D       │   │ │
//! │  │  │   Shader    │   Shader    │      Shader         │   │ │
//! │  │  │(Instanced)  │ (Effects)   │   (Composition)     │   │ │
//! │  │  └─────────────┴─────────────┴─────────────────────┘   │ │
//! │  └─────────────────────────────────────────────────────────┘ │
//! └─────────────────────────────────────────────────────────────┘
//! ```

#![allow(unused_variables)]



/// Texture loading and management system for wgpu
pub mod texture;

/// Shader compilation and management system for wgpu
pub mod shader;

/// WGSL shader source code storage
pub mod shader_source;

/// Main pixel renderer implementation for wgpu
pub mod pixel;

/// Symbol rendering with instanced drawing for wgpu
pub mod render_symbols;

/// Transition effects and blending for wgpu
pub mod render_transition;

/// Final composition and screen mapping for wgpu
pub mod render_general2d;

/// Shared render core for both native and web adapters
pub mod render_core;

pub use render_core::{WgpuRenderCore, WgpuRenderCoreBuilder};

use wgpu;
use bytemuck;

/// WGPU Renderer Interface Definition
/// 
/// Defines the essential interface that all WGPU rendering components must implement.
/// This trait provides a standardized way to initialize, manage, and execute
/// WGPU rendering operations across different shader types and rendering techniques.
/// 
/// ## Rendering Lifecycle
/// 
/// All renderers follow this standard lifecycle:
/// 
/// ```text
/// ┌─────────────────────────────────────────────────────────────┐
/// │                  Renderer Lifecycle                        │
/// │                                                             │
/// │  1. new()           → Create renderer instance              │
/// │          │                                                  │
/// │          ▼                                                  │
/// │  2. init()          → Initialize WGPU resources            │
/// │          │                                                  │
/// │          ▼                                                  │
/// │  3. Loop: prepare_draw() → draw() → cleanup()              │
/// │          │                                                  │
/// │          ▼                                                  │
/// │  4. Drop            → Automatic cleanup                    │
/// └─────────────────────────────────────────────────────────────┘
/// ```
pub trait WgpuRender {
    /// Create new renderer instance
    /// 
    /// Initializes the renderer with specified canvas dimensions but does not
    /// create any WGPU resources yet. WGPU resource creation should be
    /// deferred to the `init()` method.
    /// 
    /// # Parameters
    /// - `canvas_width`: Target canvas width in pixels
    /// - `canvas_height`: Target canvas height in pixels
    fn new(canvas_width: u32, canvas_height: u32) -> Self
    where
        Self: Sized;

    /// Get mutable reference to base renderer data
    /// 
    /// Provides access to shared renderer data including WGPU objects,
    /// canvas dimensions, and common rendering state.
    fn get_base(&mut self) -> &mut WgpuRenderBase;

    /// Create and compile shaders
    /// 
    /// Compiles WGSL shaders and creates render pipelines.
    /// This method handles shader module creation and pipeline layout setup.
    /// 
    /// # Parameters
    /// - `device`: WGPU device handle
    fn create_shader(&mut self, device: &wgpu::Device);

    /// Create WGPU buffers and resources
    /// 
    /// Allocates vertex buffers, index buffers, uniform buffers, and other
    /// WGPU resources needed for rendering. Should be called after shader creation.
    /// 
    /// # Parameters
    /// - `device`: WGPU device handle
    fn create_buffer(&mut self, device: &wgpu::Device);

    /// Initialize all WGPU resources
    /// 
    /// Default implementation that calls `create_shader()` followed by `create_buffer()`.
    /// Can be overridden for custom initialization sequences.
    /// 
    /// # Parameters
    /// - `device`: WGPU device handle
    fn init(&mut self, device: &wgpu::Device) {
        self.create_shader(device);
        self.create_buffer(device);
    }

    /// Prepare for drawing operations
    /// 
    /// Sets up per-frame rendering state, updates uniforms, and prepares
    /// the WGPU pipeline for drawing. Called once per frame before `draw()`.
    /// 
    /// # Parameters
    /// - `device`: WGPU device handle
    /// - `queue`: WGPU queue handle
    fn prepare_draw(&mut self, device: &wgpu::Device, queue: &wgpu::Queue);

    /// Execute drawing operations
    /// 
    /// Performs the actual WGPU drawing commands using command encoder.
    /// Should assume that `prepare_draw()` has already been called.
    /// 
    /// # Parameters
    /// - `encoder`: Command encoder for recording draw commands
    /// - `view`: Render target texture view
    fn draw(&mut self, encoder: &mut wgpu::CommandEncoder, view: &wgpu::TextureView);

    /// Clean up temporary rendering state
    /// 
    /// Resets temporary WGPU state changes made during rendering.
    /// This method is for per-frame cleanup, not resource deallocation.
    /// 
    /// # Parameters
    /// - `device`: WGPU device handle
    fn cleanup(&mut self, device: &wgpu::Device);
}

/// WGPU Renderer Base Data Structure
/// 
/// Contains shared data and WGPU resources used across all graphics
/// mode renderers. This structure provides common functionality and
/// resource management for the WGPU rendering pipeline.
/// 
/// ## Resource Management
/// 
/// The base structure manages several types of WGPU resources:
/// - **Render Pipelines**: Compiled shader programs with state
/// - **Buffers**: Vertex, index, and uniform buffers
/// - **Textures**: 2D textures and render targets
/// - **Bind Groups**: Resource binding collections
pub struct WgpuRenderBase {
    /// Unique identifier for this renderer instance
    /// 
    /// Used for debugging, resource tracking, and distinguishing between
    /// multiple renderer instances in complex rendering setups.
    pub id: usize,
    
    /// Vector of compiled render pipelines
    /// 
    /// Stores all render pipelines used by this renderer. Each pipeline
    /// contains compiled shaders, vertex layouts, and render state.
    pub render_pipelines: Vec<wgpu::RenderPipeline>,
    
    /// Vector of WGPU buffer objects
    /// 
    /// Contains vertex buffers, index buffers, uniform buffers, and other
    /// buffer objects used by the renderer. Indexed access allows flexible
    /// buffer management for different rendering techniques.
    pub buffers: Vec<wgpu::Buffer>,
    
    /// Vector of WGPU texture objects
    /// 
    /// Stores 2D textures, render targets, and other texture resources.
    /// Includes both source textures (loaded from files) and render targets
    /// (created for off-screen rendering).
    pub textures: Vec<wgpu::Texture>,
    
    /// Vector of WGPU bind groups
    /// 
    /// Contains resource binding collections that group related resources
    /// (uniforms, textures, samplers) for efficient GPU access.
    pub bind_groups: Vec<wgpu::BindGroup>,
    
    /// Canvas width in pixels
    /// 
    /// Width of the render target or canvas that this renderer draws to.
    /// Used for viewport calculations, projection matrix setup, and
    /// coordinate system transformations.
    pub canvas_width: u32,
    
    /// Canvas height in pixels
    /// 
    /// Height of the render target or canvas that this renderer draws to.
    /// Used for viewport calculations, projection matrix setup, and
    /// coordinate system transformations.
    pub canvas_height: u32,
}

impl WgpuRenderBase {
    /// Create new base renderer data structure
    /// 
    /// Initializes a new base structure with the specified ID and canvas dimensions.
    /// All resource vectors are initialized as empty and will be populated during
    /// the renderer initialization process.
    /// 
    /// # Parameters
    /// - `id`: Unique identifier for this renderer instance
    /// - `canvas_width`: Canvas width in pixels
    /// - `canvas_height`: Canvas height in pixels
    /// 
    /// # Returns
    /// New WgpuRenderBase instance with empty resource collections
    pub fn new(id: usize, canvas_width: u32, canvas_height: u32) -> Self {
        Self {
            id,
            render_pipelines: Vec::new(),
            buffers: Vec::new(),
            textures: Vec::new(),
            bind_groups: Vec::new(),
            canvas_width,
            canvas_height,
        }
    }
}