Skip to main content

crabshell_ui/
screencopy.rs

1//! [`ScreencopyView`], a widget that shows what an output or a window
2//! shows, and what the platform reads and writes of it: the views to
3//! capture for, and the frames it captured.
4
5use std::cell::RefCell;
6use std::rc::Rc;
7use std::sync::atomic::{AtomicU64, Ordering};
8
9use crabshell_reactive::{Signal, untrack};
10
11use crate::capture::Capture;
12use crate::geometry::{Affine, Rect, Size};
13use crate::prop::{IntoProp, Prop};
14use crate::style::Style;
15use crate::tree::{Change, NodeId, NodeKind, Tree, borrow, replace};
16use crate::widgets::{Common, Element, ElementKind, Fit, Widget, visibility_methods};
17use crate::window::Window;
18
19/// Numbers every view mounted, in every window, so a platform's capture
20/// and a renderer's cache can't mix two up.
21static NEXT_VIEW: AtomicU64 = AtomicU64::new(0);
22
23/// The most dropped views kept for the platform to hear of; a shell
24/// without one stops counting there.
25const MAX_DROPPED: usize = 4096;
26
27thread_local! {
28  /// The ids of views dropped since [`dropped_captures`] last ran.
29  static DROPPED: RefCell<Vec<u64>> = const { RefCell::new(Vec::new()) };
30}
31
32/// The ids of screencopy views removed, or in windows dropped, since the
33/// last call, of either kind, so the platform can have the renderer let
34/// go of the frames and copies it kept for them.
35#[doc(hidden)]
36pub fn dropped_captures() -> Vec<u64> {
37  DROPPED.with(|dropped| std::mem::take(&mut *dropped.borrow_mut()))
38}
39
40/// A number no view or capture request had before.
41pub(crate) fn next_id() -> u64 {
42  NEXT_VIEW.fetch_add(1, Ordering::Relaxed)
43}
44
45/// What a [`ScreencopyView`] shows.
46#[non_exhaustive]
47#[derive(Clone, Debug, PartialEq, Eq, Hash)]
48pub enum CaptureSource {
49  /// The output of this name, such as `DP-1`.
50  Output(String),
51  /// The window of this id: a `Toplevel::id` from `cx.toplevels()`.
52  Toplevel(u64),
53}
54
55pub(crate) struct ScreencopyProps {
56  /// `None` for a view of a [`Capture`].
57  pub(crate) source: Option<Prop<CaptureSource>>,
58  pub(crate) capture: Option<Capture>,
59  pub(crate) crop: Option<Prop<Option<Rect>>>,
60  pub(crate) shown: Option<Signal<bool>>,
61  pub(crate) live: Option<Prop<bool>>,
62  pub(crate) paint_cursors: Option<Prop<bool>>,
63  pub(crate) fit: Option<Prop<Fit>>,
64}
65
66/// Shows what an output or a window shows, captured by the compositor,
67/// in the box its style's `width` and `height` give it, as an
68/// [`Image`](crate::Image) shows a picture. It draws nothing until the
69/// first frame arrives.
70///
71/// It captures one frame, unless it is `live`: then each change to the
72/// source brings a new frame, and a source that doesn't change sends
73/// none, so it wakes nothing. A source that isn't there yet, such as an
74/// output not plugged in, is waited for. When it goes, the last frame
75/// stays.
76///
77/// ```
78/// use crabshell_ui::{CaptureSource, ScreencopyView, Style};
79///
80/// let thumbnail = ScreencopyView::new(CaptureSource::Output(String::from("DP-1")))
81///     .live(true)
82///     .style(Style::new().width(192.0).height(108.0));
83/// ```
84pub struct ScreencopyView {
85  props: ScreencopyProps,
86  common: Common,
87}
88
89impl ScreencopyView {
90  /// A view of `source`: a [`CaptureSource`], or a closure that returns
91  /// one.
92  pub fn new(source: impl IntoProp<CaptureSource>) -> ScreencopyView {
93    ScreencopyView::with(Some(source.into_prop()), None)
94  }
95
96  /// A view of `capture`'s frame, which it shares with every other view
97  /// of it; the view captures nothing itself, so `live` and
98  /// `paint_cursors` do nothing. It draws nothing while the capture has
99  /// no frame.
100  pub fn of(capture: Capture) -> ScreencopyView {
101    ScreencopyView::with(None, Some(capture))
102  }
103
104  fn with(source: Option<Prop<CaptureSource>>, capture: Option<Capture>) -> ScreencopyView {
105    ScreencopyView {
106      props: ScreencopyProps {
107        source,
108        capture,
109        crop: None,
110        shown: None,
111        live: None,
112        paint_cursors: None,
113        fit: None,
114      },
115      common: Common::default(),
116    }
117  }
118
119  /// Shows only this part of the frame, in the source's logical pixels,
120  /// as an output's windows are placed, filling the view's box as `fit`
121  /// says. The part is cut to the frame, and one wholly outside it draws
122  /// nothing. `None`, the default, shows the whole frame. A view of a
123  /// source with a crop asks for the source's whole frame, at its own
124  /// resolution, so the part stays sharp. A window's logical pixels are
125  /// taken at the largest output scale, so with outputs of mixed scales
126  /// a crop of a window on a smaller-scale one misses its mark.
127  pub fn crop(mut self, rect: impl IntoProp<Option<Rect>>) -> ScreencopyView {
128    self.props.crop = Some(rect.into_prop());
129    self
130  }
131
132  /// Writes `true` to `shown` once the picture this view shows is on
133  /// screen: the compositor presented the window's frame that first drew
134  /// it, as its frame callback says. It writes `false` while the view has
135  /// no picture, from when it takes a new one until that is presented,
136  /// and while the view is hidden, outside the window or a clipping
137  /// ancestor, or its window has no surface. Give each view a signal of
138  /// its own.
139  pub fn shown(mut self, shown: Signal<bool>) -> ScreencopyView {
140    self.props.shown = Some(shown);
141    self
142  }
143
144  /// Whether each change to the source shows, rather than only the first
145  /// frame. Off by default.
146  pub fn live(mut self, live: impl IntoProp<bool>) -> ScreencopyView {
147    self.props.live = Some(live.into_prop());
148    self
149  }
150
151  /// Whether the pointer is drawn into the frames. Off by default.
152  pub fn paint_cursors(mut self, paint: impl IntoProp<bool>) -> ScreencopyView {
153    self.props.paint_cursors = Some(paint.into_prop());
154    self
155  }
156
157  /// Sets how the frame fills the view's box when their shapes differ.
158  pub fn fit(mut self, fit: impl IntoProp<Fit>) -> ScreencopyView {
159    self.props.fit = Some(fit.into_prop());
160    self
161  }
162
163  /// Sets the style, whose `width` and `height` give the view its size.
164  pub fn style(mut self, style: impl IntoProp<Style>) -> ScreencopyView {
165    self.common.style = Some(style.into_prop());
166    self
167  }
168
169  visibility_methods!();
170}
171
172impl Widget for ScreencopyView {
173  fn into_element(self: Box<Self>) -> Element {
174    Element {
175      name: "ScreencopyView",
176      common: self.common,
177      kind: ElementKind::Capture(self.props),
178      children: Vec::new(),
179    }
180  }
181}
182
183/// A captured frame, as a view keeps it.
184#[derive(Clone, Debug, PartialEq, Eq)]
185pub struct CaptureFrame {
186  /// The width in pixels.
187  pub width: u32,
188  /// The height in pixels.
189  pub height: u32,
190  /// The source's whole width in logical pixels, which a
191  /// [`crop`](ScreencopyView::crop) is given in. A frame scaled down for
192  /// a small view keeps its source's. An output's is its logical size;
193  /// a window's is its pixels divided by the largest output scale, which
194  /// is wrong for a window on a smaller-scale output when scales are
195  /// mixed.
196  pub logical_width: u32,
197  /// The source's whole height in logical pixels, as for
198  /// [`logical_width`](Self::logical_width).
199  pub logical_height: u32,
200  /// Premultiplied RGBA, row by row: `width * height * 4` bytes. Shared,
201  /// so a renderer can tell a new frame from the one it already scaled.
202  pub rgba: Rc<[u8]>,
203}
204
205impl CaptureFrame {
206  /// The part of the frame a view with `crop` draws, in the frame's
207  /// pixels: left, top, width and height. The crop, in the source's
208  /// logical pixels, is rounded to whole pixels and cut to the frame.
209  /// `None` when the view draws nothing: a crop wholly outside the frame
210  /// or not finite, or pixels that don't fill the frame's size.
211  #[doc(hidden)]
212  pub fn drawn_part(&self, crop: Option<Rect>) -> Option<[u32; 4]> {
213    let pixels = u64::from(self.width) * u64::from(self.height) * 4;
214    if self.width == 0 || self.height == 0 || self.rgba.len() as u64 != pixels {
215      return None;
216    }
217    let Some(crop) = crop else {
218      return Some([0, 0, self.width, self.height]);
219    };
220    let sides = [crop.x, crop.y, crop.width, crop.height];
221    if !sides.iter().all(|side| side.is_finite()) {
222      return None;
223    }
224    let (width, height) = (self.width as f32, self.height as f32);
225    let across = width / self.logical_width.max(1) as f32;
226    let down = height / self.logical_height.max(1) as f32;
227    let left = (crop.x * across).round().max(0.0);
228    let top = (crop.y * down).round().max(0.0);
229    let right = (crop.right() * across).round().min(width);
230    let bottom = (crop.bottom() * down).round().min(height);
231    if right <= left || bottom <= top {
232      return None;
233    }
234    // Within the frame, so `as` keeps every value.
235    let [left, top, right, bottom] = [left, top, right, bottom].map(|side| side as u32);
236    Some([left, top, right - left, bottom - top])
237  }
238}
239
240/// One view the platform captures for, from [`Window::captures`].
241#[derive(Clone, Debug, PartialEq)]
242pub struct CaptureRequest {
243  /// Names the view while it is in a window. Never reused.
244  pub id: u64,
245  /// What it shows.
246  pub source: CaptureSource,
247  /// Whether it shows each new frame.
248  pub live: bool,
249  /// Whether the pointer is drawn into the frames.
250  pub paint_cursors: bool,
251  /// The view's content box at the last layout, in logical pixels, times
252  /// the zoom the renderer draws it at inside transforms that scale it
253  /// up, from [`Affine::layer_zoom`]: a frame needn't be larger. Infinite
254  /// for a view with a crop, which needs the source's whole frame.
255  pub size: Size,
256}
257
258pub(crate) struct CaptureNode {
259  pub(crate) id: u64,
260  /// `None` until the source's binding first runs.
261  pub(crate) source: Option<CaptureSource>,
262  pub(crate) live: bool,
263  pub(crate) paint_cursors: bool,
264  pub(crate) fit: Fit,
265  pub(crate) crop: Option<Rect>,
266  pub(crate) frame: Option<CaptureFrame>,
267  pub(crate) shown: Option<Signal<bool>>,
268  pub(crate) seen: Seen,
269}
270
271/// How far the picture a view shows got to the screen.
272#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
273pub(crate) enum Seen {
274  /// No commit drew it yet, or the view isn't shown.
275  #[default]
276  Unseen,
277  /// The window's last commit drew it.
278  Drawn,
279  /// The compositor presented that commit.
280  Shown,
281}
282
283impl Drop for CaptureNode {
284  fn drop(&mut self) {
285    // At thread exit the list may be gone already; nobody is left to ask.
286    let _ = DROPPED.try_with(|dropped| {
287      let mut dropped = dropped.borrow_mut();
288      if dropped.len() < MAX_DROPPED {
289        dropped.push(self.id);
290      }
291    });
292  }
293}
294
295impl CaptureNode {
296  pub(crate) fn new() -> CaptureNode {
297    CaptureNode {
298      id: next_id(),
299      source: None,
300      live: false,
301      paint_cursors: false,
302      fit: Fit::default(),
303      crop: None,
304      frame: None,
305      shown: None,
306      seen: Seen::Unseen,
307    }
308  }
309
310  /// The view left its window: a `shown` it wrote `true` reads `false`.
311  pub(crate) fn gone(&self) {
312    if let Some(shown) = self.shown {
313      write(shown, false);
314    }
315  }
316
317  /// Shows `frame`, and returns whether that changed what shows. A new
318  /// picture isn't on screen until a commit draws it.
319  fn show(&mut self, frame: Option<CaptureFrame>) -> bool {
320    if self.frame == frame {
321      return false;
322    }
323    self.frame = frame;
324    if self.seen == Seen::Shown
325      && let Some(shown) = self.shown
326    {
327      shown.try_set(false);
328    }
329    self.seen = Seen::Unseen;
330    true
331  }
332}
333
334impl Tree {
335  /// Applies a view's properties. Only the source and fit change what
336  /// shows; the platform reads the rest when it next captures.
337  pub(crate) fn bind_capture(&mut self, id: NodeId, props: ScreencopyProps) {
338    self.captures.push(id);
339    if let Some(shown) = props.shown {
340      write(shown, false);
341      self.update_capture(id, |capture| {
342        capture.shown = Some(shown);
343        Change::None
344      });
345    }
346    if let Some(capture) = props.capture {
347      let frame = (move || capture.frame()).into_prop();
348      self.bind(id, frame, "frame", |tree, id, frame| {
349        tree.update_capture(id, |capture| match capture.show(frame) {
350          true => Change::Paint,
351          false => Change::None,
352        });
353      });
354    }
355    self.bind_opt(id, props.source, "source", |tree, id, value| {
356      tree.update_capture(id, |capture| {
357        if capture.source.as_ref() == Some(&value) {
358          return Change::None;
359        }
360        capture.source = Some(value);
361        // The old source's frame isn't this one's.
362        match capture.show(None) {
363          true => Change::Paint,
364          false => Change::None,
365        }
366      });
367    });
368    self.bind_opt(id, props.crop, "crop", |tree, id, value| {
369      tree.update_capture(id, |capture| match replace(&mut capture.crop, value) {
370        Change::None => Change::None,
371        _ => Change::Paint,
372      });
373    });
374    self.bind_opt(id, props.live, "live", |tree, id, value| {
375      tree.update_capture(id, |capture| {
376        capture.live = value;
377        Change::None
378      });
379    });
380    self.bind_opt(
381      id,
382      props.paint_cursors,
383      "paint_cursors",
384      |tree, id, value| {
385        tree.update_capture(id, |capture| {
386          capture.paint_cursors = value;
387          Change::None
388        });
389      },
390    );
391    self.bind_opt(id, props.fit, "fit", |tree, id, value| {
392      tree.update_capture(id, |capture| match replace(&mut capture.fit, value) {
393        Change::None => Change::None,
394        _ => Change::Paint,
395      });
396    });
397  }
398
399  /// Whether any of what node `id` paints shows inside the window and
400  /// every clipping ancestor, such as a scroll view, at the last layout.
401  /// An ancestor's painted area stands for its clip, so a shadow around
402  /// it counts as inside.
403  fn in_sight(&self, id: NodeId) -> bool {
404    let Some(node) = self.node(id) else {
405      return false;
406    };
407    let mut seen = node.window_painted;
408    let mut at = id;
409    while !seen.is_empty()
410      && let Some(parent) = self.taffy.parent(at)
411    {
412      if let Some(above) = self.node(parent)
413        && (above.clips || parent == self.root)
414      {
415        seen = seen.intersect(above.window_painted);
416      }
417      at = parent;
418    }
419    !seen.is_empty()
420  }
421
422  /// How many times its own resolution node `id` is drawn at, through
423  /// its transform and every one around it, as the renderer draws a
424  /// transformed layer: [`Affine::layer_zoom`] of them all.
425  fn zoom(&self, id: NodeId) -> f32 {
426    let mut linear: Option<Affine> = None;
427    let mut at = Some(id);
428    while let Some(node) = at {
429      if let Some(transform) = self.node(node).and_then(|node| node.transform) {
430        linear = Some(match linear {
431          Some(inner) => transform.after(&inner),
432          None => transform,
433        });
434      }
435      at = self.taffy.parent(node);
436    }
437    linear.map_or(1.0, |linear| linear.layer_zoom())
438  }
439
440  fn update_capture(&mut self, id: NodeId, f: impl FnOnce(&mut CaptureNode) -> Change) {
441    self.update(id, |node| match &mut node.kind {
442      NodeKind::Capture(capture) => f(capture),
443      _ => Change::None,
444    });
445  }
446}
447
448impl Window {
449  /// The views to capture for, in the order they were built: those with
450  /// a source and a box that isn't empty at the last layout. A live view
451  /// wholly outside the window or a clipping ancestor, such as one
452  /// scrolled out of its scroll view's box, is left out until it shows
453  /// again; a one-shot view is kept, so its frame is there when it does.
454  pub fn captures(&self) -> Vec<CaptureRequest> {
455    let tree = self.tree.borrow();
456    tree
457      .captures
458      .iter()
459      .filter_map(|&id| {
460        let node = tree.node(id)?;
461        let NodeKind::Capture(capture) = &node.kind else {
462          return None;
463        };
464        let content = node.content;
465        if node.rect.is_none() || content.is_empty() || capture.live && !tree.in_sight(id) {
466          return None;
467        }
468        let zoom = tree.zoom(id);
469        let size = match capture.crop {
470          Some(_) => Size::new(f32::INFINITY, f32::INFINITY),
471          None => Size::new(content.width * zoom, content.height * zoom),
472        };
473        Some(CaptureRequest {
474          id: capture.id,
475          source: capture.source.clone()?,
476          live: capture.live,
477          paint_cursors: capture.paint_cursors,
478          size,
479        })
480      })
481      .collect()
482  }
483
484  /// Shows `frame` in view `id`, repainting only that view, and returns
485  /// whether it did. A frame the same as the one shown repaints nothing,
486  /// so a live view of its own output settles. A view no longer in the
487  /// window is ignored.
488  pub fn show_capture(&self, id: u64, frame: CaptureFrame) -> bool {
489    let mut tree = borrow(&self.tree);
490    let found = tree.captures.iter().copied().find(|&node| {
491      matches!(tree.node(node).map(|node| &node.kind),
492        Some(NodeKind::Capture(capture)) if capture.id == id)
493    });
494    let Some(node) = found else {
495      return false;
496    };
497    let mut shown = false;
498    tree.update_capture(node, |capture| {
499      shown = capture.show(Some(frame));
500      match shown {
501        true => Change::Paint,
502        false => Change::None,
503      }
504    });
505    shown
506  }
507
508  /// The window committed a frame. Each view in it with a picture no
509  /// commit drew yet counts as drawn, and each hidden, outside the window
510  /// or a clipping ancestor, or without a picture, as off screen.
511  pub fn frame_committed(&self) {
512    self.each_view(|capture, placed| match (placed, capture.seen) {
513      (false, _) => Seen::Unseen,
514      (true, Seen::Unseen) => Seen::Drawn,
515      (true, seen) => seen,
516    });
517  }
518
519  /// The compositor presented the window's last commit, as its frame
520  /// callback says: each view that commit drew shows its picture.
521  pub fn frame_presented(&self) {
522    self.each_view(|capture, _| match capture.seen {
523      Seen::Drawn => Seen::Shown,
524      seen => seen,
525    });
526  }
527
528  /// The window's surface went, as a hidden floating window's does: no
529  /// view in it is on screen.
530  pub fn unmapped(&self) {
531    self.each_view(|_, _| Seen::Unseen);
532  }
533
534  /// Moves each view's picture to the state `next` gives, from whether
535  /// it has one placed in sight, and writes `shown` where that changes.
536  fn each_view(&self, mut next: impl FnMut(&CaptureNode, bool) -> Seen) {
537    let mut writes = Vec::new();
538    let mut tree = borrow(&self.tree);
539    let views = tree.captures.clone();
540    for id in views {
541      let placed = tree
542        .node(id)
543        .is_some_and(|node| node.rect.is_some() && !node.content.is_empty())
544        && tree.in_sight(id);
545      let Some(node) = tree.node_mut(id) else {
546        continue;
547      };
548      let NodeKind::Capture(capture) = &mut node.kind else {
549        continue;
550      };
551      // What the renderer draws of it, which may be nothing.
552      let frame = capture.frame.as_ref();
553      let picture = frame.is_some_and(|frame| frame.drawn_part(capture.crop).is_some());
554      let seen = next(capture, placed && picture);
555      if let Some(shown) = capture.shown
556        && (seen == Seen::Shown) != (capture.seen == Seen::Shown)
557      {
558        writes.push((shown, seen == Seen::Shown));
559      }
560      capture.seen = seen;
561    }
562    drop(tree);
563    for (shown, value) in writes {
564      write(shown, value);
565    }
566  }
567}
568
569/// Writes `value` to `signal` only when it changes, since a signal
570/// notifies on every write.
571fn write(signal: Signal<bool>, value: bool) {
572  if untrack(|| signal.try_get()).is_some_and(|was| was != value) {
573    signal.try_set(value);
574  }
575}