gapp_winit/

lib.rs

#![deny(missing_docs)]

/*!
An abstract event loop library for winit-based applications with support for OpenGL (glutin) and wgpu backends.
It cleanly separates input handling, updates, rendering, and presenting via traits and manages a fixed-timestep FPS loop.

# Features

- `opengl`: Enables OpenGL support.
- `wgpu`: Enables wgpu support (recommended).

# Usage

Implement `WindowInput<I, R>`, `Present<R>`, `Render<R>` (from gapp), and `Update` (from gapp) for your app.
Create a `Windows<R>` collection with your backend-specific `WindowData`, then call `run()`.

See [the template](https://gitlab.com/porky11/gapp-template) for reference. It can be used as a starting point.
*/

use std::collections::HashMap;
#[cfg(feature = "wgpu")]
use std::sync::Arc;
#[cfg(not(target_arch = "wasm32"))]
use std::time::{Duration, Instant};
#[cfg(target_arch = "wasm32")]
use web_time::{Duration, Instant};

pub use gapp::{Render, Update};

#[cfg(feature = "opengl")]
#[cfg(not(target_arch = "wasm32"))]
use glutin::{
    context::PossiblyCurrentContext,
    prelude::*,
    surface::{Surface, WindowSurface},
};
#[cfg(not(target_arch = "wasm32"))]
use winit::dpi::PhysicalSize;
use winit::{
    event::{DeviceEvent, DeviceId, WindowEvent},
    event_loop::ActiveEventLoop,
    window::{Window, WindowId},
};

/// Trait for custom input handling.
///
/// Called for **every** `WindowEvent`, **after** possible internal handling.
/// Handle events like `CloseRequested`, `KeyboardInput`, etc. here.
/// Call `event_loop.exit()` to quit the app.
/// The `windows` parameter provides mutable access to all managed windows and their renderers.
///
/// `KeyboardInput` is withheld for a brief grace period after the window regains focus, so the
/// keystroke of an OS window-switch shortcut (e.g. Alt-Tab) doesn't leak into the app.
pub trait WindowInput<C, R> {
    /// Processes a `WindowEvent`.
    ///
    /// # Arguments
    ///
    /// - `window_id`: The ID of the window that received the event.
    /// - `event`: The incoming `WindowEvent`.
    /// - `event_loop`: Reference to the active event loop for control (e.g., `exit()`).
    /// - `context`: Custom context to represent input state.
    /// - `windows`: Mutable access to all managed windows and their renderers.
    fn input(
        &mut self,
        window_id: WindowId,
        event: &WindowEvent,
        event_loop: &ActiveEventLoop,
        context: &mut C,
        windows: &mut Windows<R>,
    );

    /// Processes a raw `DeviceEvent` (e.g. relative mouse motion for camera/look controls).
    ///
    /// Called for every `DeviceEvent`, unfiltered. Default implementation does nothing, so
    /// existing `WindowInput` implementors are unaffected unless they opt in.
    ///
    /// # Arguments
    ///
    /// - `device_id`: The ID of the device that produced the event.
    /// - `event`: The incoming `DeviceEvent`.
    /// - `event_loop`: Reference to the active event loop for control (e.g., `exit()`).
    /// - `context`: Custom context to represent input state.
    /// - `windows`: Mutable access to all managed windows and their renderers.
    fn device_input(
        &mut self,
        device_id: DeviceId,
        event: &DeviceEvent,
        event_loop: &ActiveEventLoop,
        context: &mut C,
        windows: &mut Windows<R>,
    ) {
        let _ = (device_id, event, event_loop, context, windows);
    }
}

/// Platform- and backend-specific window data for OpenGL.
#[cfg(feature = "opengl")]
pub struct WindowData {
    /// The winit window.
    pub window: Window,
    /// The GL context (glutin).
    #[cfg(not(target_arch = "wasm32"))]
    pub context: PossiblyCurrentContext,
    /// The GL surface (glutin).
    #[cfg(not(target_arch = "wasm32"))]
    pub surface: Surface<WindowSurface>,
}

#[cfg(feature = "opengl")]
#[cfg(not(target_arch = "wasm32"))]
impl WindowData {
    /// Creates a window with a current OpenGL context and surface via glutin.
    ///
    /// Picks a config with an alpha channel, preferring transparency and multisampling, then makes
    /// the context current on the new surface. Build your GL renderer afterward from
    /// `window_data.context.display()` (e.g. via `get_proc_address`). All fields are public, so
    /// callers needing different config selection can construct `WindowData` manually instead.
    #[allow(clippy::expect_used)]
    pub fn new_opengl(
        event_loop: &ActiveEventLoop,
        attributes: winit::window::WindowAttributes,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        use glutin::{
            config::ConfigTemplateBuilder,
            context::{ContextApi, ContextAttributesBuilder},
            display::GetGlDisplay,
            surface::SurfaceAttributesBuilder,
        };
        use glutin_winit::DisplayBuilder;
        use raw_window_handle::HasWindowHandle;
        use std::num::NonZeroU32;

        let template = ConfigTemplateBuilder::new().with_alpha_size(8);
        let display_builder = DisplayBuilder::new().with_window_attributes(Some(attributes));

        let (window, gl_config) = display_builder.build(event_loop, template, |configs| {
            configs
                .reduce(|accum, config| {
                    let prefer_config = config.supports_transparency().unwrap_or(false)
                        & !accum.supports_transparency().unwrap_or(false);
                    if prefer_config || config.num_samples() > accum.num_samples() {
                        config
                    } else {
                        accum
                    }
                })
                .expect("no OpenGL configurations available")
        })?;

        let window = window.ok_or("display builder returned no window")?;
        let raw_handle = window.window_handle()?.as_raw();
        let gl_display = gl_config.display();

        let context_attributes = ContextAttributesBuilder::new().build(Some(raw_handle));
        let fallback_attributes = ContextAttributesBuilder::new()
            .with_context_api(ContextApi::Gles(None))
            .build(Some(raw_handle));

        let context = unsafe {
            gl_display
                .create_context(&gl_config, &context_attributes)
                .or_else(|_| gl_display.create_context(&gl_config, &fallback_attributes))?
        };

        let size = window.inner_size();
        let width = NonZeroU32::new(size.width.max(1)).ok_or("zero window width")?;
        let height = NonZeroU32::new(size.height.max(1)).ok_or("zero window height")?;
        let surface_attributes =
            SurfaceAttributesBuilder::<WindowSurface>::new().build(raw_handle, width, height);
        let surface = unsafe { gl_display.create_window_surface(&gl_config, &surface_attributes)? };

        let context = context.make_current(&surface)?;

        Ok(Self {
            window,
            context,
            surface,
        })
    }
}

/// Platform- and backend-specific window data for wgpu.
#[cfg(feature = "wgpu")]
pub struct WindowData {
    /// The wgpu device.
    pub device: wgpu::Device,
    /// The wgpu queue.
    pub queue: wgpu::Queue,
    /// Current surface configuration (updated on resize).
    pub surface_config: wgpu::SurfaceConfiguration,
    /// The wgpu surface (with `'static` lifetime for compatibility).
    pub surface: wgpu::Surface<'static>,
    /// Arc-wrapped winit window (thread-safe).
    pub window: Arc<Window>,
}

#[cfg(feature = "wgpu")]
impl WindowData {
    /// Creates a window and its wgpu device, queue, surface, and configuration.
    ///
    /// Picks the instance backends and adapter from the environment, requests a device with
    /// WebGL2-downlevel limits (portable across native and `wasm32`), and configures the surface
    /// with a non-sRGB format. All fields are public, so callers can adjust the result afterward
    /// (e.g. add `TextureUsages::COPY_SRC` for screenshots, then reconfigure the surface).
    ///
    /// Intended for native targets: call it inside the [`run`] window factory and drive the future
    /// with a blocking executor (e.g. `pollster::block_on`). On `wasm32` it cannot be used through
    /// [`run`] — the factory is synchronous, blocking executors deadlock the single-threaded JS
    /// event loop, and the browser surface is built from a canvas rather than a created window. On
    /// the web, set up the device and surface in an `async` context before calling [`run`] and
    /// construct `WindowData` by hand in the factory.
    pub async fn new_wgpu(
        event_loop: &ActiveEventLoop,
        attributes: winit::window::WindowAttributes,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let window = Arc::new(event_loop.create_window(attributes)?);

        let instance = wgpu::util::new_instance_with_webgpu_detection(wgpu::InstanceDescriptor {
            backends: wgpu::Backends::from_env().unwrap_or_default(),
            flags: wgpu::InstanceFlags::from_build_config().with_env(),
            ..wgpu::InstanceDescriptor::new_without_display_handle()
        })
        .await;

        let surface = instance.create_surface(window.clone())?;

        let adapter =
            wgpu::util::initialize_adapter_from_env_or_default(&instance, Some(&surface)).await?;

        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                required_limits: wgpu::Limits::downlevel_webgl2_defaults()
                    .using_resolution(adapter.limits()),
                ..Default::default()
            })
            .await?;

        let size = window.inner_size();
        let mut surface_config = surface
            .get_default_config(&adapter, size.width.max(1), size.height.max(1))
            .ok_or("surface is not supported by the adapter")?;

        let capabilities = surface.get_capabilities(&adapter);
        surface_config.format = capabilities
            .formats
            .iter()
            .find(|format| !format.is_srgb())
            .copied()
            .unwrap_or(capabilities.formats[0]);
        surface.configure(&device, &surface_config);

        Ok(Self {
            device,
            queue,
            surface_config,
            surface,
            window,
        })
    }
}

/// Collection of windows with their associated renderers.
pub struct Windows<R> {
    map: HashMap<WindowId, (WindowData, R)>,
}

impl<R> Windows<R> {
    /// Creates an empty window collection.
    pub fn new() -> Self {
        Self {
            map: HashMap::new(),
        }
    }

    /// Inserts a window and its renderer. Returns the `WindowId`.
    pub fn insert(&mut self, window_data: WindowData, renderer: R) -> WindowId {
        let id = window_data.window.id();
        self.map.insert(id, (window_data, renderer));
        id
    }

    /// Removes a window by ID, returning its data and renderer if present.
    pub fn remove(&mut self, id: &WindowId) -> Option<(WindowData, R)> {
        self.map.remove(id)
    }

    /// Returns a reference to the window data and renderer for the given ID.
    pub fn get(&self, id: &WindowId) -> Option<&(WindowData, R)> {
        self.map.get(id)
    }

    /// Returns a mutable reference to the window data and renderer for the given ID.
    pub fn get_mut(&mut self, id: &WindowId) -> Option<&mut (WindowData, R)> {
        self.map.get_mut(id)
    }

    /// Returns `true` if there are no windows.
    pub fn is_empty(&self) -> bool {
        self.map.is_empty()
    }

    /// Returns the number of windows.
    pub fn len(&self) -> usize {
        self.map.len()
    }

    /// Iterates over all windows.
    pub fn iter(&self) -> impl Iterator<Item = (&WindowId, &(WindowData, R))> {
        self.map.iter()
    }

    /// Iterates mutably over all windows.
    pub fn iter_mut(&mut self) -> impl Iterator<Item = (&WindowId, &mut (WindowData, R))> {
        self.map.iter_mut()
    }
}

impl<R> Default for Windows<R> {
    fn default() -> Self {
        Self::new()
    }
}

/// Trait for presenting the rendered frame.
///
/// Called after `application.render()` in `RedrawRequested` events.
pub trait Present<R> {
    /// Presents the frame to the surface.
    ///
    /// # Arguments
    ///
    /// - `renderer`: Mutable renderer (e.g., for swapchain submit).
    /// - `window_data`: Backend-specific data (surface/context).
    fn present(&self, renderer: &mut R, window_data: &WindowData);
}

type WindowFactory<R> = Box<dyn FnOnce(&ActiveEventLoop) -> Windows<R>>;

struct AppState<I, R, E> {
    application: E,
    timestep: Duration,
    create_windows: Option<WindowFactory<R>>,
    windows: Option<Windows<R>>,
    input_context: I,
    prev_time: Instant,
    focus_grace_until: Option<Instant>,
}

// ponytail: fixed grace window swallowing the window-switch shortcut's residual
// keystroke; bump if a platform still leaks input past this.
const FOCUS_GRACE: Duration = Duration::from_millis(50);

impl<I: 'static, R: 'static, E> winit::application::ApplicationHandler for AppState<I, R, E>
where
    E: WindowInput<I, R> + Present<R> + Render<R> + Update,
{
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        if self.windows.is_some() {
            return;
        }
        if let Some(create_windows) = self.create_windows.take() {
            self.windows = Some(create_windows(event_loop));
            self.prev_time = Instant::now();
        }
    }

    fn window_event(
        &mut self,
        event_loop: &ActiveEventLoop,
        window_id: WindowId,
        event: WindowEvent,
    ) {
        let Some(windows) = &mut self.windows else {
            return;
        };

        if let WindowEvent::Focused(focused) = &event {
            self.focus_grace_until = focused.then(|| Instant::now() + FOCUS_GRACE);
        }
        if matches!(event, WindowEvent::KeyboardInput { .. })
            && self
                .focus_grace_until
                .is_some_and(|until| Instant::now() < until)
        {
            return;
        }

        #[cfg(not(target_arch = "wasm32"))]
        if let WindowEvent::Resized(PhysicalSize { width, height }) = &event {
            let width = (*width).max(1);
            let height = (*height).max(1);
            if let Some((window_data, _)) = windows.get_mut(&window_id) {
                #[cfg(feature = "opengl")]
                if let (Ok(non_zero_width), Ok(non_zero_height)) =
                    (width.try_into(), height.try_into())
                {
                    window_data.surface.resize(
                        &window_data.context,
                        non_zero_width,
                        non_zero_height,
                    );
                }
                #[cfg(feature = "wgpu")]
                {
                    window_data.surface_config.width = width;
                    window_data.surface_config.height = height;
                    window_data
                        .surface
                        .configure(&window_data.device, &window_data.surface_config);
                }
            }
        }

        self.application.input(
            window_id,
            &event,
            event_loop,
            &mut self.input_context,
            windows,
        );

        if matches!(event, WindowEvent::RedrawRequested)
            && let Some((window_data, renderer)) = windows.get_mut(&window_id)
        {
            self.application.render(renderer);
            self.application.present(renderer, window_data);
        }
    }

    fn device_event(
        &mut self,
        event_loop: &ActiveEventLoop,
        device_id: DeviceId,
        event: DeviceEvent,
    ) {
        let Some(windows) = &mut self.windows else {
            return;
        };

        self.application.device_input(
            device_id,
            &event,
            event_loop,
            &mut self.input_context,
            windows,
        );
    }

    fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {
        let Some(windows) = &self.windows else {
            return;
        };

        self.application.update(self.timestep.as_secs_f32());

        #[cfg(not(target_arch = "wasm32"))]
        {
            let frame_duration = self.prev_time.elapsed();
            if frame_duration < self.timestep {
                std::thread::sleep(self.timestep - frame_duration);
            }
        }

        for (_, (window_data, _)) in windows.iter() {
            window_data.window.request_redraw();
        }

        self.prev_time = Instant::now();
    }

    fn exiting(&mut self, _event_loop: &ActiveEventLoop) {}
}

/// Starts the main event loop with a fixed timestep.
///
/// Manages winit events and calls app traits in the correct order:
/// - `input()` after every `WindowEvent` (after internal resize/redraw handling).
/// - `update(timestep)` with fixed timestep in `about_to_wait`.
/// - `render()` + `present()` on `RedrawRequested` (per window).
///
/// **Important notes:**
/// - App (`E`) and states must be `'static` (moved into closure).
/// - Automatic resize handling (clamped to min 1px size).
/// - No automatic close handling: implement in `input()`.
/// - Redraw is requested for all windows on each frame.
/// - The `create_windows` closure is called once in `resumed()`.
///
/// # Type Parameters
///
/// - `I`: Input context type (for `WindowInput`).
/// - `R`: Renderer type.
/// - `E`: App type (must implement `WindowInput<I,R> + Present<R> + Render<R> + Update + 'static`).
pub fn run<
    I: 'static,
    R: 'static,
    E: WindowInput<I, R> + Present<R> + Render<R> + Update + 'static,
>(
    application: E,
    event_loop: winit::event_loop::EventLoop<()>,
    fps: u64,
    create_windows: impl FnOnce(&ActiveEventLoop) -> Windows<R> + 'static,
    input_context: I,
) {
    let timestep = Duration::from_nanos(1_000_000_000 / fps);

    let mut state = AppState {
        application,
        timestep,
        create_windows: Some(Box::new(create_windows)),
        windows: None,
        input_context,
        prev_time: Instant::now(),
        focus_grace_until: None,
    };

    let _ = event_loop.run_app(&mut state);
}