Managed texture loading (#3297)

* add types from proposal

* add load methods on `egui::Context`

* implement loaders from proposal in `egui_extras`

* impl `From<Vec2>` for `SizeHint`

* re-export `SizeHint` from `egui` root

* rework `svg` example to use new managed `Image`

* split loaders into separate files + add logging

* add `log_trace`

* clean up `RetainedImage` from `svg` example

* refactor ehttp loader response to bytes mapping

* remove spammy trace

* load images even without extension

* fix lints

* remove unused imports

* use `Image2` in `download_image`

* use `visuals.error_fg_color` in `Image2` error state

* update lockfile

* use `Arc<ColorImage>` in `ImageData` + add `forget` API

* add `ui.image2`

* add byte size query api

* use iterators to sum loader byte sizes

* add static image loading

* use static image in `svg` example

* small refactor of `Image2::ui` texture loading code

* add `ImageFit` to size images properly

* remove println calls

* add bad image load to `download_image` example

* add loader file extension support tests

* fix lint errors in `loaders`

* remove unused `poll-promise` dependency

* add some docs to `Image2`

* add some docs to `egui_extras::loaders::install`

* explain `loaders::install` in examples

* fix lint

* upgrade `ehttp` to `0.3` for some crates

* Remove some unused dependencies

* Remove unnecessary context clone

* Turn on the `log` create feature of egui_extras in all examples

* rename `forget` and document it

* derive `Debug` on `SizeHint`

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

* round when converting SizeHint from vec2

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

* add `load` module docs

* docstring `add_loader` methods

* expose + document `load_include_bytes`

* cache texture handles in `DefaultTextureLoader`

* add `image2` doctest + further document `Image2`

* use `Default` for default `Image2` options

* update `image2` doc comment

* mention immediate-mode safety

* more fit calculation into inherent impl

* add hover text on spinner

* add `all-loaders` feature

* clarify `egui_extras::loaders::install` behavior

* explain how to enable image formats

* properly format `uri`

* use `thread::Builder` instead of `spawn`

* use eq op instead of `matches`

* inline `From<Arc<ColorImage>>` for `ImageData`

* allow non-`'static` bytes + `forget` in `DefaultTextureLoader`

* sort features

* change `ehttp` feature to `http`

* update `Image2` docs

* refactor loader cache type

---------

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

crates/egui_extras/src/loaders/ehttp_loader.rs

@@ -0,0 +1,107 @@
+use egui::{
+    ahash::HashMap,
+    load::{Bytes, BytesLoadResult, BytesLoader, BytesPoll, LoadError},
+    mutex::Mutex,
+};
+use std::{sync::Arc, task::Poll};
+
+type Entry = Poll<Result<Arc<[u8]>, String>>;
+
+#[derive(Default)]
+pub struct EhttpLoader {
+    cache: Arc<Mutex<HashMap<String, Entry>>>,
+}
+
+const PROTOCOLS: &[&str] = &["http://", "https://"];
+
+fn starts_with_one_of(s: &str, prefixes: &[&str]) -> bool {
+    prefixes.iter().any(|prefix| s.starts_with(prefix))
+}
+
+fn get_image_bytes(
+    uri: &str,
+    response: Result<ehttp::Response, String>,
+) -> Result<Arc<[u8]>, String> {
+    let response = response?;
+    if !response.ok {
+        match response.text() {
+            Some(response_text) => {
+                return Err(format!(
+                    "failed to load {uri:?}: {} {} {response_text}",
+                    response.status, response.status_text
+                ))
+            }
+            None => {
+                return Err(format!(
+                    "failed to load {uri:?}: {} {}",
+                    response.status, response.status_text
+                ))
+            }
+        }
+    }
+
+    let Some(content_type) = response.content_type() else {
+    return Err(format!("failed to load {uri:?}: no content-type header found"));
+  };
+    if !content_type.starts_with("image/") {
+        return Err(format!("failed to load {uri:?}: expected content-type starting with \"image/\", found {content_type:?}"));
+    }
+
+    Ok(response.bytes.into())
+}
+
+impl BytesLoader for EhttpLoader {
+    fn load(&self, ctx: &egui::Context, uri: &str) -> BytesLoadResult {
+        if !starts_with_one_of(uri, PROTOCOLS) {
+            return Err(LoadError::NotSupported);
+        }
+
+        let mut cache = self.cache.lock();
+        if let Some(entry) = cache.get(uri).cloned() {
+            match entry {
+                Poll::Ready(Ok(bytes)) => Ok(BytesPoll::Ready {
+                    size: None,
+                    bytes: Bytes::Shared(bytes),
+                }),
+                Poll::Ready(Err(err)) => Err(LoadError::Custom(err)),
+                Poll::Pending => Ok(BytesPoll::Pending { size: None }),
+            }
+        } else {
+            crate::log_trace!("started loading {uri:?}");
+
+            let uri = uri.to_owned();
+            cache.insert(uri.clone(), Poll::Pending);
+            drop(cache);
+
+            ehttp::fetch(ehttp::Request::get(uri.clone()), {
+                let ctx = ctx.clone();
+                let cache = self.cache.clone();
+                move |response| {
+                    let result = get_image_bytes(&uri, response);
+                    crate::log_trace!("finished loading {uri:?}");
+                    let prev = cache.lock().insert(uri, Poll::Ready(result));
+                    assert!(matches!(prev, Some(Poll::Pending)));
+                    ctx.request_repaint();
+                }
+            });
+
+            Ok(BytesPoll::Pending { size: None })
+        }
+    }
+
+    fn forget(&self, uri: &str) {
+        let _ = self.cache.lock().remove(uri);
+    }
+
+    fn byte_size(&self) -> usize {
+        self.cache
+            .lock()
+            .values()
+            .map(|entry| match entry {
+                Poll::Ready(Ok(bytes)) => bytes.len(),
+                Poll::Ready(Err(err)) => err.len(),
+                _ => 0,
+            })
+            .sum()
+    }
+}

crates/egui_extras/src/loaders/file_loader.rs

@@ -0,0 +1,84 @@
+use egui::{
+    ahash::HashMap,
+    load::{Bytes, BytesLoadResult, BytesLoader, BytesPoll, LoadError},
+    mutex::Mutex,
+};
+use std::{sync::Arc, task::Poll, thread};
+
+type Entry = Poll<Result<Arc<[u8]>, String>>;
+
+#[derive(Default)]
+pub struct FileLoader {
+    /// Cache for loaded files
+    cache: Arc<Mutex<HashMap<String, Entry>>>,
+}
+
+const PROTOCOL: &str = "file://";
+
+impl BytesLoader for FileLoader {
+    fn load(&self, ctx: &egui::Context, uri: &str) -> BytesLoadResult {
+        // File loader only supports the `file` protocol.
+        let Some(path) = uri.strip_prefix(PROTOCOL) else {
+            return Err(LoadError::NotSupported);
+        };
+
+        let mut cache = self.cache.lock();
+        if let Some(entry) = cache.get(path).cloned() {
+            // `path` has either begun loading, is loaded, or has failed to load.
+            match entry {
+                Poll::Ready(Ok(bytes)) => Ok(BytesPoll::Ready {
+                    size: None,
+                    bytes: Bytes::Shared(bytes),
+                }),
+                Poll::Ready(Err(err)) => Err(LoadError::Custom(err)),
+                Poll::Pending => Ok(BytesPoll::Pending { size: None }),
+            }
+        } else {
+            crate::log_trace!("started loading {uri:?}");
+            // We need to load the file at `path`.
+
+            // Set the file to `pending` until we finish loading it.
+            let path = path.to_owned();
+            cache.insert(path.clone(), Poll::Pending);
+            drop(cache);
+
+            // Spawn a thread to read the file, so that we don't block the render for too long.
+            thread::Builder::new()
+                .name(format!("egui_extras::FileLoader::load({uri:?})"))
+                .spawn({
+                    let ctx = ctx.clone();
+                    let cache = self.cache.clone();
+                    let uri = uri.to_owned();
+                    move || {
+                        let result = match std::fs::read(&path) {
+                            Ok(bytes) => Ok(bytes.into()),
+                            Err(err) => Err(err.to_string()),
+                        };
+                        let prev = cache.lock().insert(path, Poll::Ready(result));
+                        assert!(matches!(prev, Some(Poll::Pending)));
+                        ctx.request_repaint();
+                        crate::log_trace!("finished loading {uri:?}");
+                    }
+                })
+                .expect("failed to spawn thread");
+
+            Ok(BytesPoll::Pending { size: None })
+        }
+    }
+
+    fn forget(&self, uri: &str) {
+        let _ = self.cache.lock().remove(uri);
+    }
+
+    fn byte_size(&self) -> usize {
+        self.cache
+            .lock()
+            .values()
+            .map(|entry| match entry {
+                Poll::Ready(Ok(bytes)) => bytes.len(),
+                Poll::Ready(Err(err)) => err.len(),
+                _ => 0,
+            })
+            .sum()
+    }
+}

crates/egui_extras/src/loaders/image_loader.rs

@@ -0,0 +1,84 @@
+use egui::{
+    ahash::HashMap,
+    load::{BytesPoll, ImageLoadResult, ImageLoader, ImagePoll, LoadError, SizeHint},
+    mutex::Mutex,
+    ColorImage,
+};
+use std::{mem::size_of, path::Path, sync::Arc};
+
+type Entry = Result<Arc<ColorImage>, String>;
+
+#[derive(Default)]
+pub struct ImageCrateLoader {
+    cache: Mutex<HashMap<String, Entry>>,
+}
+
+fn is_supported(uri: &str) -> bool {
+    let Some(ext) = Path::new(uri).extension().and_then(|ext| ext.to_str()) else {
+        // `true` because if there's no extension, assume that we support it
+        return true
+    };
+
+    ext != "svg"
+}
+
+impl ImageLoader for ImageCrateLoader {
+    fn load(&self, ctx: &egui::Context, uri: &str, _: SizeHint) -> ImageLoadResult {
+        if !is_supported(uri) {
+            return Err(LoadError::NotSupported);
+        }
+
+        let mut cache = self.cache.lock();
+        if let Some(entry) = cache.get(uri).cloned() {
+            match entry {
+                Ok(image) => Ok(ImagePoll::Ready { image }),
+                Err(err) => Err(LoadError::Custom(err)),
+            }
+        } else {
+            match ctx.try_load_bytes(uri) {
+                Ok(BytesPoll::Ready { bytes, .. }) => {
+                    crate::log_trace!("started loading {uri:?}");
+                    let result = crate::image::load_image_bytes(&bytes).map(Arc::new);
+                    crate::log_trace!("finished loading {uri:?}");
+                    cache.insert(uri.into(), result.clone());
+                    match result {
+                        Ok(image) => Ok(ImagePoll::Ready { image }),
+                        Err(err) => Err(LoadError::Custom(err)),
+                    }
+                }
+                Ok(BytesPoll::Pending { size }) => Ok(ImagePoll::Pending { size }),
+                Err(err) => Err(err),
+            }
+        }
+    }
+
+    fn forget(&self, uri: &str) {
+        let _ = self.cache.lock().remove(uri);
+    }
+
+    fn byte_size(&self) -> usize {
+        self.cache
+            .lock()
+            .values()
+            .map(|result| match result {
+                Ok(image) => image.pixels.len() * size_of::<egui::Color32>(),
+                Err(err) => err.len(),
+            })
+            .sum()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn check_support() {
+        assert!(is_supported("https://test.png"));
+        assert!(is_supported("test.jpeg"));
+        assert!(is_supported("http://test.gif"));
+        assert!(is_supported("test.webp"));
+        assert!(is_supported("file://test"));
+        assert!(!is_supported("test.svg"));
+    }
+}

crates/egui_extras/src/loaders/svg_loader.rs

@@ -0,0 +1,92 @@
+use egui::{
+    ahash::HashMap,
+    load::{BytesPoll, ImageLoadResult, ImageLoader, ImagePoll, LoadError, SizeHint},
+    mutex::Mutex,
+    ColorImage,
+};
+use std::{mem::size_of, path::Path, sync::Arc};
+
+type Entry = Result<Arc<ColorImage>, String>;
+
+#[derive(Default)]
+pub struct SvgLoader {
+    cache: Mutex<HashMap<(String, SizeHint), Entry>>,
+}
+
+fn is_supported(uri: &str) -> bool {
+    let Some(ext) = Path::new(uri).extension().and_then(|ext| ext.to_str()) else { return false };
+
+    ext == "svg"
+}
+
+impl ImageLoader for SvgLoader {
+    fn load(&self, ctx: &egui::Context, uri: &str, size_hint: SizeHint) -> ImageLoadResult {
+        if !is_supported(uri) {
+            return Err(LoadError::NotSupported);
+        }
+
+        let uri = uri.to_owned();
+
+        let mut cache = self.cache.lock();
+        // We can't avoid the `uri` clone here without unsafe code.
+        if let Some(entry) = cache.get(&(uri.clone(), size_hint)).cloned() {
+            match entry {
+                Ok(image) => Ok(ImagePoll::Ready { image }),
+                Err(err) => Err(LoadError::Custom(err)),
+            }
+        } else {
+            match ctx.try_load_bytes(&uri) {
+                Ok(BytesPoll::Ready { bytes, .. }) => {
+                    crate::log_trace!("started loading {uri:?}");
+                    let fit_to = match size_hint {
+                        SizeHint::Original => usvg::FitTo::Original,
+                        SizeHint::Width(w) => usvg::FitTo::Width(w),
+                        SizeHint::Height(h) => usvg::FitTo::Height(h),
+                        SizeHint::Size(w, h) => usvg::FitTo::Size(w, h),
+                    };
+                    let result =
+                        crate::image::load_svg_bytes_with_size(&bytes, fit_to).map(Arc::new);
+                    crate::log_trace!("finished loading {uri:?}");
+                    cache.insert((uri, size_hint), result.clone());
+                    match result {
+                        Ok(image) => Ok(ImagePoll::Ready { image }),
+                        Err(err) => Err(LoadError::Custom(err)),
+                    }
+                }
+                Ok(BytesPoll::Pending { size }) => Ok(ImagePoll::Pending { size }),
+                Err(err) => Err(err),
+            }
+        }
+    }
+
+    fn forget(&self, uri: &str) {
+        self.cache.lock().retain(|(u, _), _| u != uri);
+    }
+
+    fn byte_size(&self) -> usize {
+        self.cache
+            .lock()
+            .values()
+            .map(|result| match result {
+                Ok(image) => image.pixels.len() * size_of::<egui::Color32>(),
+                Err(err) => err.len(),
+            })
+            .sum()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn check_support() {
+        // inverse of same test in `image_loader.rs`
+        assert!(!is_supported("https://test.png"));
+        assert!(!is_supported("test.jpeg"));
+        assert!(!is_supported("http://test.gif"));
+        assert!(!is_supported("test.webp"));
+        assert!(!is_supported("file://test"));
+        assert!(is_supported("test.svg"));
+    }
+}