Skip to main content

crabshell_ui/
image.rs

1//! The bindings of [`Image`](crate::Image) and [`Icon`](crate::Icon), an
2//! image's transition to a new source, and what the platform asks of an
3//! image: a repaint of one GIF's box when its next frame is due.
4
5use std::cell::{Cell, RefCell};
6use std::path::{Path, PathBuf};
7use std::rc::Rc;
8use std::sync::atomic::{AtomicU64, Ordering};
9
10use crabshell_reactive::{Signal, untrack};
11
12use crate::animation::{self, Transition};
13use crate::tree::{Change, ImageNode, NodeId, NodeKind, Tree, borrow, replace};
14use crate::widgets::{Fit, IconProps, ImageFilters, ImageProps};
15use crate::window::Window;
16
17/// Numbers every image mounted, in every window, so the renderer's
18/// playback of one GIF and the platform's repaint of it can't mix two up.
19static NEXT_IMAGE: AtomicU64 = AtomicU64::new(0);
20
21/// The most dropped images kept for the renderer to hear of; a shell
22/// without one stops counting there.
23const MAX_DROPPED: usize = 4096;
24
25thread_local! {
26  /// The ids of images dropped since [`dropped_images`] last ran.
27  static DROPPED: RefCell<Vec<u64>> = const { RefCell::new(Vec::new()) };
28  /// Images whose transition's new source the renderer couldn't load,
29  /// with that source, until the transition's next tick.
30  static FAILED: RefCell<Vec<(u64, PathBuf)>> = const { RefCell::new(Vec::new()) };
31  /// Images whose transition's new source the renderer is decoding, with
32  /// that source, until the picture comes in.
33  static DECODING: RefCell<Vec<(u64, PathBuf)>> = const { RefCell::new(Vec::new()) };
34  /// The images with a `status` signal: their id, the signal and the
35  /// source they show.
36  static WATCHED: RefCell<Vec<(u64, Signal<ImageStatus>, PathBuf)>> =
37    const { RefCell::new(Vec::new()) };
38  /// A report changed a status signal since [`image_status_changed`]
39  /// last ran.
40  static STATUS_CHANGED: Cell<bool> = const { Cell::new(false) };
41  /// A watched image went back to Loading since
42  /// [`image_sources_changed`] last ran.
43  static SOURCES_CHANGED: Cell<bool> = const { Cell::new(false) };
44}
45
46/// Where an [`Image`](crate::Image)'s picture is, as Qt's `Image.status`,
47/// written to the signal [`Image::status`](crate::Image::status) takes.
48#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
49pub enum ImageStatus {
50  /// The source is an empty path, so nothing is shown. The default.
51  #[default]
52  Empty,
53  /// The source is new and its picture hasn't loaded yet: it is read in
54  /// the loop turn that set it, or decoded off the loop's thread.
55  Loading,
56  /// The source's picture loaded, whether it was drawn or not.
57  Ready,
58  /// The source can't be read or decoded, or is past the size limits.
59  Failed,
60}
61
62/// Writes `status` to image `id`'s status signal while it shows
63/// `source`, if that changes it. A renderer calls it as it loads a
64/// picture, with [`ImageStatus::Ready`] when the image's source loaded and
65/// [`ImageStatus::Failed`] when it can't be, whether the image is drawn or
66/// not (see [`WindowView::loading_images`](crate::WindowView::loading_images)). A report
67/// about another source, an empty one, or an image without a `status`
68/// signal changes nothing. The platform then asks
69/// [`image_status_changed`] and runs the reactive flush.
70pub fn image_status(id: u64, source: &Path, status: ImageStatus) {
71  if source.as_os_str().is_empty() {
72    return;
73  }
74  let _ = WATCHED.try_with(|watched| {
75    for (_, signal, _) in watched
76      .borrow()
77      .iter()
78      .filter(|(at, _, shown)| *at == id && shown == source)
79    {
80      if write_status(*signal, status) {
81        STATUS_CHANGED.with(|changed| changed.set(true));
82      }
83    }
84  });
85}
86
87/// Whether a report since the last call changed an image's status
88/// signal, so the platform runs the reactive flush for what reads it.
89pub fn image_status_changed() -> bool {
90  STATUS_CHANGED.with(|changed| changed.replace(false))
91}
92
93/// Whether an image with a `status` signal got a new source since the
94/// last call, so its picture waits to load. The platform then has the
95/// renderer load each window's waiting images, drawn or not, as
96/// `Renderer::load_images` does, since a hidden image may be shown only
97/// once it is Ready.
98pub fn image_sources_changed() -> bool {
99  SOURCES_CHANGED.with(|changed| changed.replace(false))
100}
101
102/// Writes `status` to `signal` if that changes it, and says whether it
103/// did.
104fn write_status(signal: Signal<ImageStatus>, status: ImageStatus) -> bool {
105  untrack(|| signal.try_get()) != Some(status) && signal.try_set(status)
106}
107
108/// Watches image `id`'s status with `signal`, from its source's binding.
109fn watch(id: u64, signal: Signal<ImageStatus>) {
110  WATCHED.with(|watched| watched.borrow_mut().push((id, signal, PathBuf::new())));
111}
112
113/// Image `id` shows `source` now: its status goes back to Loading, or to
114/// Empty for an empty path.
115fn watch_source(id: u64, source: &Path) {
116  WATCHED.with(|watched| {
117    for (_, signal, shown) in watched.borrow_mut().iter_mut().filter(|(at, ..)| *at == id) {
118      source.clone_into(shown);
119      let status = match source.as_os_str().is_empty() {
120        true => ImageStatus::Empty,
121        false => ImageStatus::Loading,
122      };
123      write_status(*signal, status);
124      if status == ImageStatus::Loading {
125        SOURCES_CHANGED.with(|changed| changed.set(true));
126      }
127    }
128  });
129}
130
131/// Whether image `id` has a `status` signal that still says Loading.
132pub(crate) fn awaits_status(id: u64) -> bool {
133  WATCHED
134    .try_with(|watched| {
135      watched.borrow().iter().any(|(at, signal, _)| {
136        *at == id && untrack(|| signal.try_get()) == Some(ImageStatus::Loading)
137      })
138    })
139    .unwrap_or(false)
140}
141
142/// How many images have a status watched, for tests.
143#[cfg(test)]
144pub(crate) fn watched_images() -> usize {
145  WATCHED.with(|watched| watched.borrow().len())
146}
147
148/// The ids of images removed, or in windows dropped, since the last call,
149/// so a renderer can let go of what it kept for them, such as the picture
150/// a transition was leaving.
151pub fn dropped_images() -> Vec<u64> {
152  DROPPED.with(|dropped| std::mem::take(&mut *dropped.borrow_mut()))
153}
154
155/// Tells image `id`'s transition that the renderer can't load its new
156/// `source`, so at its next tick it ends at once, leaving the old picture
157/// shown and its box still. The reverse of [`dropped_images`]: a renderer
158/// calls it while drawing. A report for an image with no transition
159/// running, or one to another source, changes nothing.
160pub fn image_source_failed(id: u64, source: &Path) {
161  FAILED.with(|failed| {
162    let mut failed = failed.borrow_mut();
163    if failed.len() < MAX_DROPPED && !failed.iter().any(|(at, path)| *at == id && path == source) {
164      failed.push((id, source.to_owned()));
165    }
166  });
167}
168
169/// Tells image `id`'s transition that the renderer is still decoding its
170/// new `source`, so its clock waits at the start, the old picture shown,
171/// until [`Window::repaint_image`] says the picture came in. A renderer
172/// calls it while drawing. A report for another source holds nothing.
173pub fn image_source_decoding(id: u64, source: &Path) {
174  DECODING.with(|decoding| {
175    let mut decoding = decoding.borrow_mut();
176    if decoding.len() < MAX_DROPPED
177      && !decoding
178        .iter()
179        .any(|(at, path)| *at == id && path == source)
180    {
181      decoding.push((id, source.to_owned()));
182    }
183  });
184}
185
186/// Whether the renderer said it is decoding `source` for image `id`.
187fn source_decoding(id: u64, source: Option<&PathBuf>) -> bool {
188  DECODING.with(|decoding| {
189    decoding
190      .borrow()
191      .iter()
192      .any(|(at, path)| *at == id && Some(path) == source)
193  })
194}
195
196/// Forgets what the renderer said it decodes for image `id`.
197fn decoded(id: u64) {
198  let _ = DECODING.try_with(|decoding| decoding.borrow_mut().retain(|(at, _)| *at != id));
199}
200
201/// How many decoding reports are held, for tests.
202#[cfg(test)]
203pub(crate) fn decoding_reports() -> usize {
204  DECODING.with(|decoding| decoding.borrow().len())
205}
206
207/// How many reports wait for a transition's tick, for tests.
208#[cfg(test)]
209pub(crate) fn failed_reports() -> usize {
210  FAILED.with(|failed| failed.borrow().len())
211}
212
213/// Whether the renderer said image `id` can't load `source`, using up
214/// every report about `id`.
215fn source_failed(id: u64, source: Option<&PathBuf>) -> bool {
216  FAILED.with(|failed| {
217    let mut found = false;
218    failed.borrow_mut().retain(|(at, path)| {
219      let mine = *at == id;
220      found |= mine && Some(path) == source;
221      !mine
222    });
223    found
224  })
225}
226
227impl Drop for ImageNode {
228  fn drop(&mut self) {
229    // At thread exit the list may be gone already; nobody is left to ask.
230    let _ = DROPPED.try_with(|dropped| {
231      let mut dropped = dropped.borrow_mut();
232      if dropped.len() < MAX_DROPPED {
233        dropped.push(self.id);
234      }
235    });
236    // A report about it would wait for a tick that never comes.
237    let _ = FAILED.try_with(|failed| failed.borrow_mut().retain(|(id, _)| *id != self.id));
238    decoded(self.id);
239    let _ = WATCHED.try_with(|watched| watched.borrow_mut().retain(|(id, ..)| *id != self.id));
240  }
241}
242
243impl ImageNode {
244  pub(crate) fn new() -> ImageNode {
245    ImageNode {
246      id: NEXT_IMAGE.fetch_add(1, Ordering::Relaxed),
247      source: None,
248      width: crate::Image::DEFAULT_SIZE,
249      height: crate::Image::DEFAULT_SIZE,
250      fit: Fit::default(),
251      filters: ImageFilters::default(),
252      playing: true,
253      transition: ImageTransition::None,
254      leaving: None,
255      transitions: 0,
256    }
257  }
258}
259
260/// How an [`Image`](crate::Image) shows a new source: at once, or coming
261/// in over the old picture over a [`Transition`], which gives its time,
262/// curve and delay. Both pictures are drawn at the image's size, fit and
263/// filters.
264///
265/// ```
266/// use crabshell_ui::{Easing, ImageTransition, Transition};
267///
268/// const WALLPAPER: ImageTransition =
269///     ImageTransition::wipe(Transition::new(800).easing(Easing::InOutCubic), 90.0);
270/// ```
271#[derive(Clone, Copy, Debug, Default, PartialEq)]
272pub enum ImageTransition {
273  /// The new picture replaces the old at once. The default.
274  #[default]
275  None,
276  /// The new picture fades in as the old one fades out.
277  Crossfade(Transition),
278  /// An edge sweeps across the box in the direction of the angle, in
279  /// degrees as CSS's gradient angle: 0 toward the top, 90 toward the
280  /// right. The new picture is behind it. An angle that isn't finite
281  /// counts as 90.
282  Wipe(Transition, f32),
283  /// A circle grows from the middle until it covers the box, the new
284  /// picture inside it.
285  Circle(Transition),
286  /// The old picture breaks into growing blocks and the new one sharpens
287  /// out of them.
288  Pixelate(Transition),
289}
290
291impl ImageTransition {
292  /// No transition: a new source shows at once.
293  pub const fn none() -> ImageTransition {
294    ImageTransition::None
295  }
296
297  /// A crossfade over `transition`.
298  pub const fn crossfade(transition: Transition) -> ImageTransition {
299    ImageTransition::Crossfade(transition)
300  }
301
302  /// A wipe toward `angle` degrees over `transition`.
303  pub const fn wipe(transition: Transition, angle: f32) -> ImageTransition {
304    ImageTransition::Wipe(transition, angle)
305  }
306
307  /// A circle reveal over `transition`.
308  pub const fn circle(transition: Transition) -> ImageTransition {
309    ImageTransition::Circle(transition)
310  }
311
312  /// A pixelation over `transition`.
313  pub const fn pixelate(transition: Transition) -> ImageTransition {
314    ImageTransition::Pixelate(transition)
315  }
316
317  /// Its time and curve, `None` for none.
318  pub const fn transition(self) -> Option<Transition> {
319    match self {
320      ImageTransition::None => None,
321      ImageTransition::Crossfade(transition)
322      | ImageTransition::Wipe(transition, _)
323      | ImageTransition::Circle(transition)
324      | ImageTransition::Pixelate(transition) => Some(transition),
325    }
326  }
327}
328
329/// The picture a running transition leaves.
330pub(crate) struct Leaving {
331  pub(crate) source: PathBuf,
332  /// How far along the transition is, eased.
333  pub(crate) t: f32,
334  /// Which transition of the image it is, so one replaced stops.
335  generation: u64,
336}
337
338/// `value` if it is finite and above 0, 0 if it is finite and not, and
339/// `unset` otherwise. Never -0, so equal filters hash alike.
340fn filter_value(value: f32, unset: f32) -> f32 {
341  if !value.is_finite() {
342    unset
343  } else if value > 0.0 {
344    value
345  } else {
346    0.0
347  }
348}
349
350/// Sets `slot` to `value`: a change repaints, never lays out.
351fn repaint<T: PartialEq>(slot: &mut T, value: T) -> Change {
352  match replace(slot, value) {
353    Change::None => Change::None,
354    _ => Change::Paint,
355  }
356}
357
358impl Tree {
359  pub(crate) fn bind_image(&mut self, id: NodeId, props: ImageProps) {
360    self.images.push(id);
361    if let (Some(signal), Some(NodeKind::Image(image))) =
362      (props.status, self.node(id).map(|node| &node.kind))
363    {
364      watch(image.id, signal);
365    }
366    self.bind(id, props.source, "image", |tree, id, value| {
367      let mut started = None;
368      // A new picture of the same size only needs a repaint.
369      tree.update(id, |node| {
370        let drawn = node.rect.is_some();
371        let NodeKind::Image(image) = &mut node.kind else {
372          return Change::None;
373        };
374        if image.source.as_ref() == Some(&value) {
375          return Change::None;
376        }
377        watch_source(image.id, &value);
378        let old = image.source.replace(value);
379        let transition = image
380          .transition
381          .transition()
382          .filter(|transition| !transition.is_instant());
383        // Mid-transition, it leaves the picture most of the box shows.
384        let old = match image.leaving.take() {
385          Some(leaving) if leaving.t < 0.5 => Some(leaving.source),
386          _ => old,
387        };
388        // One not drawn yet has nothing to leave, and one going back to
389        // what it shows needs no transition.
390        let old = old.filter(|old| image.source.as_ref() != Some(old));
391        if let (Some(old), Some(transition), true) = (old, transition, drawn) {
392          image.transitions += 1;
393          image.leaving = Some(Leaving {
394            source: old,
395            t: 0.0,
396            generation: image.transitions,
397          });
398          started = Some((image.transitions, transition));
399        }
400        Change::Paint
401      });
402      if let Some((generation, transition)) = started {
403        tree.start_image_transition(id, generation, transition);
404      }
405    });
406    self.bind_opt(id, props.width, "width", |tree, id, value| {
407      tree.update_image(id, |image| replace(&mut image.width, value));
408    });
409    self.bind_opt(id, props.height, "height", |tree, id, value| {
410      tree.update_image(id, |image| replace(&mut image.height, value));
411    });
412    self.bind_opt(id, props.fit, "fit", |tree, id, value| {
413      tree.update_image(id, |image| repaint(&mut image.fit, value));
414    });
415    self.bind_opt(id, props.tint, "tint", |tree, id, value| {
416      tree.update_image(id, |image| repaint(&mut image.filters.tint, value));
417    });
418    self.bind_opt(id, props.brightness, "brightness", |tree, id, value| {
419      let value = filter_value(value, 1.0);
420      tree.update_image(id, |image| repaint(&mut image.filters.brightness, value));
421    });
422    self.bind_opt(id, props.contrast, "contrast", |tree, id, value| {
423      let value = filter_value(value, 1.0);
424      tree.update_image(id, |image| repaint(&mut image.filters.contrast, value));
425    });
426    self.bind_opt(id, props.saturation, "saturation", |tree, id, value| {
427      let value = filter_value(value, 1.0);
428      tree.update_image(id, |image| repaint(&mut image.filters.saturation, value));
429    });
430    self.bind_opt(id, props.blur, "blur", |tree, id, value| {
431      let value = filter_value(value, 0.0);
432      tree.update_image(id, |image| repaint(&mut image.filters.blur, value));
433    });
434    self.bind_opt(id, props.playing, "playing", |tree, id, value| {
435      tree.update_image(id, |image| repaint(&mut image.playing, value));
436    });
437    self.bind_opt(id, props.transition, "transition", |tree, id, value| {
438      tree.update_image(id, |image| repaint(&mut image.transition, value));
439    });
440  }
441
442  /// Moves image `id`'s transition number `generation` with the animation
443  /// clock, repainting its box each tick, until it ends, when the old
444  /// picture is let go, or another replaces it.
445  fn start_image_transition(&self, id: NodeId, generation: u64, transition: Transition) {
446    let tree = self.this.clone();
447    let mut started = animation::start_time();
448    let label = self.node(id).map_or_else(
449      || Rc::from("an image transition"),
450      |node| format!("{}.transition", node.path).into(),
451    );
452    let busy = self.node(id).and_then(|node| node.cx.busy());
453    animation::start(
454      label,
455      busy,
456      Box::new(move |now| {
457        let Some(tree) = tree.upgrade() else {
458          return false;
459        };
460        let Ok(mut tree) = tree.try_borrow_mut() else {
461          return true;
462        };
463        // While its new picture is decoded, the clock waits at the start.
464        let held = tree.node(id).is_some_and(|node| {
465          matches!(&node.kind, NodeKind::Image(image)
466            if image.leaving.as_ref().is_some_and(|leaving| leaving.generation == generation)
467              && source_decoding(image.id, image.source.as_ref()))
468        });
469        if held {
470          started = None;
471          return true;
472        }
473        let begun = *started.get_or_insert(now);
474        let waiting = transition.waiting(begun, now);
475        let (t, mut ended) = transition.progress(begun, now);
476        let mut mine = false;
477        tree.update_image(id, |image| {
478          let failed = source_failed(image.id, image.source.as_ref());
479          let Some(leaving) = image
480            .leaving
481            .as_mut()
482            .filter(|leaving| leaving.generation == generation)
483          else {
484            return Change::None;
485          };
486          mine = true;
487          ended |= failed;
488          if ended {
489            image.leaving = None;
490          } else if waiting {
491            // Nothing on screen changes until the delay is over.
492            return Change::None;
493          } else {
494            leaving.t = t;
495          }
496          Change::Paint
497        });
498        mine && !ended
499      }),
500    );
501  }
502
503  pub(crate) fn bind_icon(&mut self, id: NodeId, props: IconProps) {
504    self.bind(id, props.source, "icon", |tree, id, value| {
505      // A new picture of the same size only needs a repaint.
506      tree.update_icon(id, |icon| repaint(&mut icon.source, Some(value)));
507    });
508    self.bind_opt(id, props.fallback, "fallback", |tree, id, value| {
509      tree.update_icon(id, |icon| repaint(&mut icon.fallback, Some(value)));
510    });
511    self.bind_opt(id, props.size, "size", |tree, id, value| {
512      tree.update_icon(id, |icon| replace(&mut icon.size, value));
513    });
514    self.bind_opt(id, props.tint, "tint", |tree, id, value| {
515      tree.update_icon(id, |icon| repaint(&mut icon.tint, value));
516    });
517  }
518}
519
520impl Window {
521  /// Repaints the box of image `id`, as when the renderer says a GIF's
522  /// next frame is due or a picture it decoded came in, which also ends
523  /// its transition's wait for it, and returns whether it did. An image in another
524  /// window, removed, hidden or not laid out yet repaints nothing.
525  pub fn repaint_image(&self, id: u64) -> bool {
526    let mut tree = borrow(&self.tree);
527    let found = tree.images.iter().copied().find(|&node| {
528      matches!(tree.node(node), Some(node) if node.rect.is_some()
529        && matches!(&node.kind, NodeKind::Image(image) if image.id == id))
530    });
531    // A picture that came in ends any wait for it.
532    decoded(id);
533    let Some(node) = found else {
534      return false;
535    };
536    tree.invalidate(node, Change::Paint);
537    true
538  }
539}