Skip to main content

gpui/elements/
img.rs

1use crate::{
2    AnyElement, AnyImageCache, App, Asset, AssetLogger, Bounds, DefiniteLength, Element, ElementId,
3    Entity, GlobalElementId, Hitbox, Image, ImageCache, InspectorElementId, InteractiveElement,
4    Interactivity, LayoutId, Length, ObjectFit, Pixels, RenderImage, Resource, SharedString,
5    SharedUri, StyleRefinement, Styled, Task, Window, decode_gif_image, decode_static_image,
6    decode_webp_image, px,
7};
8use anyhow::Result;
9
10use futures::Future;
11use gpui_util::ResultExt;
12use image::{ImageError, ImageFormat};
13use scheduler::Instant;
14use std::{
15    fs,
16    io::{self},
17    ops::{Deref, DerefMut},
18    path::{Path, PathBuf},
19    str::FromStr,
20    sync::Arc,
21    time::Duration,
22};
23use thiserror::Error;
24
25use super::{Stateful, StatefulInteractiveElement};
26
27/// The delay before showing the loading state.
28pub const LOADING_DELAY: Duration = Duration::from_millis(200);
29
30/// A type alias to the resource loader that the `img()` element uses.
31///
32/// Note: that this is only for Resources, like URLs or file paths.
33/// Custom loaders, or external images will not use this asset loader
34pub type ImgResourceLoader = AssetLogger<ImageAssetLoader>;
35
36/// A source of image content.
37#[derive(Clone)]
38pub enum ImageSource {
39    /// The image content will be loaded from some resource location
40    Resource(Resource),
41    /// Cached image data
42    Render(Arc<RenderImage>),
43    /// Cached image data
44    Image(Arc<Image>),
45    /// A custom loading function to use
46    Custom(Arc<dyn Fn(&mut Window, &mut App) -> Option<Result<Arc<RenderImage>, ImageCacheError>>>),
47}
48
49fn is_uri(uri: &str) -> bool {
50    url::Url::from_str(uri).is_ok()
51}
52
53impl From<SharedUri> for ImageSource {
54    fn from(value: SharedUri) -> Self {
55        Self::Resource(Resource::Uri(value))
56    }
57}
58
59impl<'a> From<&'a str> for ImageSource {
60    fn from(s: &'a str) -> Self {
61        if is_uri(s) {
62            Self::Resource(Resource::Uri(s.to_string().into()))
63        } else {
64            Self::Resource(Resource::Embedded(s.to_string().into()))
65        }
66    }
67}
68
69impl From<String> for ImageSource {
70    fn from(s: String) -> Self {
71        if is_uri(&s) {
72            Self::Resource(Resource::Uri(s.into()))
73        } else {
74            Self::Resource(Resource::Embedded(s.into()))
75        }
76    }
77}
78
79impl From<SharedString> for ImageSource {
80    fn from(s: SharedString) -> Self {
81        s.as_ref().into()
82    }
83}
84
85impl From<&Path> for ImageSource {
86    fn from(value: &Path) -> Self {
87        Self::Resource(value.to_path_buf().into())
88    }
89}
90
91impl From<Arc<Path>> for ImageSource {
92    fn from(value: Arc<Path>) -> Self {
93        Self::Resource(value.into())
94    }
95}
96
97impl From<PathBuf> for ImageSource {
98    fn from(value: PathBuf) -> Self {
99        Self::Resource(value.into())
100    }
101}
102
103impl From<Arc<RenderImage>> for ImageSource {
104    fn from(value: Arc<RenderImage>) -> Self {
105        Self::Render(value)
106    }
107}
108
109impl From<Arc<Image>> for ImageSource {
110    fn from(value: Arc<Image>) -> Self {
111        Self::Image(value)
112    }
113}
114
115impl<F> From<F> for ImageSource
116where
117    F: Fn(&mut Window, &mut App) -> Option<Result<Arc<RenderImage>, ImageCacheError>> + 'static,
118{
119    fn from(value: F) -> Self {
120        Self::Custom(Arc::new(value))
121    }
122}
123
124/// The style of an image element.
125pub struct ImageStyle {
126    grayscale: bool,
127    object_fit: ObjectFit,
128    loading: Option<Box<dyn Fn() -> AnyElement>>,
129    fallback: Option<Box<dyn Fn() -> AnyElement>>,
130}
131
132impl Default for ImageStyle {
133    fn default() -> Self {
134        Self {
135            grayscale: false,
136            object_fit: ObjectFit::Contain,
137            loading: None,
138            fallback: None,
139        }
140    }
141}
142
143/// Style an image element.
144pub trait StyledImage: Sized {
145    /// Get a mutable [ImageStyle] from the element.
146    fn image_style(&mut self) -> &mut ImageStyle;
147
148    /// Set the image to be displayed in grayscale.
149    fn grayscale(mut self, grayscale: bool) -> Self {
150        self.image_style().grayscale = grayscale;
151        self
152    }
153
154    /// Set the object fit for the image.
155    fn object_fit(mut self, object_fit: ObjectFit) -> Self {
156        self.image_style().object_fit = object_fit;
157        self
158    }
159
160    /// Set a fallback function that will be invoked to render an error view should
161    /// the image fail to load.
162    fn with_fallback(mut self, fallback: impl Fn() -> AnyElement + 'static) -> Self {
163        self.image_style().fallback = Some(Box::new(fallback));
164        self
165    }
166
167    /// Set a fallback function that will be invoked to render a view while the image
168    /// is still being loaded.
169    fn with_loading(mut self, loading: impl Fn() -> AnyElement + 'static) -> Self {
170        self.image_style().loading = Some(Box::new(loading));
171        self
172    }
173}
174
175impl StyledImage for Img {
176    fn image_style(&mut self) -> &mut ImageStyle {
177        &mut self.style
178    }
179}
180
181impl StyledImage for Stateful<Img> {
182    fn image_style(&mut self) -> &mut ImageStyle {
183        &mut self.element.style
184    }
185}
186
187/// An image element.
188pub struct Img {
189    interactivity: Interactivity,
190    source: ImageSource,
191    style: ImageStyle,
192    image_cache: Option<AnyImageCache>,
193}
194
195/// Create a new image element.
196#[track_caller]
197pub fn img(source: impl Into<ImageSource>) -> Img {
198    Img {
199        interactivity: Interactivity::new(),
200        source: source.into(),
201        style: ImageStyle::default(),
202        image_cache: None,
203    }
204}
205
206impl Img {
207    /// A list of all format extensions currently supported by this img element
208    pub fn extensions() -> &'static [&'static str] {
209        // This is the list in [image::ImageFormat::from_extension] + `svg`
210        &[
211            "avif", "jpg", "jpeg", "png", "gif", "webp", "tif", "tiff", "tga", "dds", "bmp", "ico",
212            "hdr", "exr", "pbm", "pam", "ppm", "pgm", "ff", "farbfeld", "qoi", "svg",
213        ]
214    }
215
216    /// Sets the image cache for the current node.
217    ///
218    /// If the `image_cache` is not explicitly provided, the function will determine the image cache by:
219    ///
220    /// 1. Checking if any ancestor node of the current node contains an `ImageCacheElement`, If such a node exists, the image cache specified by that ancestor will be used.
221    /// 2. If no ancestor node contains an `ImageCacheElement`, the global image cache will be used as a fallback.
222    ///
223    /// This mechanism provides a flexible way to manage image caching, allowing precise control when needed,
224    /// while ensuring a default behavior when no cache is explicitly specified.
225    #[inline]
226    pub fn image_cache<I: ImageCache>(self, image_cache: &Entity<I>) -> Self {
227        Self {
228            image_cache: Some(image_cache.clone().into()),
229            ..self
230        }
231    }
232}
233
234impl Deref for Stateful<Img> {
235    type Target = Img;
236
237    fn deref(&self) -> &Self::Target {
238        &self.element
239    }
240}
241
242impl DerefMut for Stateful<Img> {
243    fn deref_mut(&mut self) -> &mut Self::Target {
244        &mut self.element
245    }
246}
247
248/// The image state between frames
249struct ImgState {
250    frame_index: usize,
251    last_frame_time: Option<Instant>,
252    started_loading: Option<(Instant, Task<()>)>,
253}
254
255/// The image layout state between frames
256pub struct ImgLayoutState {
257    frame_index: usize,
258    replacement: Option<AnyElement>,
259}
260
261impl Element for Img {
262    type RequestLayoutState = ImgLayoutState;
263    type PrepaintState = Option<Hitbox>;
264
265    fn id(&self) -> Option<ElementId> {
266        self.interactivity.element_id.clone()
267    }
268
269    fn source_location(&self) -> Option<&'static core::panic::Location<'static>> {
270        self.interactivity.source_location()
271    }
272
273    fn request_layout(
274        &mut self,
275        global_id: Option<&GlobalElementId>,
276        inspector_id: Option<&InspectorElementId>,
277        window: &mut Window,
278        cx: &mut App,
279    ) -> (LayoutId, Self::RequestLayoutState) {
280        let mut layout_state = ImgLayoutState {
281            frame_index: 0,
282            replacement: None,
283        };
284
285        window.with_optional_element_state(global_id, |state, window| {
286            let mut state = state.map(|state| {
287                state.unwrap_or(ImgState {
288                    frame_index: 0,
289                    last_frame_time: None,
290                    started_loading: None,
291                })
292            });
293
294            let mut frame_index = state.as_ref().map(|state| state.frame_index).unwrap_or(0);
295
296            let layout_id = self.interactivity.request_layout(
297                global_id,
298                inspector_id,
299                window,
300                cx,
301                |mut style, window, cx| {
302                    let mut replacement_id = None;
303
304                    match self.source.use_data(
305                        self.image_cache
306                            .clone()
307                            .or_else(|| window.image_cache_stack.last().cloned()),
308                        window,
309                        cx,
310                    ) {
311                        Some(Ok(data)) => {
312                            let frame_count = data.frame_count();
313                            let max_frame_index = frame_count.saturating_sub(1);
314
315                            if let Some(state) = &mut state {
316                                state.frame_index = state.frame_index.min(max_frame_index);
317                                if frame_count > 1 && !cx.reduce_motion() {
318                                    if window.is_window_active() {
319                                        let current_time = Instant::now();
320                                        if let Some(last_frame_time) = state.last_frame_time {
321                                            let elapsed = current_time - last_frame_time;
322                                            let frame_duration =
323                                                Duration::from(data.delay(state.frame_index));
324
325                                            if elapsed >= frame_duration {
326                                                state.frame_index =
327                                                    (state.frame_index + 1) % frame_count;
328                                                state.last_frame_time =
329                                                    Some(current_time - (elapsed - frame_duration));
330                                            }
331                                        } else {
332                                            state.last_frame_time = Some(current_time);
333                                        }
334                                    } else {
335                                        state.last_frame_time = None;
336                                    }
337                                } else {
338                                    state.last_frame_time = None;
339                                }
340                                state.started_loading = None;
341                                frame_index = state.frame_index;
342                            }
343
344                            let image_size = data.render_size(frame_index);
345
346                            if style.aspect_ratio.is_none() {
347                                style.aspect_ratio = Some(image_size.width / image_size.height);
348                            }
349
350                            if let Length::Auto = style.size.width {
351                                style.size.width = match style.size.height {
352                                    Length::Definite(DefiniteLength::Absolute(abs_length)) => {
353                                        let height_px = abs_length.to_pixels(window.rem_size());
354                                        Length::Definite(
355                                            px(image_size.width.0 * height_px.0
356                                                / image_size.height.0)
357                                            .into(),
358                                        )
359                                    }
360                                    _ => Length::Definite(image_size.width.into()),
361                                };
362                            }
363
364                            if let Length::Auto = style.size.height {
365                                style.size.height = match style.size.width {
366                                    Length::Definite(DefiniteLength::Absolute(abs_length)) => {
367                                        let width_px = abs_length.to_pixels(window.rem_size());
368                                        Length::Definite(
369                                            px(image_size.height.0 * width_px.0
370                                                / image_size.width.0)
371                                            .into(),
372                                        )
373                                    }
374                                    _ => Length::Definite(image_size.height.into()),
375                                };
376                            }
377
378                            if global_id.is_some()
379                                && data.frame_count() > 1
380                                && window.is_window_active()
381                                && !cx.reduce_motion()
382                            {
383                                window.request_animation_frame();
384                            }
385                        }
386                        Some(_err) => {
387                            if let Some(fallback) = self.style.fallback.as_ref() {
388                                let mut element = fallback();
389                                replacement_id = Some(element.request_layout(window, cx));
390                                layout_state.replacement = Some(element);
391                            }
392                            if let Some(state) = &mut state {
393                                state.started_loading = None;
394                            }
395                        }
396                        None => {
397                            if let Some(state) = &mut state {
398                                if let Some((started_loading, _)) = state.started_loading {
399                                    if started_loading.elapsed() > LOADING_DELAY
400                                        && let Some(loading) = self.style.loading.as_ref()
401                                    {
402                                        let mut element = loading();
403                                        replacement_id = Some(element.request_layout(window, cx));
404                                        layout_state.replacement = Some(element);
405                                    }
406                                } else {
407                                    let current_view = window.current_view();
408                                    let task = window.spawn(cx, async move |cx| {
409                                        cx.background_executor().timer(LOADING_DELAY).await;
410                                        cx.update(move |_, cx| {
411                                            cx.notify(current_view);
412                                        })
413                                        .ok();
414                                    });
415                                    state.started_loading = Some((Instant::now(), task));
416                                }
417                            }
418                        }
419                    }
420
421                    window.request_layout(style, replacement_id, cx)
422                },
423            );
424
425            layout_state.frame_index = frame_index;
426
427            ((layout_id, layout_state), state)
428        })
429    }
430
431    fn prepaint(
432        &mut self,
433        global_id: Option<&GlobalElementId>,
434        inspector_id: Option<&InspectorElementId>,
435        bounds: Bounds<Pixels>,
436        request_layout: &mut Self::RequestLayoutState,
437        window: &mut Window,
438        cx: &mut App,
439    ) -> Self::PrepaintState {
440        self.interactivity.prepaint(
441            global_id,
442            inspector_id,
443            bounds,
444            bounds.size,
445            window,
446            cx,
447            |_, _, hitbox, window, cx| {
448                if let Some(replacement) = &mut request_layout.replacement {
449                    replacement.prepaint(window, cx);
450                }
451
452                hitbox
453            },
454        )
455    }
456
457    fn paint(
458        &mut self,
459        global_id: Option<&GlobalElementId>,
460        inspector_id: Option<&InspectorElementId>,
461        bounds: Bounds<Pixels>,
462        layout_state: &mut Self::RequestLayoutState,
463        hitbox: &mut Self::PrepaintState,
464        window: &mut Window,
465        cx: &mut App,
466    ) {
467        let source = self.source.clone();
468        self.interactivity.paint(
469            global_id,
470            inspector_id,
471            bounds,
472            hitbox.as_ref(),
473            window,
474            cx,
475            |style, window, cx| {
476                if let Some(Ok(data)) = source.use_data(
477                    self.image_cache
478                        .clone()
479                        .or_else(|| window.image_cache_stack.last().cloned()),
480                    window,
481                    cx,
482                ) {
483                    if data.frame_count() == 0 {
484                        return;
485                    }
486                    // vue-native fork: the picture's size, not its pixels' (an
487                    // embedder may have swapped in a smaller copy).
488                    let natural = data.natural_size(layout_state.frame_index);
489                    let new_bounds = match style.vn_object_position {
490                        Some(position) => {
491                            self.style.object_fit.get_bounds_at(bounds, natural, position)
492                        }
493                        None => self.style.object_fit.get_bounds(bounds, natural),
494                    };
495                    // vue-native fork: percentages and the overlap rule resolve
496                    // against the box (`Style::corner_radii_for`).
497                    let corner_radii = style.corner_radii_for(bounds.size, window.rem_size());
498                    window
499                        .paint_image(
500                            bounds,
501                            new_bounds,
502                            corner_radii,
503                            data,
504                            layout_state.frame_index,
505                            self.style.grayscale,
506                        )
507                        .log_err();
508                } else if let Some(replacement) = &mut layout_state.replacement {
509                    replacement.paint(window, cx);
510                }
511            },
512        )
513    }
514}
515
516impl Styled for Img {
517    fn style(&mut self) -> &mut StyleRefinement {
518        &mut self.interactivity.base_style
519    }
520}
521
522impl InteractiveElement for Img {
523    fn interactivity(&mut self) -> &mut Interactivity {
524        &mut self.interactivity
525    }
526}
527
528impl StatefulInteractiveElement for Img {}
529
530impl ImageSource {
531    pub(crate) fn use_data(
532        &self,
533        cache: Option<AnyImageCache>,
534        window: &mut Window,
535        cx: &mut App,
536    ) -> Option<Result<Arc<RenderImage>, ImageCacheError>> {
537        match self {
538            ImageSource::Resource(resource) => {
539                if let Some(cache) = cache {
540                    cache.load(resource, window, cx)
541                } else {
542                    window.use_asset::<ImgResourceLoader>(resource, cx)
543                }
544            }
545            ImageSource::Custom(loading_fn) => loading_fn(window, cx),
546            ImageSource::Render(data) => Some(Ok(data.to_owned())),
547            ImageSource::Image(data) => window.use_asset::<AssetLogger<ImageDecoder>>(data, cx),
548        }
549    }
550
551    pub(crate) fn get_data(
552        &self,
553        cache: Option<AnyImageCache>,
554        window: &mut Window,
555        cx: &mut App,
556    ) -> Option<Result<Arc<RenderImage>, ImageCacheError>> {
557        match self {
558            ImageSource::Resource(resource) => {
559                if let Some(cache) = cache {
560                    cache.load(resource, window, cx)
561                } else {
562                    window.get_asset::<ImgResourceLoader>(resource, cx)
563                }
564            }
565            ImageSource::Custom(loading_fn) => loading_fn(window, cx),
566            ImageSource::Render(data) => Some(Ok(data.to_owned())),
567            ImageSource::Image(data) => window.get_asset::<AssetLogger<ImageDecoder>>(data, cx),
568        }
569    }
570
571    /// Remove this image source from the asset system
572    pub fn remove_asset(&self, cx: &mut App) {
573        match self {
574            ImageSource::Resource(resource) => {
575                cx.remove_asset::<ImgResourceLoader>(resource);
576            }
577            ImageSource::Custom(_) | ImageSource::Render(_) => {}
578            ImageSource::Image(data) => cx.remove_asset::<AssetLogger<ImageDecoder>>(data),
579        }
580    }
581
582    /// vue-native fork: the decode the asset system holds for this source, if
583    /// its load has finished. Never starts a load.
584    pub fn cached(&self, cx: &App) -> Option<Arc<RenderImage>> {
585        match self {
586            ImageSource::Resource(resource) => cx.peek_asset::<ImgResourceLoader>(resource)?.ok(),
587            ImageSource::Image(data) => cx.peek_asset::<AssetLogger<ImageDecoder>>(data)?.ok(),
588            ImageSource::Custom(_) | ImageSource::Render(_) => None,
589        }
590    }
591
592    /// vue-native fork: makes `image` what the asset system answers for this
593    /// source from now on — a smaller copy of the decode
594    /// ([`RenderImage::with_natural_size`]), or the full decode back. `false`
595    /// when the source is still loading, or is not one the asset system caches.
596    pub fn replace_cached(&self, image: Arc<RenderImage>, cx: &mut App) -> bool {
597        match self {
598            ImageSource::Resource(resource) => {
599                cx.replace_asset::<ImgResourceLoader>(resource, Ok(image))
600            }
601            ImageSource::Image(data) => {
602                cx.replace_asset::<AssetLogger<ImageDecoder>>(data, Ok(image))
603            }
604            ImageSource::Custom(_) | ImageSource::Render(_) => false,
605        }
606    }
607
608    /// vue-native fork: loads and decodes this source afresh on the background
609    /// executor, leaving the asset system's entry as it is (an embedder that
610    /// swapped in a smaller copy gets the full decode back this way without
611    /// the element going blank meanwhile). `None` for a source the asset
612    /// system does not load.
613    pub fn load_detached(
614        &self,
615        cx: &mut App,
616    ) -> Option<Task<Result<Arc<RenderImage>, ImageCacheError>>> {
617        match self {
618            ImageSource::Resource(resource) => {
619                let load = <ImgResourceLoader as Asset>::load(resource.clone(), cx);
620                Some(cx.background_executor().spawn(load))
621            }
622            ImageSource::Image(data) => {
623                let load = <AssetLogger<ImageDecoder> as Asset>::load(data.clone(), cx);
624                Some(cx.background_executor().spawn(load))
625            }
626            ImageSource::Custom(_) | ImageSource::Render(_) => None,
627        }
628    }
629
630    /// Check whether this image source is present in the asset system (loading
631    /// or loaded), without fetching it.
632    #[cfg(any(test, feature = "test-support"))]
633    pub fn is_asset_cached(&self, cx: &App) -> bool {
634        match self {
635            ImageSource::Resource(resource) => cx.has_asset::<ImgResourceLoader>(resource),
636            ImageSource::Custom(_) | ImageSource::Render(_) => false,
637            ImageSource::Image(data) => cx.has_asset::<AssetLogger<ImageDecoder>>(data),
638        }
639    }
640}
641
642#[derive(Clone)]
643enum ImageDecoder {}
644
645impl Asset for ImageDecoder {
646    type Source = Arc<Image>;
647    type Output = Result<Arc<RenderImage>, ImageCacheError>;
648
649    fn load(
650        source: Self::Source,
651        cx: &mut App,
652    ) -> impl Future<Output = Self::Output> + Send + 'static {
653        let renderer = cx.svg_renderer();
654        async move { source.to_image_data(renderer).map_err(Into::into) }
655    }
656}
657
658/// An image loader for the GPUI asset system
659#[derive(Clone)]
660pub enum ImageAssetLoader {}
661
662impl Asset for ImageAssetLoader {
663    type Source = Resource;
664    type Output = Result<Arc<RenderImage>, ImageCacheError>;
665
666    fn load(
667        source: Self::Source,
668        cx: &mut App,
669    ) -> impl Future<Output = Self::Output> + Send + 'static {
670        let client = cx.http_client();
671        // TODO: Can we make SVGs always rescale?
672        // let scale_factor = cx.scale_factor();
673        let svg_renderer = cx.svg_renderer();
674        let asset_source = cx.asset_source().clone();
675        async move {
676            let bytes = match source.clone() {
677                Resource::Path(uri) => fs::read(uri.as_ref())?,
678                Resource::Uri(uri) => {
679                    use anyhow::Context as _;
680                    use futures::AsyncReadExt as _;
681
682                    let mut response = client
683                        .get(uri.as_ref(), ().into(), true)
684                        .await
685                        .with_context(|| format!("loading image asset from {uri:?}"))?;
686                    let mut body = Vec::new();
687                    response.body_mut().read_to_end(&mut body).await?;
688                    if !response.status().is_success() {
689                        let mut body = String::from_utf8_lossy(&body).into_owned();
690                        let first_line = body.lines().next().unwrap_or("").trim_end();
691                        body.truncate(first_line.len());
692                        return Err(ImageCacheError::BadStatus {
693                            uri,
694                            status: response.status(),
695                            body,
696                        });
697                    }
698                    body
699                }
700                Resource::Embedded(path) => {
701                    let data = asset_source.load(&path).ok().flatten();
702                    if let Some(data) = data {
703                        data.to_vec()
704                    } else {
705                        return Err(ImageCacheError::Asset(
706                            format!("Embedded resource not found: {}", path).into(),
707                        ));
708                    }
709                }
710            };
711
712            if let Ok(format) = image::guess_format(&bytes) {
713                let data = match format {
714                    ImageFormat::Gif => decode_gif_image(&bytes)?,
715                    ImageFormat::WebP => decode_webp_image(&bytes)?,
716                    _ => decode_static_image(&bytes, format)?,
717                };
718
719                Ok(Arc::new(RenderImage::new(data)))
720            } else {
721                svg_renderer
722                    .render_single_frame(&bytes, 1.0)
723                    .map_err(Into::into)
724            }
725        }
726    }
727}
728
729/// An error that can occur when interacting with the image cache.
730#[derive(Debug, Error, Clone)]
731pub enum ImageCacheError {
732    /// Some other kind of error occurred
733    #[error("error: {0}")]
734    Other(#[from] Arc<anyhow::Error>),
735    /// An error that occurred while reading the image from disk.
736    #[error("IO error: {0}")]
737    Io(Arc<std::io::Error>),
738    /// An error that occurred while processing an image.
739    #[error("unexpected http status for {uri}: {status}, body: {body}")]
740    BadStatus {
741        /// The URI of the image.
742        uri: SharedUri,
743        /// The HTTP status code.
744        status: http_client::StatusCode,
745        /// The HTTP response body.
746        body: String,
747    },
748    /// An error that occurred while processing an asset.
749    #[error("asset error: {0}")]
750    Asset(SharedString),
751    /// An error that occurred while processing an image.
752    #[error("image error: {0}")]
753    Image(Arc<ImageError>),
754    /// An error that occurred while processing an SVG.
755    #[error("svg error: {0}")]
756    Usvg(Arc<usvg::Error>),
757}
758
759impl From<anyhow::Error> for ImageCacheError {
760    fn from(value: anyhow::Error) -> Self {
761        Self::Other(Arc::new(value))
762    }
763}
764
765impl From<io::Error> for ImageCacheError {
766    fn from(value: io::Error) -> Self {
767        Self::Io(Arc::new(value))
768    }
769}
770
771impl From<usvg::Error> for ImageCacheError {
772    fn from(value: usvg::Error) -> Self {
773        Self::Usvg(Arc::new(value))
774    }
775}
776
777impl From<image::ImageError> for ImageCacheError {
778    fn from(value: image::ImageError) -> Self {
779        Self::Image(Arc::new(value))
780    }
781}
782
783#[cfg(test)]
784mod tests {
785    use super::*;
786    use crate::{IntoElement, ParentElement as _, TestAppContext, canvas, div, point, px, size};
787    use image::{Frame, ImageBuffer, Rgba};
788    use smallvec::SmallVec;
789
790    const TEST_IMG_ID: &str = "test-img";
791
792    fn test_image(frame_count: usize) -> Arc<RenderImage> {
793        let frame = Frame::new(ImageBuffer::from_pixel(1, 1, Rgba([0, 0, 0, 0])));
794        Arc::new(RenderImage::new(SmallVec::from_iter(
795            (0..frame_count).map(|_| frame.clone()),
796        )))
797    }
798
799    fn test_image_with_size(width: u32, height: u32) -> Arc<RenderImage> {
800        let frame = Frame::new(ImageBuffer::from_pixel(width, height, Rgba([0, 0, 0, 0])));
801        Arc::new(RenderImage::new(SmallVec::from_elem(frame, 1)))
802    }
803
804    /// Overwrites the cached `frame_index` of the sibling `img` during paint.
805    fn seed_frame_index(frame_index: usize) -> impl IntoElement {
806        canvas(
807            |_, _, _| (),
808            move |_, _, window, _| {
809                window.with_global_id(TEST_IMG_ID.into(), |id, window| {
810                    window.with_element_state::<ImgState, _>(id, |state, _| {
811                        let mut state = state.expect("img state should be initialized");
812                        state.frame_index = frame_index;
813                        ((), state)
814                    });
815                });
816            },
817        )
818    }
819
820    #[gpui::test]
821    fn zero_frame_image_does_not_panic_on_paint(cx: &mut TestAppContext) {
822        cx.add_empty_window()
823            .draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
824                img(ImageSource::Render(test_image(0))).into_any_element()
825            });
826    }
827
828    #[gpui::test]
829    fn image_object_fit_cover_crops_to_element_bounds(cx: &mut TestAppContext) {
830        let window = cx.add_empty_window();
831        let image = test_image_with_size(200, 100);
832        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
833            img(ImageSource::Render(image.clone()))
834                .size_full()
835                .object_fit(ObjectFit::Fill)
836                .into_any_element()
837        });
838        let full_tile_bounds = window.update(|window, _| {
839            window
840                .rendered_frame
841                .scene
842                .polychrome_sprites
843                .last()
844                .expect("fill image should paint a sprite")
845                .tile
846                .bounds
847        });
848
849        window.draw(point(px(10.), px(20.)), size(px(100.), px(100.)), |_, _| {
850            img(ImageSource::Render(image))
851                .size_full()
852                .object_fit(ObjectFit::Cover)
853                .into_any_element()
854        });
855
856        let (rendered_bounds, rendered_tile_bounds, scale_factor) = window.update(|window, _| {
857            let sprite = window
858                .rendered_frame
859                .scene
860                .polychrome_sprites
861                .last()
862                .expect("cover image should paint a sprite");
863            (sprite.bounds, sprite.tile.bounds, window.scale_factor())
864        });
865        assert_eq!(
866            rendered_bounds,
867            Bounds {
868                origin: point(px(10.).scale(scale_factor), px(20.).scale(scale_factor)),
869                size: size(px(100.).scale(scale_factor), px(100.).scale(scale_factor)),
870            }
871        );
872        assert_eq!(
873            (
874                rendered_tile_bounds.origin.x.0 - full_tile_bounds.origin.x.0,
875                rendered_tile_bounds.origin.y.0 - full_tile_bounds.origin.y.0,
876                rendered_tile_bounds.size.width.0,
877                rendered_tile_bounds.size.height.0,
878            ),
879            (50, 0, 100, 100),
880        );
881    }
882
883    #[gpui::test]
884    fn explicit_aspect_ratio_is_not_overridden_by_intrinsic_ratio(cx: &mut TestAppContext) {
885        let window = cx.add_empty_window();
886
887        // A portrait image in a square container
888        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
889            div()
890                .size(px(100.))
891                .overflow_hidden()
892                .child(
893                    img(ImageSource::Render(test_image_with_size(100, 200)))
894                        .size_full()
895                        .aspect_square()
896                        .object_fit(ObjectFit::Contain),
897                )
898                .into_any_element()
899        });
900
901        let (rendered_bounds, scale_factor) = window.update(|window, _| {
902            let sprite = window
903                .rendered_frame
904                .scene
905                .polychrome_sprites
906                .last()
907                .expect("contained image should paint a sprite");
908            (sprite.bounds, window.scale_factor())
909        });
910
911        // The element stays 100x100, so the image is letterboxed horizontally
912        assert_eq!(
913            rendered_bounds,
914            Bounds {
915                origin: point(px(25.).scale(scale_factor), px(0.).scale(scale_factor)),
916                size: size(px(50.).scale(scale_factor), px(100.).scale(scale_factor)),
917            }
918        );
919    }
920
921    #[gpui::test]
922    fn image_object_fit_cover_clamps_corner_radii_to_visible_bounds(cx: &mut TestAppContext) {
923        let window = cx.add_empty_window();
924        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
925            img(ImageSource::Render(test_image_with_size(200, 100)))
926                .size_full()
927                .rounded(px(100.))
928                .object_fit(ObjectFit::Cover)
929                .into_any_element()
930        });
931
932        let (corner_radius, expected_corner_radius) = window.update(|window, _| {
933            (
934                window
935                    .rendered_frame
936                    .scene
937                    .polychrome_sprites
938                    .last()
939                    .map(|sprite| sprite.corner_radii.top_left),
940                px(50.).scale(window.scale_factor()),
941            )
942        });
943        assert_eq!(corner_radius, Some(expected_corner_radius));
944    }
945
946    #[gpui::test]
947    fn stale_frame_index_is_clamped_when_image_changes(cx: &mut TestAppContext) {
948        let window = cx.add_empty_window();
949
950        // Assert that a cached frame_index from a previous multi-frame image
951        // does not cause an out-of-bounds panic when the image is replaced
952        // with one that has fewer frames.
953        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
954            div()
955                .child(img(ImageSource::Render(test_image(5))).id(TEST_IMG_ID))
956                .child(seed_frame_index(4))
957                .into_any_element()
958        });
959        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
960            img(ImageSource::Render(test_image(1)))
961                .id(TEST_IMG_ID)
962                .into_any_element()
963        });
964    }
965}