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                            // `auto` and `auto <ratio>` (zero and negative) take the natural ratio.
347                            let ratio = style
348                                .aspect_ratio
349                                .filter(|ratio| *ratio > 0.0)
350                                .unwrap_or(image_size.width / image_size.height);
351                            style.aspect_ratio = Some(ratio);
352
353                            if let Length::Auto = style.size.width {
354                                style.size.width = match style.size.height {
355                                    Length::Definite(DefiniteLength::Absolute(abs_length))
356                                        if ratio.is_finite() && ratio > 0.0 =>
357                                    {
358                                        let height_px = abs_length.to_pixels(window.rem_size());
359                                        Length::Definite(px(height_px.0 * ratio).into())
360                                    }
361                                    _ => Length::Definite(image_size.width.into()),
362                                };
363                            }
364
365                            // A relative width leaves the height to the ratio, as a browser does.
366                            if let (
367                                Length::Auto,
368                                Length::Definite(DefiniteLength::Absolute(abs_length)),
369                            ) = (style.size.height, style.size.width)
370                                && ratio.is_finite()
371                                && ratio > 0.0
372                            {
373                                let width_px = abs_length.to_pixels(window.rem_size());
374                                style.size.height = Length::Definite(px(width_px.0 / ratio).into());
375                            }
376
377                            if global_id.is_some()
378                                && data.frame_count() > 1
379                                && window.is_window_active()
380                                && !cx.reduce_motion()
381                            {
382                                window.request_animation_frame();
383                            }
384                        }
385                        Some(_err) => {
386                            if let Some(fallback) = self.style.fallback.as_ref() {
387                                let mut element = fallback();
388                                replacement_id = Some(element.request_layout(window, cx));
389                                layout_state.replacement = Some(element);
390                            }
391                            if let Some(state) = &mut state {
392                                state.started_loading = None;
393                            }
394                        }
395                        None => {
396                            if let Some(state) = &mut state {
397                                if let Some((started_loading, _)) = state.started_loading {
398                                    if started_loading.elapsed() > LOADING_DELAY
399                                        && let Some(loading) = self.style.loading.as_ref()
400                                    {
401                                        let mut element = loading();
402                                        replacement_id = Some(element.request_layout(window, cx));
403                                        layout_state.replacement = Some(element);
404                                    }
405                                } else {
406                                    let current_view = window.current_view();
407                                    let task = window.spawn(cx, async move |cx| {
408                                        cx.background_executor().timer(LOADING_DELAY).await;
409                                        cx.update(move |_, cx| {
410                                            cx.notify(current_view);
411                                        })
412                                        .ok();
413                                    });
414                                    state.started_loading = Some((Instant::now(), task));
415                                }
416                            }
417                        }
418                    }
419
420                    window.request_layout(style, replacement_id, cx)
421                },
422            );
423
424            layout_state.frame_index = frame_index;
425
426            ((layout_id, layout_state), state)
427        })
428    }
429
430    fn prepaint(
431        &mut self,
432        global_id: Option<&GlobalElementId>,
433        inspector_id: Option<&InspectorElementId>,
434        bounds: Bounds<Pixels>,
435        request_layout: &mut Self::RequestLayoutState,
436        window: &mut Window,
437        cx: &mut App,
438    ) -> Self::PrepaintState {
439        self.interactivity.prepaint(
440            global_id,
441            inspector_id,
442            bounds,
443            bounds.size,
444            window,
445            cx,
446            |_, _, hitbox, window, cx| {
447                if let Some(replacement) = &mut request_layout.replacement {
448                    replacement.prepaint(window, cx);
449                }
450
451                hitbox
452            },
453        )
454    }
455
456    fn paint(
457        &mut self,
458        global_id: Option<&GlobalElementId>,
459        inspector_id: Option<&InspectorElementId>,
460        bounds: Bounds<Pixels>,
461        layout_state: &mut Self::RequestLayoutState,
462        hitbox: &mut Self::PrepaintState,
463        window: &mut Window,
464        cx: &mut App,
465    ) {
466        let source = self.source.clone();
467        self.interactivity.paint(
468            global_id,
469            inspector_id,
470            bounds,
471            hitbox.as_ref(),
472            window,
473            cx,
474            |style, window, cx| {
475                if let Some(Ok(data)) = source.use_data(
476                    self.image_cache
477                        .clone()
478                        .or_else(|| window.image_cache_stack.last().cloned()),
479                    window,
480                    cx,
481                ) {
482                    if data.frame_count() == 0 {
483                        return;
484                    }
485                    // vue-native fork: the picture's size, not its pixels' (an
486                    // embedder may have swapped in a smaller copy).
487                    let natural = data.natural_size(layout_state.frame_index);
488                    let new_bounds = match style.vn_object_position {
489                        Some(position) => {
490                            self.style.object_fit.get_bounds_at(bounds, natural, position)
491                        }
492                        None => self.style.object_fit.get_bounds(bounds, natural),
493                    };
494                    // vue-native fork: percentages and the overlap rule resolve
495                    // against the box (`Style::corner_radii_for`).
496                    let corner_radii = style.corner_radii_for(bounds.size, window.rem_size());
497                    window
498                        .paint_image(
499                            bounds,
500                            new_bounds,
501                            corner_radii,
502                            data,
503                            layout_state.frame_index,
504                            self.style.grayscale,
505                        )
506                        .log_err();
507                } else if let Some(replacement) = &mut layout_state.replacement {
508                    replacement.paint(window, cx);
509                }
510            },
511        )
512    }
513}
514
515impl Styled for Img {
516    fn style(&mut self) -> &mut StyleRefinement {
517        &mut self.interactivity.base_style
518    }
519}
520
521impl InteractiveElement for Img {
522    fn interactivity(&mut self) -> &mut Interactivity {
523        &mut self.interactivity
524    }
525}
526
527impl StatefulInteractiveElement for Img {}
528
529impl ImageSource {
530    pub(crate) fn use_data(
531        &self,
532        cache: Option<AnyImageCache>,
533        window: &mut Window,
534        cx: &mut App,
535    ) -> Option<Result<Arc<RenderImage>, ImageCacheError>> {
536        match self {
537            ImageSource::Resource(resource) => {
538                if let Some(cache) = cache {
539                    cache.load(resource, window, cx)
540                } else {
541                    window.use_asset::<ImgResourceLoader>(resource, cx)
542                }
543            }
544            ImageSource::Custom(loading_fn) => loading_fn(window, cx),
545            ImageSource::Render(data) => Some(Ok(data.to_owned())),
546            ImageSource::Image(data) => window.use_asset::<AssetLogger<ImageDecoder>>(data, cx),
547        }
548    }
549
550    pub(crate) fn get_data(
551        &self,
552        cache: Option<AnyImageCache>,
553        window: &mut Window,
554        cx: &mut App,
555    ) -> Option<Result<Arc<RenderImage>, ImageCacheError>> {
556        match self {
557            ImageSource::Resource(resource) => {
558                if let Some(cache) = cache {
559                    cache.load(resource, window, cx)
560                } else {
561                    window.get_asset::<ImgResourceLoader>(resource, cx)
562                }
563            }
564            ImageSource::Custom(loading_fn) => loading_fn(window, cx),
565            ImageSource::Render(data) => Some(Ok(data.to_owned())),
566            ImageSource::Image(data) => window.get_asset::<AssetLogger<ImageDecoder>>(data, cx),
567        }
568    }
569
570    /// Remove this image source from the asset system
571    pub fn remove_asset(&self, cx: &mut App) {
572        match self {
573            ImageSource::Resource(resource) => {
574                cx.remove_asset::<ImgResourceLoader>(resource);
575            }
576            ImageSource::Custom(_) | ImageSource::Render(_) => {}
577            ImageSource::Image(data) => cx.remove_asset::<AssetLogger<ImageDecoder>>(data),
578        }
579    }
580
581    /// vue-native fork: the decode the asset system holds for this source, if
582    /// its load has finished. Never starts a load.
583    pub fn cached(&self, cx: &App) -> Option<Arc<RenderImage>> {
584        match self {
585            ImageSource::Resource(resource) => cx.peek_asset::<ImgResourceLoader>(resource)?.ok(),
586            ImageSource::Image(data) => cx.peek_asset::<AssetLogger<ImageDecoder>>(data)?.ok(),
587            ImageSource::Custom(_) | ImageSource::Render(_) => None,
588        }
589    }
590
591    /// vue-native fork: makes `image` what the asset system answers for this
592    /// source from now on — a smaller copy of the decode
593    /// ([`RenderImage::with_natural_size`]), or the full decode back. `false`
594    /// when the source is still loading, or is not one the asset system caches.
595    pub fn replace_cached(&self, image: Arc<RenderImage>, cx: &mut App) -> bool {
596        match self {
597            ImageSource::Resource(resource) => {
598                cx.replace_asset::<ImgResourceLoader>(resource, Ok(image))
599            }
600            ImageSource::Image(data) => {
601                cx.replace_asset::<AssetLogger<ImageDecoder>>(data, Ok(image))
602            }
603            ImageSource::Custom(_) | ImageSource::Render(_) => false,
604        }
605    }
606
607    /// vue-native fork: loads and decodes this source afresh on the background
608    /// executor, leaving the asset system's entry as it is (an embedder that
609    /// swapped in a smaller copy gets the full decode back this way without
610    /// the element going blank meanwhile). `None` for a source the asset
611    /// system does not load.
612    pub fn load_detached(
613        &self,
614        cx: &mut App,
615    ) -> Option<Task<Result<Arc<RenderImage>, ImageCacheError>>> {
616        match self {
617            ImageSource::Resource(resource) => {
618                let load = <ImgResourceLoader as Asset>::load(resource.clone(), cx);
619                Some(cx.background_executor().spawn(load))
620            }
621            ImageSource::Image(data) => {
622                let load = <AssetLogger<ImageDecoder> as Asset>::load(data.clone(), cx);
623                Some(cx.background_executor().spawn(load))
624            }
625            ImageSource::Custom(_) | ImageSource::Render(_) => None,
626        }
627    }
628
629    /// Check whether this image source is present in the asset system (loading
630    /// or loaded), without fetching it.
631    #[cfg(any(test, feature = "test-support"))]
632    pub fn is_asset_cached(&self, cx: &App) -> bool {
633        match self {
634            ImageSource::Resource(resource) => cx.has_asset::<ImgResourceLoader>(resource),
635            ImageSource::Custom(_) | ImageSource::Render(_) => false,
636            ImageSource::Image(data) => cx.has_asset::<AssetLogger<ImageDecoder>>(data),
637        }
638    }
639}
640
641#[derive(Clone)]
642enum ImageDecoder {}
643
644impl Asset for ImageDecoder {
645    type Source = Arc<Image>;
646    type Output = Result<Arc<RenderImage>, ImageCacheError>;
647
648    fn load(
649        source: Self::Source,
650        cx: &mut App,
651    ) -> impl Future<Output = Self::Output> + Send + 'static {
652        let renderer = cx.svg_renderer();
653        async move { source.to_image_data(renderer).map_err(Into::into) }
654    }
655}
656
657/// An image loader for the GPUI asset system
658#[derive(Clone)]
659pub enum ImageAssetLoader {}
660
661impl Asset for ImageAssetLoader {
662    type Source = Resource;
663    type Output = Result<Arc<RenderImage>, ImageCacheError>;
664
665    fn load(
666        source: Self::Source,
667        cx: &mut App,
668    ) -> impl Future<Output = Self::Output> + Send + 'static {
669        let client = cx.http_client();
670        // TODO: Can we make SVGs always rescale?
671        // let scale_factor = cx.scale_factor();
672        let svg_renderer = cx.svg_renderer();
673        let asset_source = cx.asset_source().clone();
674        async move {
675            let bytes = match source.clone() {
676                Resource::Path(uri) => fs::read(uri.as_ref())?,
677                Resource::Uri(uri) => {
678                    use anyhow::Context as _;
679                    use futures::AsyncReadExt as _;
680
681                    let mut response = client
682                        .get(uri.as_ref(), ().into(), true)
683                        .await
684                        .with_context(|| format!("loading image asset from {uri:?}"))?;
685                    let mut body = Vec::new();
686                    response.body_mut().read_to_end(&mut body).await?;
687                    if !response.status().is_success() {
688                        let mut body = String::from_utf8_lossy(&body).into_owned();
689                        let first_line = body.lines().next().unwrap_or("").trim_end();
690                        body.truncate(first_line.len());
691                        return Err(ImageCacheError::BadStatus {
692                            uri,
693                            status: response.status(),
694                            body,
695                        });
696                    }
697                    body
698                }
699                Resource::Embedded(path) => {
700                    let data = asset_source.load(&path).ok().flatten();
701                    if let Some(data) = data {
702                        data.to_vec()
703                    } else {
704                        return Err(ImageCacheError::Asset(
705                            format!("Embedded resource not found: {}", path).into(),
706                        ));
707                    }
708                }
709            };
710
711            if let Ok(format) = image::guess_format(&bytes) {
712                let data = match format {
713                    ImageFormat::Gif => decode_gif_image(&bytes)?,
714                    ImageFormat::WebP => decode_webp_image(&bytes)?,
715                    _ => decode_static_image(&bytes, format)?,
716                };
717
718                Ok(Arc::new(RenderImage::new(data)))
719            } else {
720                svg_renderer
721                    .render_single_frame(&bytes, 1.0)
722                    .map_err(Into::into)
723            }
724        }
725    }
726}
727
728/// An error that can occur when interacting with the image cache.
729#[derive(Debug, Error, Clone)]
730pub enum ImageCacheError {
731    /// Some other kind of error occurred
732    #[error("error: {0}")]
733    Other(#[from] Arc<anyhow::Error>),
734    /// An error that occurred while reading the image from disk.
735    #[error("IO error: {0}")]
736    Io(Arc<std::io::Error>),
737    /// An error that occurred while processing an image.
738    #[error("unexpected http status for {uri}: {status}, body: {body}")]
739    BadStatus {
740        /// The URI of the image.
741        uri: SharedUri,
742        /// The HTTP status code.
743        status: http_client::StatusCode,
744        /// The HTTP response body.
745        body: String,
746    },
747    /// An error that occurred while processing an asset.
748    #[error("asset error: {0}")]
749    Asset(SharedString),
750    /// An error that occurred while processing an image.
751    #[error("image error: {0}")]
752    Image(Arc<ImageError>),
753    /// An error that occurred while processing an SVG.
754    #[error("svg error: {0}")]
755    Usvg(Arc<usvg::Error>),
756}
757
758impl From<anyhow::Error> for ImageCacheError {
759    fn from(value: anyhow::Error) -> Self {
760        Self::Other(Arc::new(value))
761    }
762}
763
764impl From<io::Error> for ImageCacheError {
765    fn from(value: io::Error) -> Self {
766        Self::Io(Arc::new(value))
767    }
768}
769
770impl From<usvg::Error> for ImageCacheError {
771    fn from(value: usvg::Error) -> Self {
772        Self::Usvg(Arc::new(value))
773    }
774}
775
776impl From<image::ImageError> for ImageCacheError {
777    fn from(value: image::ImageError) -> Self {
778        Self::Image(Arc::new(value))
779    }
780}
781
782#[cfg(test)]
783mod tests {
784    use super::*;
785    use crate::{IntoElement, ParentElement as _, TestAppContext, canvas, div, point, px, size};
786    use image::{Frame, ImageBuffer, Rgba};
787    use smallvec::SmallVec;
788
789    const TEST_IMG_ID: &str = "test-img";
790
791    fn test_image(frame_count: usize) -> Arc<RenderImage> {
792        let frame = Frame::new(ImageBuffer::from_pixel(1, 1, Rgba([0, 0, 0, 0])));
793        Arc::new(RenderImage::new(SmallVec::from_iter(
794            (0..frame_count).map(|_| frame.clone()),
795        )))
796    }
797
798    fn test_image_with_size(width: u32, height: u32) -> Arc<RenderImage> {
799        let frame = Frame::new(ImageBuffer::from_pixel(width, height, Rgba([0, 0, 0, 0])));
800        Arc::new(RenderImage::new(SmallVec::from_elem(frame, 1)))
801    }
802
803    /// Overwrites the cached `frame_index` of the sibling `img` during paint.
804    fn seed_frame_index(frame_index: usize) -> impl IntoElement {
805        canvas(
806            |_, _, _| (),
807            move |_, _, window, _| {
808                window.with_global_id(TEST_IMG_ID.into(), |id, window| {
809                    window.with_element_state::<ImgState, _>(id, |state, _| {
810                        let mut state = state.expect("img state should be initialized");
811                        state.frame_index = frame_index;
812                        ((), state)
813                    });
814                });
815            },
816        )
817    }
818
819    #[gpui::test]
820    fn zero_frame_image_does_not_panic_on_paint(cx: &mut TestAppContext) {
821        cx.add_empty_window()
822            .draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
823                img(ImageSource::Render(test_image(0))).into_any_element()
824            });
825    }
826
827    #[gpui::test]
828    fn image_object_fit_cover_crops_to_element_bounds(cx: &mut TestAppContext) {
829        let window = cx.add_empty_window();
830        let image = test_image_with_size(200, 100);
831        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
832            img(ImageSource::Render(image.clone()))
833                .size_full()
834                .object_fit(ObjectFit::Fill)
835                .into_any_element()
836        });
837        let full_tile_bounds = window.update(|window, _| {
838            window
839                .rendered_frame
840                .scene
841                .polychrome_sprites
842                .last()
843                .expect("fill image should paint a sprite")
844                .tile
845                .bounds
846        });
847
848        window.draw(point(px(10.), px(20.)), size(px(100.), px(100.)), |_, _| {
849            img(ImageSource::Render(image))
850                .size_full()
851                .object_fit(ObjectFit::Cover)
852                .into_any_element()
853        });
854
855        let (rendered_bounds, rendered_tile_bounds, scale_factor) = window.update(|window, _| {
856            let sprite = window
857                .rendered_frame
858                .scene
859                .polychrome_sprites
860                .last()
861                .expect("cover image should paint a sprite");
862            (sprite.bounds, sprite.tile.bounds, window.scale_factor())
863        });
864        assert_eq!(
865            rendered_bounds,
866            Bounds {
867                origin: point(px(10.).scale(scale_factor), px(20.).scale(scale_factor)),
868                size: size(px(100.).scale(scale_factor), px(100.).scale(scale_factor)),
869            }
870        );
871        assert_eq!(
872            (
873                rendered_tile_bounds.origin.x.0 - full_tile_bounds.origin.x.0,
874                rendered_tile_bounds.origin.y.0 - full_tile_bounds.origin.y.0,
875                rendered_tile_bounds.size.width.0,
876                rendered_tile_bounds.size.height.0,
877            ),
878            (50, 0, 100, 100),
879        );
880    }
881
882    #[gpui::test]
883    fn explicit_aspect_ratio_is_not_overridden_by_intrinsic_ratio(cx: &mut TestAppContext) {
884        let window = cx.add_empty_window();
885
886        // A portrait image in a square container
887        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
888            div()
889                .size(px(100.))
890                .overflow_hidden()
891                .child(
892                    img(ImageSource::Render(test_image_with_size(100, 200)))
893                        .size_full()
894                        .aspect_square()
895                        .object_fit(ObjectFit::Contain),
896                )
897                .into_any_element()
898        });
899
900        let (rendered_bounds, scale_factor) = window.update(|window, _| {
901            let sprite = window
902                .rendered_frame
903                .scene
904                .polychrome_sprites
905                .last()
906                .expect("contained image should paint a sprite");
907            (sprite.bounds, window.scale_factor())
908        });
909
910        // The element stays 100x100, so the image is letterboxed horizontally
911        assert_eq!(
912            rendered_bounds,
913            Bounds {
914                origin: point(px(25.).scale(scale_factor), px(0.).scale(scale_factor)),
915                size: size(px(50.).scale(scale_factor), px(100.).scale(scale_factor)),
916            }
917        );
918    }
919
920    #[gpui::test]
921    fn image_object_fit_cover_clamps_corner_radii_to_visible_bounds(cx: &mut TestAppContext) {
922        let window = cx.add_empty_window();
923        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
924            img(ImageSource::Render(test_image_with_size(200, 100)))
925                .size_full()
926                .rounded(px(100.))
927                .object_fit(ObjectFit::Cover)
928                .into_any_element()
929        });
930
931        let (corner_radius, expected_corner_radius) = window.update(|window, _| {
932            (
933                window
934                    .rendered_frame
935                    .scene
936                    .polychrome_sprites
937                    .last()
938                    .map(|sprite| sprite.corner_radii.top_left),
939                px(50.).scale(window.scale_factor()),
940            )
941        });
942        assert_eq!(corner_radius, Some(expected_corner_radius));
943    }
944
945    #[gpui::test]
946    fn stale_frame_index_is_clamped_when_image_changes(cx: &mut TestAppContext) {
947        let window = cx.add_empty_window();
948
949        // Assert that a cached frame_index from a previous multi-frame image
950        // does not cause an out-of-bounds panic when the image is replaced
951        // with one that has fewer frames.
952        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
953            div()
954                .child(img(ImageSource::Render(test_image(5))).id(TEST_IMG_ID))
955                .child(seed_frame_index(4))
956                .into_any_element()
957        });
958        window.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, _| {
959            img(ImageSource::Render(test_image(1)))
960                .id(TEST_IMG_ID)
961                .into_any_element()
962        });
963    }
964}