GitCorner

Code

ossartcraftcadcraft🌐
a770fa5a5e5f
//! Bounded, one-shot window screenshots for `ui.screenshot`.
//!
//! The request record owns the output path, reply, deadline, document/focus identity and the
//! geometry it was admitted against. The shared `craft_ui::capture::CaptureSlot` owns the strong
//! `egui::Context`; its screenshot callback holds only a weak reference and never writes a file.
//! Files are encoded and written only from the logic drain, after the deadline and every identity
//! check have passed.

use std::sync::mpsc::Sender;

use craft_ui::capture::CaptureSlot;
use egui::ViewportCommand;
use serde_json::{Value, json};
use web_time::{Duration, Instant};

use crate::CadApp;

/// At most this many queued, in-flight or completed-but-not-yet-drained requests.
pub(crate) const MAX_REQUESTS: usize = 4;
/// CADCraft keeps its stricter 64 MiB per-image bound (the suite default is 128 MiB).
pub(crate) const MAX_IMAGE_BYTES: usize = 64 * 1024 * 1024;
/// CADCraft keeps the aggregate reservation at the same 64 MiB bound. Completed but undrained
/// images still own their reservation, so they count against this limit.
pub(crate) const MAX_TOTAL_BYTES: usize = 64 * 1024 * 1024;

const READY_DELAY: Duration = Duration::from_millis(120);
/// Accepted settled passes (never discarded passes or hidden logic ticks).
const SETTLE_PASSES: u32 = 3;
const DEADLINE: Duration = Duration::from_secs(8);
const REBUILD_WAIT: Duration = Duration::from_secs(6);
const REPAINT_INTERVAL: Duration = Duration::from_millis(16);

/// The host surface as reported by one `RawInput`. `RawInput` is the fresh source on hidden
/// logic-only ticks; `Context::input`/`viewport_rect` describe the last UI pass and are stale
/// there.
///
/// The equality used for the capture epoch is deliberately strict: OS focus and visibility
/// (`window_focused`, `minimized`, `occluded`) are part of it even though they are not geometry.
/// A focus or visibility transition can change what the presented frame contains (menu state,
/// active-window styling, a hidden surface), so a capture admitted before it is rejected rather
/// than risking an image from another epoch. Do not narrow this to size/DPI/zoom without a
/// replacement visibility check and a measured acceptance path.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct SurfaceGeometry {
    /// Logical content size in points. A minimized window keeps its last known size so a forced
    /// hidden paint can still be requested; `None` only before any size was ever reported.
    viewport: Option<egui::Vec2>,
    /// Native pixels per point times egui's interface zoom.
    pixels_per_point: f32,
    max_texture_side: usize,
    minimized: bool,
    occluded: bool,
    window_focused: bool,
}

impl SurfaceGeometry {
    /// `Some(size)` only when both axes are finite and strictly positive; rejects degenerate viewport sizes before they enter a `SurfaceGeometry` snapshot.
    fn valid_size(size: egui::Vec2) -> Option<egui::Vec2> {
        (size.x.is_finite() && size.y.is_finite() && size.x > 0.0 && size.y > 0.0).then_some(size)
    }

    /// The fresh raw hook's surface. Called from `raw_input_hook`, so it runs on both UI and
    /// hidden logic-only callbacks and never reads the stale `InputState` rectangle.
    fn from_raw(raw: &egui::RawInput, ctx: &egui::Context, previous: Option<Self>) -> Option<Self> {
        let info = raw.viewports.get(&raw.viewport_id).cloned().unwrap_or_default();
        // `InputState::viewport_rect` is `RawInput::screen_rect`, falling back to the previous
        // pass's rect; the pass snapshot uses the same source so the two agree bit for bit. The
        // screenshot is of the UI content rect (what kittest renders and the plan binds to), so
        // remove the safe-area insets here as `InputState::content_rect` does.
        let insets = raw.safe_area_insets.unwrap_or_else(|| ctx.input(|input| input.safe_area_insets()));
        let rect = raw.screen_rect.map(|rect| rect - insets);
        let viewport = rect.and_then(|rect| Self::valid_size(rect.size())).or_else(|| previous.and_then(|previous| previous.viewport));
        let zoom = ctx.zoom_factor();
        if !zoom.is_finite() || zoom <= 0.0 {
            return None;
        }
        let pixels_per_point = info
            .native_pixels_per_point
            .map(|native| native * zoom)
            .filter(|pixels| pixels.is_finite() && *pixels > 0.0)
            .or_else(|| previous.map(|previous| previous.pixels_per_point))
            .unwrap_or_else(|| ctx.pixels_per_point());
        if !pixels_per_point.is_finite() || pixels_per_point <= 0.0 {
            return None;
        }
        let max_texture_side = raw.max_texture_side.filter(|side| *side > 0).unwrap_or_else(|| ctx.input(|input| input.max_texture_side));
        let minimized = info.minimized.unwrap_or_else(|| previous.is_some_and(|previous| previous.minimized));
        let occluded = info.occluded.unwrap_or_else(|| previous.is_some_and(|previous| previous.occluded));
        Some(Self { viewport, pixels_per_point, max_texture_side, minimized, occluded, window_focused: raw.focused })
    }

    /// The settled surface of a UI pass: the content rect and ppp this pass renders (and is
    /// presented) with. The saved interface zoom takes effect at the start of a pass, so this is
    /// the only scale the presented frame can be expected to have.
    fn from_pass(ctx: &egui::Context, previous: Option<Self>) -> Option<Self> {
        let content = ctx.input(|input| input.content_rect().size());
        let viewport = Self::valid_size(content).or_else(|| previous.and_then(|previous| previous.viewport));
        let pixels_per_point = ctx.pixels_per_point();
        if !pixels_per_point.is_finite() || pixels_per_point <= 0.0 {
            return None;
        }
        let max_texture_side = ctx.input(|input| input.max_texture_side);
        let minimized = ctx.input(|input| input.viewport().minimized).unwrap_or_else(|| previous.is_some_and(|previous| previous.minimized));
        let occluded = ctx.input(|input| input.viewport().occluded).unwrap_or_else(|| previous.is_some_and(|previous| previous.occluded));
        let window_focused = ctx.input(|input| input.focused);
        Some(Self { viewport, pixels_per_point, max_texture_side, minimized, occluded, window_focused })
    }

    /// The pixel dimensions this surface would capture at: viewport points × pixels-per-point, rounded, each axis clamped to `max_texture_side` (0 means unlimited).
    /// `None` when the viewport is unknown/non-finite or an axis overflows `usize`.
    fn expected_size(self) -> Option<[usize; 2]> {
        let viewport = self.viewport?;
        if !viewport.x.is_finite() || !viewport.y.is_finite() || viewport.x <= 0.0 || viewport.y <= 0.0 {
            return None;
        }
        let max = if self.max_texture_side == 0 { usize::MAX } else { self.max_texture_side };
        let axis = |points: f32| -> Option<usize> {
            let pixels = (f64::from(points) * f64::from(self.pixels_per_point)).round();
            if !pixels.is_finite() || pixels <= 0.0 || pixels > usize::MAX as f64 {
                return None;
            }
            Some((pixels as usize).min(max))
        };
        Some([axis(viewport.x)?, axis(viewport.y)?])
    }

    /// Raw `Color32` bytes for `expected_size()` (4 bytes per pixel), with checked multiplication; `None` on overflow.
    fn expected_bytes(self) -> Option<usize> {
        let [width, height] = self.expected_size()?;
        width.checked_mul(height)?.checked_mul(std::mem::size_of::<egui::Color32>())
    }
}

/// The immutable document and widget-focus identity a capture is bound to.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct CaptureIdentity {
    document: Option<u64>,
    /// Monotonic count of drawing switches in the engine, so A→B→A is still a change.
    document_epoch: u64,
    focus: Option<egui::Id>,
}

/// Viewport geometry plus the immutable document and widget-focus identity a capture is bound to.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct CaptureGeometry {
    surface: SurfaceGeometry,
    identity: CaptureIdentity,
}

impl CaptureGeometry {
    /// Pixel dimensions of the bound surface, or `None` when it cannot be estimated.
    fn expected_size(self) -> Option<[usize; 2]> {
        self.surface.expected_size()
    }

    /// Raw image byte count of the bound surface, or `None` when it cannot be estimated.
    fn expected_bytes(self) -> Option<usize> {
        self.surface.expected_bytes()
    }
}

struct Shot {
    token: u64,
    path: Option<String>,
    reply: Sender<Value>,
    deadline: Instant,
    ready_at: Instant,
    frames: u32,
    issued: bool,
    identity: CaptureIdentity,
    identity_epoch: u64,
    /// The surface epoch at issue; a later change invalidates the in-flight image.
    surface_epoch: u64,
    geometry: SurfaceGeometry,
    expected: [usize; 2],
    reserved: usize,
    slot: Option<CaptureSlot>,
    callback: Option<egui::ScreenshotCallback>,
}

/// All admitted screenshots. `requests` includes queued, issued and completed-but-undrained
/// captures; nothing is removed before it has been replied to or timed out.
#[derive(Default)]
pub(crate) struct Shots {
    token: u64,
    requests: Vec<Shot>,
}

impl Shots {
    /// True when no queued, in-flight or completed-but-undrained request remains.
    pub(crate) fn is_empty(&self) -> bool {
        self.requests.is_empty()
    }

    /// True when at least one admitted request has not been issued yet; drives the hidden-window repaint request.
    pub(crate) fn has_unissued(&self) -> bool {
        self.requests.iter().any(|shot| !shot.issued)
    }

    /// Saturating sum of the byte reservations of all outstanding requests.
    fn reserved(&self) -> usize {
        self.requests.iter().fold(0usize, |sum, shot| sum.saturating_add(shot.reserved))
    }

    /// Test-only count of outstanding request records.
    #[cfg(test)]
    fn len(&self) -> usize {
        self.requests.len()
    }
}

/// Advance the per-app request token, wrapping and skipping 0.
fn next_token(shots: &mut Shots) -> u64 {
    let mut token = shots.token.wrapping_add(1);
    if token == 0 {
        token = 1;
    }
    shots.token = token;
    token
}

/// The JSON rejection envelope `{ok:false,error,request}` used by admission, issuance, drain and cancellation rejections; `control::save_screenshot` builds an identical envelope for its own failures.
fn error_reply(token: u64, message: impl std::fmt::Display) -> Value {
    json!({"ok": false, "error": message.to_string(), "request": token})
}

/// Send an `error_reply` to `reply`; a closed receiver is ignored so admission never blocks.
fn reject(reply: Sender<Value>, token: u64, message: impl std::fmt::Display) {
    let _ = reply.send(error_reply(token, message));
}

/// UID of the active drawing, or `None` when no drawing is open.
fn active_document(app: &CadApp) -> Option<u64> {
    app.session.docs.get(app.session.active).map(|doc| doc.uid)
}

/// The widget egui currently reports as keyboard-focused, if any.
fn current_focus(ctx: &egui::Context) -> Option<egui::Id> {
    ctx.memory(|memory| memory.focused())
}

/// Snapshot the active drawing UID, the monotonic document epoch and the focused widget together.
fn observed_identity(app: &CadApp, ctx: &egui::Context) -> CaptureIdentity {
    CaptureIdentity { document: active_document(app), document_epoch: app.session.doc_epoch, focus: current_focus(ctx) }
}

/// Store a fresh observation. The surface and identity epochs are independent: a surface change
/// re-baselines a queued request at issue, while any identity change rejects it, including one
/// that returns to the same document or focused widget.
fn observe(app: &mut CadApp, surface: SurfaceGeometry, identity: CaptureIdentity) {
    let previous = app.capture_geometry;
    let surface_changed = previous.is_none_or(|previous| previous.surface != surface);
    let identity_changed = previous.is_none_or(|previous| previous.identity != identity);
    if surface_changed || identity_changed {
        app.capture_geometry = Some(CaptureGeometry { surface, identity });
    }
    if surface_changed {
        app.capture_epoch = app.capture_epoch.wrapping_add(1);
    }
    if identity_changed {
        app.capture_identity_epoch = app.capture_identity_epoch.wrapping_add(1);
    }
}

/// Refresh the fresh raw-input surface/identity snapshot. Called from `raw_input_hook`, so it runs
/// on both UI and hidden logic-only callbacks.
pub(crate) fn note_raw_geometry(app: &mut CadApp, ctx: &egui::Context, raw: &egui::RawInput) {
    let previous = app.capture_geometry.map(|geometry| geometry.surface);
    let Some(surface) = SurfaceGeometry::from_raw(raw, ctx, previous) else {
        if app.capture_geometry.is_some() {
            app.capture_geometry = None;
            app.capture_epoch = app.capture_epoch.wrapping_add(1);
            app.capture_identity_epoch = app.capture_identity_epoch.wrapping_add(1);
        }
        return;
    };
    let identity = observed_identity(app, ctx);
    observe(app, surface, identity);
}

/// Refresh the settled geometry of a UI pass (content rect and ppp), from every pass so a pass
/// that applies the saved interface zoom is the one admission and issuance use.
///
/// An unusable pass snapshot invalidates the retained surface exactly like the raw path: the
/// previous geometry must not survive a pass whose pixels-per-point is invalid, or a later
/// admission could be bound to a surface no current pass renders. Both epochs grow so queued and
/// in-flight captures are re-based or rejected.
pub(crate) fn note_pass_geometry(app: &mut CadApp, ctx: &egui::Context) {
    let previous = app.capture_geometry.map(|geometry| geometry.surface);
    let Some(surface) = SurfaceGeometry::from_pass(ctx, previous) else {
        if app.capture_geometry.is_some() {
            app.capture_geometry = None;
            app.capture_epoch = app.capture_epoch.wrapping_add(1);
            app.capture_identity_epoch = app.capture_identity_epoch.wrapping_add(1);
        }
        return;
    };
    let identity = observed_identity(app, ctx);
    observe(app, surface, identity);
}

/// Refresh only the binding identity. Call after anything that can change the drawing or the
/// keyboard focus within one callback (each control command, opening completion), so an
/// intervening A→B→A transition is still seen.
pub(crate) fn note_identity(app: &mut CadApp, ctx: &egui::Context) {
    let Some(geometry) = app.capture_geometry else { return };
    let identity = observed_identity(app, ctx);
    observe(app, geometry.surface, identity);
}

/// Admit one `ui.screenshot` request without issuing it. Counts queued, in-flight and
/// completed-but-undrained requests and reserves the expected raw image bytes before any capture.
/// The reservation is the admission estimate; issuance re-bases it on the settled pass.
pub(crate) fn admit(app: &mut CadApp, ctx: &egui::Context, path: Option<String>, reply: Sender<Value>) {
    note_identity(app, ctx);
    let token = next_token(&mut app.shots);
    let Some(geometry) = app.capture_geometry else {
        return reject(reply, token, "screenshot failed: the window geometry is not known yet");
    };
    let Some(expected) = geometry.expected_size() else {
        return reject(reply, token, "screenshot failed: the window has no capturable size yet");
    };
    let Some(reserved) = geometry.expected_bytes() else {
        return reject(reply, token, "screenshot failed: the window size overflows the screenshot budget");
    };
    if reserved > MAX_IMAGE_BYTES {
        return reject(
            reply,
            token,
            format!(
                "screenshot budget exceeded: {reserved} bytes for one {}×{} image, over the {MAX_IMAGE_BYTES}-byte per-image limit",
                expected[0], expected[1]
            ),
        );
    }
    if app.shots.requests.len() >= MAX_REQUESTS {
        return reject(reply, token, format!("screenshot budget exceeded: {MAX_REQUESTS} requests are already outstanding"));
    }
    let total = app.shots.reserved().saturating_add(reserved);
    if total > MAX_TOTAL_BYTES {
        return reject(
            reply,
            token,
            format!("screenshot budget exceeded: {total} bytes reserved by outstanding requests, over the {MAX_TOTAL_BYTES}-byte limit"),
        );
    }
    let (slot, callback) = CaptureSlot::new(ctx, ctx.viewport_id(), MAX_IMAGE_BYTES);
    let now = Instant::now();
    app.shots.requests.push(Shot {
        token,
        path,
        reply,
        deadline: now + DEADLINE,
        ready_at: now + READY_DELAY,
        frames: 0,
        issued: false,
        identity: geometry.identity,
        identity_epoch: app.capture_identity_epoch,
        surface_epoch: app.capture_epoch,
        geometry: geometry.surface,
        expected,
        reserved,
        slot: Some(slot),
        callback: Some(callback),
    });
    ctx.request_repaint();
}

/// Human-readable reason when the live document, focus or document epoch differs from the shot's admission identity; `None` while all still match.
fn identity_reason(app: &CadApp, ctx: &egui::Context, shot: &Shot) -> Option<&'static str> {
    if active_document(app) != shot.identity.document {
        Some("the document changed while the capture was queued")
    } else if current_focus(ctx) != shot.identity.focus {
        Some("the keyboard focus changed while the capture was queued")
    } else if app.session.doc_epoch != shot.identity.document_epoch {
        Some("the drawing changed while the capture was queued")
    } else {
        None
    }
}

/// Any observed identity change since admission, including a transition that returned to the
/// same document or widget (`capture_identity_epoch` only ever grows).
fn identity_change(app: &CadApp, ctx: &egui::Context, shot: &Shot) -> Option<&'static str> {
    if app.capture_identity_epoch == shot.identity_epoch {
        return None;
    }
    Some(identity_reason(app, ctx, shot).unwrap_or("the drawing or keyboard focus changed while the capture was queued"))
}

/// Issue settled requests from the first non-discarded UI pass.
///
/// egui discards a pass only when `will_discard()` says so, and the final pass of a multi-pass
/// frame reports false; a hidden `run_logic` tick never reaches `issue` at all.
pub(crate) fn issue(app: &mut CadApp, ctx: &egui::Context) {
    if ctx.will_discard() {
        return;
    }
    // The draw may have moved the focus or switched drawings: observe that before judging.
    note_identity(app, ctx);
    let now = Instant::now();
    let building = app.canvas.building();
    let mut failures: Vec<(usize, String)> = Vec::new();
    for i in 0..app.shots.requests.len() {
        if app.shots.requests[i].issued {
            continue;
        }
        app.shots.requests[i].frames = app.shots.requests[i].frames.saturating_add(1);
        let shot = &app.shots.requests[i];
        if now < shot.ready_at || shot.frames < SETTLE_PASSES || (building && now < shot.ready_at + REBUILD_WAIT) {
            continue;
        }
        if let Some(reason) = identity_change(app, ctx, shot) {
            failures.push((i, reason.to_string()));
            continue;
        }
        // Re-base the expected image on the settled pass. The admission estimate can predate the
        // saved interface zoom, which egui applies at the start of a later pass.
        let Some(current) = app.capture_geometry else {
            failures.push((i, "screenshot failed: the window geometry is no longer known".into()));
            continue;
        };
        let Some(expected) = current.expected_size() else {
            failures.push((i, "screenshot failed: the window has no capturable size".into()));
            continue;
        };
        let Some(reserved) = current.expected_bytes() else {
            failures.push((i, "screenshot failed: the window size overflows the screenshot budget".into()));
            continue;
        };
        if reserved > MAX_IMAGE_BYTES {
            failures.push((
                i,
                format!(
                    "screenshot budget exceeded: {reserved} bytes for one {}×{} image, over the {MAX_IMAGE_BYTES}-byte per-image limit",
                    expected[0], expected[1]
                ),
            ));
            continue;
        }
        let total = app.shots.reserved().saturating_sub(shot.reserved).saturating_add(reserved);
        if total > MAX_TOTAL_BYTES {
            failures.push((
                i,
                format!("screenshot budget exceeded: {total} bytes reserved by outstanding requests, over the {MAX_TOTAL_BYTES}-byte limit"),
            ));
            continue;
        }
        let shot = &mut app.shots.requests[i];
        let Some(callback) = shot.callback.take() else {
            failures.push((i, "screenshot failed: the capture callback was already consumed".into()));
            continue;
        };
        ctx.send_viewport_cmd_to(ctx.viewport_id(), ViewportCommand::Screenshot(callback));
        shot.issued = true;
        shot.identity = current.identity;
        shot.geometry = current.surface;
        shot.expected = expected;
        shot.reserved = reserved;
        shot.surface_epoch = app.capture_epoch;
    }
    for (i, message) in failures.into_iter().rev() {
        let shot = app.shots.requests.remove(i);
        if let Some(slot) = shot.slot {
            slot.cancel();
        }
        reject(shot.reply, shot.token, message);
    }
    if !app.shots.is_empty() {
        ctx.request_repaint_after(REPAINT_INTERVAL);
    }
}

/// Drain completed slots and expire timed-out requests. Call from every logic callback (including
/// hidden ones). The deadline is checked before taking or writing an image.
pub(crate) fn drain(app: &mut CadApp, ctx: &egui::Context) {
    note_identity(app, ctx);
    let mut i = 0;
    while i < app.shots.requests.len() {
        let now = Instant::now();
        if now >= app.shots.requests[i].deadline {
            let shot = app.shots.requests.remove(i);
            if let Some(slot) = shot.slot {
                slot.cancel();
            }
            reject(shot.reply, shot.token, "no frame was presented before the screenshot timeout");
            continue;
        }
        if let Some(reason) = identity_change(app, ctx, &app.shots.requests[i]) {
            let shot = app.shots.requests.remove(i);
            if let Some(slot) = shot.slot {
                slot.cancel();
            }
            reject(shot.reply, shot.token, format!("screenshot failed: {reason}"));
            continue;
        }
        if !app.shots.requests[i].issued {
            // A queued request re-bases its geometry on the settled pass at issue.
            i += 1;
            continue;
        }
        if app.capture_epoch != app.shots.requests[i].surface_epoch
            || app.capture_geometry.map(|geometry| geometry.surface) != Some(app.shots.requests[i].geometry)
        {
            let shot = app.shots.requests.remove(i);
            if let Some(slot) = shot.slot {
                slot.cancel();
            }
            reject(shot.reply, shot.token, "screenshot failed: the window geometry changed while the capture was queued");
            continue;
        }
        let Some(result) = app.shots.requests[i].slot.as_ref().and_then(CaptureSlot::take) else {
            i += 1;
            continue;
        };
        let shot = app.shots.requests.remove(i);
        if let Some(slot) = shot.slot {
            slot.cancel();
        }
        match result {
            Ok(image) => {
                let reply = if image.size != shot.expected {
                    error_reply(
                        shot.token,
                        format!(
                            "screenshot is {}×{} pixels, expected {}×{}: the window changed size while it was captured",
                            image.size[0], image.size[1], shot.expected[0], shot.expected[1]
                        ),
                    )
                } else {
                    crate::control::save_screenshot(&image, shot.path.as_deref(), shot.token)
                };
                let _ = shot.reply.send(reply);
            }
            Err(error) => {
                let _ = shot.reply.send(error_reply(shot.token, error));
            }
        }
    }
    if !app.shots.is_empty() {
        ctx.request_repaint_after(REPAINT_INTERVAL);
    }
}

/// Cancel every queued/in-flight capture (app exit). Late callbacks see a dropped slot and write
/// nothing; clients receive one error reply instead of hanging past the transport timeout.
pub(crate) fn cancel_all(app: &mut CadApp) {
    for shot in app.shots.requests.drain(..) {
        if let Some(slot) = shot.slot {
            slot.cancel();
        }
        let _ = shot.reply.send(error_reply(shot.token, "screenshot cancelled: the app is closing"));
    }
}

/// Ask for a painted frame while a request is still queued, and on hidden logic ticks when a
/// capture is waiting for settlement. Native eframe honours `RequestPaintWhileHidden`; the web
/// runner currently logs it as unhandled, so web only schedules a repaint and hidden web captures
/// still reach their timeout (a documented limitation, not a success path).
pub(crate) fn request_hidden_paint(app: &CadApp, ctx: &egui::Context) {
    if app.shots.has_unissued() {
        #[cfg(not(target_arch = "wasm32"))]
        ctx.send_viewport_cmd(ViewportCommand::RequestPaintWhileHidden);
        ctx.request_repaint();
    }
}

#[cfg(test)]
mod tests;