f67d38b35cc5
capture.rs
//! Bounded, one-shot window screenshots for `ui.screenshot`.
//!
//! A request record owns the output path, crop, reply, deadline, document/focus identity and the
//! surface geometry it was admitted against. `craft_ui::capture::CaptureSlot` owns the strong
//! `egui::Context`; its 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/geometry
//! check has passed.
//!
//! Web qualification note: the pinned eframe web runner does not implement
//! `ViewportCommand::RequestPaintWhileHidden` (the native runner does). A hidden web capture that
//! is still settling therefore reaches its timeout. That fork gap is recorded as a prerequisite;
//! this module does not claim a hidden web capture works.
use std::sync::Arc;
use std::sync::mpsc::Sender;
use craft_ui::capture::{CaptureError, CaptureSlot};
use egui::{ColorImage, ViewportCommand};
use serde_json::{Value, json};
use web_time::{Duration, Instant};
use crate::FilmcraftApp;
/// At most this many queued, in-flight or completed-but-not-yet-drained requests.
pub(crate) const MAX_REQUESTS: usize = 4;
/// Per-image bound from the suite contract.
pub(crate) const MAX_IMAGE_BYTES: usize = 128 * 1024 * 1024;
/// Aggregate bound, counting completed images that have not been drained yet.
pub(crate) const MAX_TOTAL_BYTES: usize = 256 * 1024 * 1024;
/// The raw RGBA image is not the only copy alive while a capture is drained: the callback's
/// `ColorImage`, the cropped RGBA copy and the encoded PNG exist together, and on the web the PNG
/// is base64-encoded into the reply while all of those are still retained. Reserve this multiple
/// of the raw pixel bytes so admission actually bounds peak memory, not just the first buffer.
pub(crate) const CAPTURE_BUFFER_FACTOR: usize = 5;
/// Bytes reserved for one `width`×`height` RGBA capture, including the transient encode copies.
pub(crate) fn admitted_bytes(expected: [usize; 2]) -> Option<usize> {
expected[0].checked_mul(expected[1])?.checked_mul(std::mem::size_of::<egui::Color32>())?.checked_mul(CAPTURE_BUFFER_FACTOR)
}
const READY_DELAY: Duration = Duration::from_millis(250);
/// Accepted first UI passes (never discarded passes or hidden logic ticks).
const SETTLE_PASSES: u32 = 3;
const DEADLINE: Duration = Duration::from_secs(10);
/// Give up waiting for the exact monitor frame/timeline rest and capture what is shown (5 s).
const SETTLE_MAX: Duration = Duration::from_secs(5);
/// Accepted passes to wait for a named crop target that is not drawn yet (e.g. a panel shown by
/// the preceding control request). After this the request fails instead of capturing the window.
const CROP_SETTLE_PASSES: u32 = 3;
const REPAINT_INTERVAL: Duration = Duration::from_millis(16);
/// The host surface as reported by one `RawInput`. Raw input is fresh on hidden logic-only ticks;
/// `Context::input`/`viewport_rect` describe the last UI pass and are stale there.
///
/// Equality covers only what changes the captured pixels (viewport size, pixels per point and the
/// GPU texture limit). Minimized, occluded and native window focus are presentation flags: a
/// hidden or unfocused window still captures the forced paint that was already issued, so they
/// must neither invalidate an in-flight screenshot nor bump `capture_epoch`.
#[derive(Clone, Copy, Debug)]
pub(crate) struct SurfaceGeometry {
/// Logical viewport 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,
}
impl PartialEq for SurfaceGeometry {
/// Compares only the fields that change captured pixels: viewport size, pixels per point and
/// the GPU texture limit. The presentation-only minimized/occluded flags are deliberately
/// ignored, so minimizing, occluding or losing window focus does not invalidate an issued
/// capture.
fn eq(&self, other: &Self) -> bool {
self.viewport == other.viewport && self.pixels_per_point == other.pixels_per_point && self.max_texture_side == other.max_texture_side
}
}
impl SurfaceGeometry {
/// Snapshot the surface from a raw-input callback, reading the fresh `viewports`/`screen_rect`
/// geometry rather than the stale `InputState`. Missing or hostile fields fall back to
/// `previous` where possible; `None` means no usable zoom and pixels-per-point pair could be
/// established.
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();
let rect = info.inner_rect.or(raw.screen_rect);
let size = rect.map(|rect| rect.size()).filter(|size| size.x.is_finite() && size.y.is_finite() && size.x > 0.0 && size.y > 0.0);
let viewport = size.or(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 })
}
/// Pixel size the backend will present: viewport points scaled by pixels per point and
/// rounded. If either axis exceeds the texture limit, both axes shrink by the same factor to
/// a positive limit, matching wgpu's `surface_fit`; per-axis clamping would predict the wrong
/// image. A zero/unknown texture limit disables shrinking.
/// `None` when the viewport is missing, non-finite, empty or the size 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 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)
};
let [width, height] = [axis(viewport.x)?, axis(viewport.y)?];
// Match the wgpu backend's `surface_fit`: when either axis exceeds the device limit, both
// axes shrink by the same factor and the longer side becomes exactly the limit. Clamping
// each axis independently predicted a wider/taller image than the surface actually has.
let max = if self.max_texture_side == 0 { usize::MAX } else { self.max_texture_side };
if width <= max && height <= max {
return Some([width, height]);
}
let longest = width.max(height);
let scale = max as f64 / longest as f64;
let fit = |side: usize| -> usize { if side == longest { max } else { ((side as f64 * scale).floor() as usize).clamp(1, max) } };
Some([fit(width), fit(height)])
}
/// Pixels per point of the delivered screenshot texture.
///
/// egui-wgpu's `surface_fit` shrinks an oversized window's surface by one factor and draws it
/// at `pixels_per_point * render_scale`; a crop expressed in points must use that rendered
/// scale, not the native one. A window within the limit keeps the native factor exactly, so a
/// one-pixel rounding difference between `viewport * ppp` and the integer window size never
/// becomes a bogus sub-1 scale.
fn captured_pixels_per_point(self) -> f32 {
let native = self.pixels_per_point;
if !native.is_finite() || native <= 0.0 {
return 1.0;
}
let Some(viewport) = self.viewport else { return native };
if !viewport.x.is_finite() || !viewport.y.is_finite() || viewport.x <= 0.0 || viewport.y <= 0.0 || self.max_texture_side == 0 {
return native;
}
let axis = |points: f32| (f64::from(points) * f64::from(native)).round();
let (width, height) = (axis(viewport.x), axis(viewport.y));
if !width.is_finite() || !height.is_finite() || width <= 0.0 || height <= 0.0 {
return native;
}
let longest = width.max(height);
let limit = self.max_texture_side as f64;
if longest <= limit {
return native;
}
// Match egui-wgpu exactly: it casts `surface_fit`'s scale to f32 and then multiplies the
// f32 pixels-per-point by it.
let render_scale = (limit / longest) as f32;
let effective = native * render_scale;
if effective.is_finite() && effective > 0.0 { effective } else { native }
}
/// Raw RGBA bytes of [`Self::expected_size`], checked for multiplication overflow; `None`
/// when the surface has no capturable size.
fn expected_bytes(self) -> Option<usize> {
let [width, height] = self.expected_size()?;
width.checked_mul(height)?.checked_mul(std::mem::size_of::<egui::Color32>())
}
}
/// Which sequence and project revision the request belongs to.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct DocumentId {
sequence: Option<u64>,
revision: u64,
}
/// 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,
document: DocumentId,
focus: Option<egui::Id>,
}
impl CaptureGeometry {
/// Pixel size implied by the bound surface geometry; `None` when it is not capturable.
fn expected_size(self) -> Option<[usize; 2]> {
self.surface.expected_size()
}
/// Raw RGBA byte count implied by the bound surface, with the same overflow rule as
/// [`SurfaceGeometry::expected_bytes`].
fn expected_bytes(self) -> Option<usize> {
self.surface.expected_bytes()
}
}
/// A screenshot crop named by a widget id. Resolved at issue time from the pass that is actually
/// captured, never from the control callback that admitted the request (that pass may be two
/// layouts old or may not have drawn the panel at all).
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum CropTarget {
Element(String),
}
impl CropTarget {
/// Resolve the named element against the accepted pass's automation registry. Only an element
/// drawn in the current pass with a finite, non-empty rectangle is accepted; a stale
/// previous-pass rectangle or an unknown id is an error, never a fallback to the whole window.
fn resolve(&self, registry: &crate::automation::Registry) -> Result<[f32; 4], String> {
let Self::Element(id) = self;
let element = registry
.find_current(id)
.ok_or_else(|| format!("screenshot failed: `{id}` was not drawn in the captured pass (the panel may be closed or hidden; see ui.elements)"))?;
let [x, y, width, height] = element.rect;
if ![x, y, width, height].iter().all(|value| value.is_finite()) || width <= 0.0 || height <= 0.0 {
return Err(format!("screenshot failed: `{id}` has an empty or non-finite rectangle"));
}
Ok(element.rect)
}
}
struct Shot {
token: u64,
path: Option<String>,
crop_target: Option<CropTarget>,
/// The crop resolved from the accepted pass that was captured (set at issue time).
crop: Option<[f32; 4]>,
/// Accepted passes the named crop target was missing, while a just-shown panel lays out.
crop_misses: u32,
reply: Sender<Value>,
deadline: Instant,
ready_at: Instant,
frames: u32,
issued: bool,
document: DocumentId,
focus: Option<egui::Id>,
geometry: CaptureGeometry,
geometry_epoch: u64,
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 request is queued, in flight or completed-but-not-yet-drained.
pub(crate) fn is_empty(&self) -> bool {
self.requests.is_empty()
}
/// True while at least one admitted request has not been handed to a `Screenshot` callback.
fn has_unissued(&self) -> bool {
self.requests.iter().any(|shot| !shot.issued)
}
/// Sum of every request's byte reservation, including completed-but-undrained captures;
/// saturates instead of overflowing.
fn reserved(&self) -> usize {
self.requests.iter().fold(0usize, |sum, shot| sum.saturating_add(shot.reserved))
}
}
/// Allocate the next request token, wrapping after `u64::MAX` and skipping zero so a token is
/// always usable as a presence marker.
fn next_token(shots: &mut Shots) -> u64 {
let mut token = shots.token.wrapping_add(1);
if token == 0 {
token = 1;
}
shots.token = token;
token
}
/// Build the JSON error reply carrying `token`, so the client can match a rejection to the
/// request it sent.
fn error_reply(token: u64, message: impl std::fmt::Display) -> Value {
json!({"ok": false, "error": message.to_string(), "request": token})
}
/// Send an error reply for `token`, ignoring a client that has already disconnected.
fn reject(reply: Sender<Value>, token: u64, message: impl std::fmt::Display) {
let _ = reply.send(error_reply(token, message));
}
/// The active sequence id (none when no sequence is open) and project revision that a capture
/// is bound to.
fn active_document(app: &FilmcraftApp) -> DocumentId {
DocumentId { sequence: app.session.state.active_sequence.map(|id| id.0), revision: app.session.revision }
}
/// The widget currently holding keyboard focus, part of the capture identity.
fn current_focus(ctx: &egui::Context) -> Option<egui::Id> {
ctx.memory(|memory| memory.focused())
}
/// Refresh the fresh raw-input surface/identity snapshot. Called from `raw_input_hook`, so it runs
/// on both UI and hidden logic-only callbacks and never reads the stale `InputState` rectangle.
pub(crate) fn note_raw_geometry(app: &mut FilmcraftApp, ctx: &egui::Context, raw: &egui::RawInput) {
let previous = app.capture_geometry;
let Some(surface) = SurfaceGeometry::from_raw(raw, ctx, previous.map(|geometry| geometry.surface)) else {
app.capture_geometry = None;
app.capture_epoch = app.capture_epoch.wrapping_add(1);
return;
};
let geometry = CaptureGeometry { surface, document: active_document(app), focus: current_focus(ctx) };
let changed = app.capture_geometry != Some(geometry);
// Keep the presentation flags fresh even when they did not change the capture geometry.
app.capture_geometry = Some(geometry);
if changed {
app.capture_epoch = app.capture_epoch.wrapping_add(1);
}
}
/// Pick up document/revision and keyboard-focus changes made since the raw-input snapshot (a
/// control request, or the UI pass that admitted a `ui.screenshot` at its end).
fn refresh_identity(app: &mut FilmcraftApp, ctx: &egui::Context) {
let Some(geometry) = app.capture_geometry else { return };
let refreshed = CaptureGeometry { document: active_document(app), focus: current_focus(ctx), ..geometry };
let changed = refreshed != geometry;
app.capture_geometry = Some(refreshed);
if changed {
app.capture_epoch = app.capture_epoch.wrapping_add(1);
}
}
/// Admit one `ui.screenshot` request without issuing it. Counts queued, in-flight and
/// completed-but-undrained requests and reserves the raw image plus its encode/encode-reply buffers
/// before capture.
pub(crate) fn admit(app: &mut FilmcraftApp, ctx: &egui::Context, path: Option<String>, crop: Option<CropTarget>, reply: Sender<Value>) {
refresh_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(raw) = geometry.expected_bytes() else {
return reject(reply, token, "screenshot failed: the window size overflows the screenshot budget");
};
if raw > MAX_IMAGE_BYTES {
return reject(
reply,
token,
format!(
"screenshot budget exceeded: {raw} raw bytes for one {}×{} image, over the {MAX_IMAGE_BYTES}-byte per-image limit",
expected[0], expected[1]
),
);
}
let Some(reserved) = admitted_bytes(expected) else {
return reject(reply, token, "screenshot failed: the window size overflows the screenshot budget");
};
if reserved > MAX_TOTAL_BYTES {
return reject(
reply,
token,
format!(
"screenshot budget exceeded: one {}×{} capture needs up to {reserved} bytes including the crop/encode reply buffers, over the {MAX_TOTAL_BYTES}-byte 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,
crop_target: crop,
crop: None,
crop_misses: 0,
reply,
deadline: now + DEADLINE,
ready_at: now + READY_DELAY,
frames: 0,
issued: false,
document: geometry.document,
focus: geometry.focus,
geometry,
geometry_epoch: app.capture_epoch,
expected,
reserved,
slot: Some(slot),
callback: Some(callback),
});
ctx.request_repaint();
}
/// Why the request's bound document/revision or keyboard focus no longer matches. `None`
/// means identity is unchanged; a mismatch must reject rather than save pixels from another
/// document or focus.
fn identity_reason(app: &FilmcraftApp, ctx: &egui::Context, shot: &Shot) -> Option<&'static str> {
if active_document(app) != shot.document {
Some("the document or project revision changed while the capture was queued")
} else if current_focus(ctx) != shot.focus {
Some("the keyboard focus changed while the capture was queued")
} else {
None
}
}
/// Why the live surface snapshot or capture epoch differs from the one this request was
/// admitted or issued against. `None` means the geometry is still the one it reserved for.
fn geometry_reason(app: &FilmcraftApp, shot: &Shot) -> Option<&'static str> {
if app.capture_geometry != Some(shot.geometry) || app.capture_epoch != shot.geometry_epoch {
Some("the window geometry changed while the capture was queued")
} else {
None
}
}
/// Re-admit an unissued request against the current geometry: cancel its old slot, check the
/// per-image and aggregate budgets including every other request, and reset its settled
/// frames, crop misses and ready time. On failure nothing is changed and the caller rejects
/// it; on success the request is unissued again and must collect fresh settling passes.
fn retry_geometry(app: &mut FilmcraftApp, ctx: &egui::Context, index: usize) -> Result<(), String> {
let now = Instant::now();
let current = app.capture_geometry.ok_or_else(|| "the window geometry is no longer known".to_string())?;
let expected = current.expected_size().ok_or_else(|| "the window has no capturable size".to_string())?;
let raw = current.expected_bytes().ok_or_else(|| "the window size overflows the screenshot budget".to_string())?;
if raw > MAX_IMAGE_BYTES {
return Err(format!("the window now needs {raw} raw bytes, over the {MAX_IMAGE_BYTES}-byte per-image limit"));
}
let reserved = admitted_bytes(expected).ok_or_else(|| "the window size overflows the screenshot budget".to_string())?;
let others = app.shots.requests.iter().enumerate().filter(|(i, _)| *i != index).fold(0usize, |sum, (_, shot)| sum.saturating_add(shot.reserved));
if others.saturating_add(reserved) > MAX_TOTAL_BYTES {
return Err(format!("the window now needs {reserved} bytes, over the {MAX_TOTAL_BYTES}-byte aggregate limit"));
}
let Some(current_geometry) = app.capture_geometry else { return Err("the window geometry changed repeatedly".into()) };
let (slot, callback) = CaptureSlot::new(ctx, ctx.viewport_id(), MAX_IMAGE_BYTES);
let shot = app.shots.requests.get_mut(index).ok_or_else(|| "the screenshot request disappeared".to_string())?;
if let Some(old) = shot.slot.take() {
old.cancel();
}
shot.callback = Some(callback);
shot.slot = Some(slot);
shot.geometry = current_geometry;
shot.geometry_epoch = app.capture_epoch;
shot.expected = expected;
shot.reserved = reserved;
shot.frames = 0;
shot.crop_misses = 0;
shot.ready_at = now + READY_DELAY;
shot.issued = false;
Ok(())
}
/// Whether an unissued request has waited for enough accepted passes, including the bounded
/// maximum when the monitor is still showing an inexact frame or the timeline is animating.
fn shot_is_settled(now: Instant, monitor_inexact: bool, timeline_still: u32, shot: &Shot) -> bool {
if now < shot.ready_at || shot.frames < SETTLE_PASSES {
return false;
}
!((monitor_inexact || timeline_still < 2) && now < shot.ready_at + SETTLE_MAX)
}
/// The result of trying to issue one settled request. Every variant keeps the original admission
/// order: identity failures reject, geometry changes retry, a missing crop target waits a bounded
/// number of passes, and everything else issues in the current accepted UI pass.
enum IssueOutcome {
Identity(String),
GeometryRetry,
CropDeferred,
Failed(String),
Issued,
}
/// Decide one settled request: reject on identity change, ask for a geometry retry, defer a
/// not-yet-drawn crop target for a bounded number of accepted passes, or issue the screenshot
/// with the crop resolved from this pass. The callback is taken at most once and `issued` is
/// set only when the viewport command was sent.
fn try_issue_shot(app: &mut FilmcraftApp, ctx: &egui::Context, index: usize) -> IssueOutcome {
let shot = &app.shots.requests[index];
if let Some(reason) = identity_reason(app, ctx, shot) {
return IssueOutcome::Identity(reason.to_string());
}
if geometry_reason(app, shot).is_some() {
return IssueOutcome::GeometryRetry;
}
let crop_result = match shot.crop_target.as_ref() {
Some(target) => target.resolve(&app.auto).map(Some),
None => Ok(None),
};
let resolved_crop = match crop_result {
Ok(crop) => crop,
Err(message) => {
let shot = &mut app.shots.requests[index];
if shot.crop_misses < CROP_SETTLE_PASSES {
// The panel may be shown by a request processed just before this admission;
// let the next accepted pass draw it before giving up.
shot.crop_misses = shot.crop_misses.saturating_add(1);
return IssueOutcome::CropDeferred;
}
return IssueOutcome::Failed(message);
}
};
let shot = &mut app.shots.requests[index];
let Some(callback) = shot.callback.take() else {
return IssueOutcome::Failed("screenshot failed: the capture callback was already consumed".into());
};
shot.crop = resolved_crop;
ctx.send_viewport_cmd_to(ctx.viewport_id(), ViewportCommand::Screenshot(callback));
shot.issued = true;
IssueOutcome::Issued
}
/// Reject failed requests from the highest index down, so an earlier removal cannot shift a later
/// index and remove the wrong shot.
fn reject_failures(app: &mut FilmcraftApp, mut failures: Vec<(usize, String)>) {
failures.sort_unstable_by_key(|(i, _)| std::cmp::Reverse(*i));
for (i, message) in failures {
if i >= app.shots.requests.len() {
continue;
}
let shot = app.shots.requests.remove(i);
if let Some(slot) = shot.slot {
slot.cancel();
}
reject(shot.reply, shot.token, message);
}
}
/// Issue settled requests. Called from every real `App::ui` pass (never from a hidden
/// `run_logic` tick), including the accepted final pass of a multipass layout. `monitor_inexact`
/// describes the pass that just drew the monitor, so consume it here: it must not stay sticky and
/// delay every later screenshot until the 5 s settle maximum.
pub(crate) fn issue(app: &mut FilmcraftApp, ctx: &egui::Context) {
let monitor_inexact = std::mem::take(&mut app.monitor_inexact);
if ctx.will_discard() {
return;
}
let now = Instant::now();
let mut failures: Vec<(usize, String)> = Vec::new();
let mut retries: Vec<usize> = 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 !shot_is_settled(now, monitor_inexact, app.timeline_still, shot) {
continue;
}
match try_issue_shot(app, ctx, i) {
IssueOutcome::Identity(reason) => failures.push((i, reason)),
IssueOutcome::GeometryRetry => retries.push(i),
IssueOutcome::CropDeferred => ctx.request_repaint(),
IssueOutcome::Failed(message) => failures.push((i, message)),
IssueOutcome::Issued => {}
}
}
for i in retries.into_iter().rev() {
if let Err(message) = retry_geometry(app, ctx, i) {
failures.push((i, message));
}
}
reject_failures(app, failures);
if !app.shots.is_empty() {
ctx.request_repaint_after(REPAINT_INTERVAL);
}
}
/// The next step for one drain scan position. `Keep` advances to the next request; every removal
/// variant leaves the index unchanged so it sees the shot shifted into place.
enum DrainStep {
Keep,
Timeout,
Identity(String),
Geometry,
Complete(Result<Arc<ColorImage>, CaptureError>),
}
/// Classify one drain position before removing anything: check the deadline first, then
/// identity, then geometry (an unissued request keeps waiting for a retry, while in-flight
/// stale pixels are rejected), and finally take a completed slot. `Keep` leaves the request
/// in place and advances the scan.
fn drain_step(app: &FilmcraftApp, ctx: &egui::Context, index: usize, now: Instant) -> DrainStep {
let shot = &app.shots.requests[index];
if now >= shot.deadline {
return DrainStep::Timeout;
}
if let Some(reason) = identity_reason(app, ctx, shot) {
return DrainStep::Identity(reason.to_string());
}
if geometry_reason(app, shot).is_some() {
if !shot.issued {
// The next accepted UI pass re-creates the slot against the fresh geometry.
return DrainStep::Keep;
}
// Geometry changed while the callback was already issued: reject stale pixels rather
// than pairing them with the new surface.
return DrainStep::Geometry;
}
if !shot.issued {
return DrainStep::Keep;
}
let Some(result) = shot.slot.as_ref().and_then(CaptureSlot::take) else {
return DrainStep::Keep;
};
DrainStep::Complete(result)
}
/// Remove one request, cancel its slot and send its error reply; later requests shift down by
/// one index.
fn remove_and_reject(app: &mut FilmcraftApp, index: usize, message: impl std::fmt::Display) {
let shot = app.shots.requests.remove(index);
if let Some(slot) = shot.slot {
slot.cancel();
}
reject(shot.reply, shot.token, message);
}
/// Build the saved-image reply, using the rendered scale of the delivered texture for crops.
fn image_reply(shot: &Shot, image: &ColorImage) -> Value {
if image.size != shot.expected {
return 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]
),
);
}
let captured_ppp = shot.geometry.surface.captured_pixels_per_point();
let mut reply = crate::control::save_screenshot_with_ppp(image, shot.path.as_deref(), shot.crop, captured_ppp);
if let Some(object) = reply.as_object_mut() {
object.insert("request".into(), json!(shot.token));
}
reply
}
/// Cancel any remaining callback, turn the captured image or error into the reply and send it
/// exactly once. A pixel size that differs from the reserved size becomes an error reply
/// instead of writing an image for the wrong surface.
fn complete_shot(mut shot: Shot, result: Result<Arc<ColorImage>, CaptureError>) {
if let Some(slot) = shot.slot.take() {
slot.cancel();
}
let reply = match result {
Ok(image) => image_reply(&shot, &image),
Err(error) => error_reply(shot.token, error),
};
let _ = shot.reply.send(reply);
}
/// 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 FilmcraftApp, ctx: &egui::Context) {
let mut i = 0;
while i < app.shots.requests.len() {
let now = Instant::now();
match drain_step(app, ctx, i, now) {
DrainStep::Keep => i += 1,
DrainStep::Timeout => remove_and_reject(app, i, "no frame was presented before the screenshot timeout"),
DrainStep::Identity(reason) => remove_and_reject(app, i, format!("screenshot failed: {reason}")),
DrainStep::Geometry => remove_and_reject(app, i, "screenshot failed: the window geometry changed while the capture was in flight"),
DrainStep::Complete(result) => {
let shot = app.shots.requests.remove(i);
complete_shot(shot, result);
}
}
}
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 FilmcraftApp) {
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. The screenshot command itself forces one paint once issued.
pub(crate) fn request_hidden_paint(app: &FilmcraftApp, ctx: &egui::Context) {
if app.shots.has_unissued() {
ctx.send_viewport_cmd(ViewportCommand::RequestPaintWhileHidden);
}
}
#[cfg(test)]
mod tests;
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.