mirage-engine 0.1.0

//! Running a game with no window, for tools and tests.
//!
//! A [`Session`] owns a game and an offscreen target, and advances it one
//! frame at a time: no window, no event loop, no presentation. It draws
//! exactly as a window would, and one stream of moves drives both the
//! controls the game reads and its UI.
//!
//! Needs the `offscreen` feature, native only and off by default; absent
//! on `wasm32`.
//!
//! ```no_run
//! use mirage_engine::headless::Session;
//! use mirage_engine::prelude::*;
//!
//! # struct Probe;
//! # meshes! { enum Only { Cube } }
//! # impl Game for Probe {
//! #     type Meshes = Only;
//! #     type Sounds = NoSounds;
//! #     type InputActions = NoInputActions;
//! #     type Skyboxes = NoSkyboxes;
//! #     type SurfaceStyles = ();
//! #     type PostEffects = ();
//! #     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
//! #     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
//! #         ctx.draw(Cube.at(Vec3::ZERO));
//! #     }
//! # }
//! let mut session = Session::new(Config::new("probe"), UVec2::new(320, 200), |_ctx| Ok(Probe))?;
//!
//! for _ in 0..60 {
//!     let started = std::time::Instant::now();
//!     let stats = session.step();
//!     println!("{} draws took {:?}", stats.draw_calls(), started.elapsed());
//! }
//!
//! let pixels = session.pixels()?;
//! assert_eq!(pixels.len(), 320 * 200 * 4);
//! # Ok::<(), mirage_engine::Error>(())
//! ```

use core::num::NonZeroU32;
use core::time::Duration;
use std::rc::Rc;

use crate::context::{Engine, Recording, Run, Simulating};
use crate::gpu::Target;
use crate::input::{Input, Pads};
use crate::math::{UVec2, Vec2};
use crate::platform::Store;
use crate::renderer::{RenderStats, Renderer};
use crate::save::Saved;
use crate::sound::{Audio, Output};
use crate::time::FrameTime;
use crate::ui::Overlay;
use crate::{Camera, Config, Cursor, Error, Game, InitContext, PointerDelta, WheelDelta};

use driven::Driven;

pub use crate::input::Switch;

/// The format a session draws and reads back in: `8-bit` RGBA,
/// sRGB-encoded, as a window would present it — what the tone map leaves,
/// never the high-dynamic-range frame behind it.
const TARGET_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8UnormSrgb;

/// What startup returns on a machine with no graphics adapter to draw
/// with, which is the one startup error a test may skip over.
pub(crate) const NO_ADAPTER: &str = "no usable graphics adapter";

/// The format the UI and a screen past the tone map draw in: the same
/// pixels taken as the encoded values they hold, which is the space egui
/// blends in.
const OVERLAY_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;

/// A game running against an offscreen target, one frame per [`Session::step`].
///
/// The session owns the game for its whole life, exactly as [`run`](crate::run)
/// does, and borrows nothing from the caller. The caller is its player:
/// [`Session::set_pointer`], [`Session::press`], [`Session::release`],
/// [`Session::pointer_delta`], [`Session::wheel_delta`] and
/// [`Session::type_text`] are its controls. Each
/// move reaches what the game reads, the UI, or both: the UI is given the
/// `egui::Event` a window's own event reaches it as, and reads no
/// [`PointerDelta`](crate::PointerDelta) of its own; text reaches the UI
/// alone. A rebind lasts
/// the session and is written to no store, and so does everything the game
/// saves — every key returns its fallback until the session itself saves
/// one.
pub struct Session<G: Game> {
    game: G,
    config: Config,
    /// What the ticks have driven the clock to, and what the steps have;
    /// the later of the two is the time a frame reads.
    simulated: Duration,
    drawn: Duration,
    run: Run,
    renderer: Renderer<G::Meshes, G::Skyboxes>,
    audio: Audio<G::Sounds>,
    input: Input,
    saves: Saved,
    overlay: Overlay,
    device: wgpu::Device,
    queue: wgpu::Queue,
    color: wgpu::Texture,
    target: Target,
    size: UVec2,
    last_camera: Camera,
    cursor: Cursor,
    frame_interval: Duration,
    /// Whether the snapshot the game reads is spent: a control has moved
    /// since it was taken, or the step that read it has drawn.
    stale: bool,
}

impl<G: Game> Session<G> {
    /// Acquires a GPU, builds an offscreen target `size` physical pixels
    /// across, and runs `init` against it, as [`run`](crate::run) does
    /// without a window.
    ///
    /// `size` replaces the configuration's window size, which means nothing
    /// without a window; the clear color and the rest of `config` apply as
    /// usual. Fails if no GPU is available, if `size` has a zero side, if a
    /// style of the game's does not compile, or if `init` does.
    pub fn new(
        config: Config,
        size: UVec2,
        init: impl FnOnce(&mut InitContext<'_, G>) -> Result<G, Error>,
    ) -> Result<Self, Error> {
        if size.x == 0 || size.y == 0 {
            return Err(Error::msg(format!(
                "a headless target needs a non-zero size, got {}x{}",
                size.x, size.y
            )));
        }
        crate::platform::install_diagnostics();

        let (device, queue) = acquire_gpu()?;
        let color = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("mirage-engine headless target"),
            size: wgpu::Extent3d {
                width: size.x,
                height: size.y,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: TARGET_FORMAT,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[OVERLAY_FORMAT],
        });
        let view = |format| {
            color.create_view(&wgpu::TextureViewDescriptor {
                format: Some(format),
                ..Default::default()
            })
        };
        let target = Target::new(view(TARGET_FORMAT), view(OVERLAY_FORMAT), size);

        let assets = Rc::new(pollster::block_on(crate::platform::load_assets(
            config.asset_sources(),
        ))?);
        let mut renderer = pollster::block_on(Renderer::new::<G::SurfaceStyles, G::PostEffects>(
            &device,
            &queue,
            TARGET_FORMAT,
            &config,
            Rc::clone(&assets),
        ))?;
        let overlay = Overlay::offscreen(&device, OVERLAY_FORMAT, size);
        // A session has no device to play to, and time it does not keep.
        let mut audio = Audio::<G::Sounds>::new(Rc::clone(&assets), Output::silent());
        let input = Input::new::<G::InputActions>(
            Pads::silent(),
            Store::bindings(None),
            config
                .double_click_interval()
                .unwrap_or(crate::platform::DOUBLE_CLICK_INTERVAL),
        );
        let saves = Saved::new(Store::saves(None));

        audio.build_catalog();
        renderer.build_catalog(&device, &queue);
        if let Some(error) = assets.unresolved() {
            return Err(error);
        }

        let engine = Engine::new(&device, &queue, size, &config, Camera::default());
        let game = init(&mut InitContext::new(
            engine,
            &mut renderer,
            &mut audio,
            &saves,
            &assets,
            &overlay,
        ))?;

        Ok(Self {
            game,
            run: Run::new(config.tick_interval()),
            config,
            simulated: Duration::ZERO,
            drawn: Duration::ZERO,
            renderer,
            audio,
            input,
            saves,
            overlay,
            device,
            queue,
            color,
            target,
            size,
            last_camera: Camera::default(),
            cursor: Cursor::default(),
            frame_interval: Duration::ZERO,
            stale: false,
        })
    }

    /// Runs one fixed simulation step: [`Game::tick`] with
    /// [`Config::tick_interval`], or the step the game last set.
    ///
    /// Headless time moves only when called; a step set during a tick is
    /// taken from the next tick on. A tick covers the span it simulates, so
    /// it reads the clock at the end of that span and the
    /// [`step`](Session::step) after it draws at that same instant.
    pub fn tick(&mut self) {
        self.start();
        let Self {
            game,
            config,
            renderer,
            audio,
            input,
            saves,
            overlay,
            device,
            queue,
            size,
            simulated,
            run,
            last_camera,
            ..
        } = self;

        let dt = run.start_ticks();
        // The tick covers the span it is about to simulate, so it reads the
        // clock at the end of that span, which is where the step after it
        // draws from.
        *simulated += dt;
        let elapsed = *simulated;
        input.ticks(NonZeroU32::MIN, |ticking| {
            let engine = Engine::new(device, queue, *size, config, *last_camera);
            let simulating = Simulating { audio, saves, run };
            game.tick(&mut simulating.tick_context(
                engine,
                renderer.meshes(),
                ticking,
                dt,
                elapsed,
                overlay.claims(),
            ));
        });
    }

    /// The same session, with the time each [`Session::step`] covers set
    /// to `interval`.
    ///
    /// A session's clock is the caller's: a tick advances it by its own
    /// interval, and a step by this one. What a frame reads as
    /// [`FrameContext::elapsed`](crate::FrameContext::elapsed) is the later
    /// of the two, so a caller that ticks and steps over the same span
    /// counts it once, as a window would. A session starts at
    /// `Duration::ZERO`, which leaves every step at the same instant.
    ///
    /// The UI paces its own animations by that clock, so an interval is
    /// what moves a fade or a highlight of the UI's own with no window.
    pub fn with_frame_interval(mut self, interval: Duration) -> Self {
        self.frame_interval = interval;
        self
    }

    /// Sets the time each later [`Session::step`] covers; see
    /// [`Session::with_frame_interval`].
    pub fn set_frame_interval(&mut self, interval: Duration) {
        self.frame_interval = interval;
    }

    /// Runs one frame: [`Game::frame`] records its draws, and the engine
    /// draws exactly those into the target, replacing what was there.
    ///
    /// Nothing is timed for you — wrap the call to measure it. Drawing
    /// never ticks: [`Session::tick`] is the only thing that simulates. A
    /// step advances the clock by
    /// [`with_frame_interval`](Session::with_frame_interval), which is the
    /// `dt` the frame reads.
    ///
    /// A floating UI window just opened may need a few more `step` calls
    /// before it draws; a capture taken right after may not show it.
    pub fn step(&mut self) -> FrameStats {
        self.start();
        let Self {
            game,
            config,
            renderer,
            audio,
            input,
            saves,
            overlay,
            device,
            queue,
            target,
            size,
            simulated,
            drawn,
            run,
            last_camera,
            cursor,
            frame_interval,
            stale,
            ..
        } = self;

        let elapsed = (*simulated).max(*drawn);
        let time = FrameTime {
            dt: *frame_interval,
            elapsed,
            alpha: 0.0,
        };
        #[cfg(feature = "ui")]
        overlay.set_clock(elapsed);
        *cursor = overlay.frame(device, queue, |layer| {
            let engine = Engine::new(device, queue, *size, config, *last_camera);
            let recording = Recording {
                renderer,
                input,
                simulating: Simulating { audio, saves, run },
            };
            game.frame(&mut recording.frame_context(engine, time, layer));
        });
        *last_camera = renderer.camera();
        audio.flush(last_camera.view());
        // A session's store has no name, so this writes nothing; it exists
        // for the loop behind a window.
        input.flush();
        saves.flush();
        *drawn += *frame_interval;
        *stale = true;
        FrameStats(renderer.render_to(device, queue, target, overlay))
    }

    /// Moves the pointer to `at`, in physical pixels from the target's top
    /// left, which is what
    /// [`FrameContext::pointer`](crate::FrameContext::pointer) reads.
    ///
    /// The next tick or step reads it, and it stays there until this moves
    /// it again. The distance it moves is what a
    /// [`PointerDelta`](crate::PointerDelta) binding reads, exactly as a
    /// cursor's is, and the UI reads the same move.
    pub fn set_pointer(&mut self, at: Vec2) {
        self.feed(Driven::Pointed(at));
    }

    /// Presses `control`, which every action bound to it reads as down, and
    /// which the UI reads as the same press.
    ///
    /// The next tick and the step after it read the press as an edge, and no
    /// tick or step after them reads that edge again. The control stays down
    /// until [`Session::release`].
    pub fn press(&mut self, control: impl Into<Switch>) {
        self.feed(Driven::Switched(control.into(), true));
    }

    /// Releases `control`, which the next tick and the step after it read as
    /// an edge the same way.
    pub fn release(&mut self, control: impl Into<Switch>) {
        self.feed(Driven::Switched(control.into(), false));
    }

    /// Moves `lane` of the pointer by `pixels`, counted right and up as
    /// [`Session::set_pointer`] counts them.
    ///
    /// An axis bound to that lane reads it through its own scale, a
    /// fraction of what it moved. The UI reads nothing of it. The next tick
    /// or step reads it: a lane reports a distance since the last reading,
    /// never a place.
    pub fn pointer_delta(&mut self, lane: PointerDelta, pixels: f32) {
        self.feed(Driven::Moved(lane, pixels));
    }

    /// Turns `lane` of the wheel by `notches`, counted right and away: one
    /// notch is one step of a mouse wheel, the same on every target.
    ///
    /// An axis bound to that lane reads it through its own scale, a
    /// fraction of what it turned, and the UI scrolls by what a window
    /// reports for those notches. The next tick or step reads it: a lane
    /// reports a distance since the last reading, never a place.
    pub fn wheel_delta(&mut self, lane: WheelDelta, notches: f32) {
        self.feed(Driven::Turned(lane, notches));
    }

    /// Types `text` into the UI, wherever it holds the keyboard.
    ///
    /// The next [`Session::step`] reads it. The game's own actions read
    /// nothing of it: text belongs to the UI layer, and an action reads
    /// controls.
    #[cfg(feature = "ui")]
    pub fn type_text(&mut self, text: &str) {
        self.feed(Driven::Typed(text.to_owned()));
    }

    /// Drives one move into the controls the game reads and the UI both.
    fn feed(&mut self, driven: Driven) {
        driven.drive(&mut self.input);
        #[cfg(feature = "ui")]
        if let Some(event) = driven.ui_event(&self.input, self.overlay.pixels_per_point()) {
            self.overlay.feed(event);
        }
        self.stale = true;
    }

    /// Starts a tick or a step as the loop behind a window starts one of its
    /// own: closes a snapshot where the controls have moved since the last
    /// one.
    fn start(&mut self) {
        if core::mem::take(&mut self.stale) {
            self.input.sample(self.simulated.max(self.drawn));
        }
    }

    /// Waits until the GPU has finished every submitted frame.
    ///
    /// [`Session::step`] returns at submission; fence each step to cap work
    /// in flight at one frame (vsync's bound), so step times measure frame
    /// cost, not queue depth.
    pub fn wait_for_gpu(&self) -> Result<(), Error> {
        wait_for_gpu(&self.device)
    }

    /// Reads the target back: `4 * width * height` bytes of sRGB-encoded RGBA,
    /// row by row from the top left, with no padding between rows.
    ///
    /// Every call waits for the GPU and allocates, which suits tests, not
    /// measurement done every frame. Before the first [`Session::step`] the
    /// pixels are undefined.
    pub fn pixels(&self) -> Result<Vec<u8>, Error> {
        let row = self.size.x * 4;
        let padded_row = row.next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT);
        let readback = self.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("mirage-engine headless readback"),
            size: u64::from(padded_row) * u64::from(self.size.y),
            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
            mapped_at_creation: false,
        });

        let mut encoder = self
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("mirage-engine headless readback"),
            });
        encoder.copy_texture_to_buffer(
            wgpu::TexelCopyTextureInfo {
                texture: &self.color,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            wgpu::TexelCopyBufferInfo {
                buffer: &readback,
                layout: wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(padded_row),
                    rows_per_image: Some(self.size.y),
                },
            },
            wgpu::Extent3d {
                width: self.size.x,
                height: self.size.y,
                depth_or_array_layers: 1,
            },
        );
        self.queue.submit([encoder.finish()]);

        readback.slice(..).map_async(wgpu::MapMode::Read, |_| {});
        wait_for_gpu(&self.device)?;

        let mapped = readback.slice(..).get_mapped_range();
        let pixels = mapped
            .chunks(padded_row as usize)
            .flat_map(|padded| &padded[..row as usize])
            .copied()
            .collect();
        drop(mapped);
        readback.unmap();

        Ok(pixels)
    }

    /// The target's size in physical pixels, as
    /// [`FrameContext::window_size`](crate::FrameContext::window_size)
    /// reports it to the game.
    pub fn size(&self) -> UVec2 {
        self.size
    }

    /// Whether the game has requested the end of the run through
    /// [`FrameContext::close`](crate::FrameContext::close), which a
    /// window would have closed on.
    ///
    /// A session has no loop to end: it runs every tick and step the caller
    /// calls for, and this stays true.
    pub fn closed(&self) -> bool {
        self.run.closing()
    }

    /// The cursor the last [`Session::step`] drew the pointer as: what the
    /// frame set through
    /// [`FrameContext::set_cursor`](crate::FrameContext::set_cursor), or
    /// the UI's where the UI sets a cursor of its own.
    ///
    /// [`Cursor::Arrow`] before the first step, and where a step's frame
    /// set none. A cursor the UI sets that [`Cursor`] does not hold reads
    /// as the nearest one it holds. [`Cursor::Held`] reads back like any
    /// other: a session has no window to hold a pointer in, so
    /// [`Session::set_pointer`] places it as it always does.
    pub fn cursor(&self) -> Cursor {
        self.cursor
    }

    /// The game being driven, for code that reads it between steps.
    pub fn game(&self) -> &G {
        &self.game
    }

    /// The game being driven, for code that changes it between steps.
    pub fn game_mut(&mut self) -> &mut G {
        &mut self.game
    }
}

/// Counts one [`Session::step`] turned the game's draws into.
///
/// Material variety never splits a batch, so these counts measure the
/// frame's mesh and slot collapse, not its color variety. Translucent draws
/// count with the rest, batched in a sorted pass of their own.
#[derive(Clone, Copy, Debug)]
pub struct FrameStats(RenderStats);

impl FrameStats {
    /// Instanced draw count the frame became.
    pub fn draw_calls(&self) -> u32 {
        self.0.draw_calls
    }

    /// Instance count those draws covered, one per drawn material slot.
    pub fn instances(&self) -> u32 {
        self.0.instances
    }
}

/// Blocks until the GPU has finished the work submitted so far — allowed
/// here because the `offscreen` feature never builds for the web.
pub(crate) fn wait_for_gpu(device: &wgpu::Device) -> Result<(), Error> {
    device
        .poll(wgpu::PollType::wait_indefinitely())
        .map(|_| ())
        .map_err(|error| Error::msg(format!("the GPU never finished the work: {error}")))
}

/// Acquires a device with no window behind it, blocking until it has one —
/// allowed here for the same reason [`wait_for_gpu`] is.
pub(crate) fn acquire_gpu() -> Result<(wgpu::Device, wgpu::Queue), Error> {
    pollster::block_on(async {
        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle());
        let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions::default())
            .await
            .map_err(|error| Error::msg(format!("{NO_ADAPTER}: {error}")))?;

        adapter
            .request_device(&wgpu::DeviceDescriptor {
                label: Some("mirage-engine headless"),
                ..Default::default()
            })
            .await
            .map_err(|error| Error::msg(format!("the graphics adapter refused a device: {error}")))
    })
}

mod driven;

#[cfg(test)]
mod tests;