Managed texture loading

crates/egui/src/context.rs

@@ -1905,24 +1905,38 @@ impl Context {
 
 /// ## Image loading
 impl Context {
-    pub(crate) fn load_include_bytes(&self, name: &'static str, bytes: &'static [u8]) {
-        self.read(|ctx| ctx.loaders.include.insert(name, bytes));
+    /// Associate some static bytes with a `uri`.
+    ///
+    /// The same `uri` may be passed to [`Ui::image2`] later to load the bytes as an image.
+    pub fn load_include_bytes(&self, uri: &'static str, bytes: &'static [u8]) {
+        self.read(|ctx| ctx.loaders.include.insert(uri, bytes));
     }
 
+    /// Append an entry onto the chain of bytes loaders.
+    ///
+    /// See [`load`] for more information.
     pub fn add_bytes_loader(&self, loader: Arc<dyn load::BytesLoader + Send + Sync + 'static>) {
         self.write(|ctx| ctx.loaders.bytes.push(loader));
     }
 
+    /// Append an entry onto the chain of image loaders.
+    ///
+    /// See [`load`] for more information.
     pub fn add_image_loader(&self, loader: Arc<dyn load::ImageLoader + Send + Sync + 'static>) {
         self.write(|ctx| ctx.loaders.image.push(loader));
     }
 
+    /// Append an entry onto the chain of texture loaders.
+    ///
+    /// See [`load`] for more information.
     pub fn add_texture_loader(&self, loader: Arc<dyn load::TextureLoader + Send + Sync + 'static>) {
         self.write(|ctx| ctx.loaders.texture.push(loader));
     }
 
-    // TODO: evict caches
-    pub fn forget(&self, uri: &str) {
+    /// Release all memory and textures related to the given image URI.
+    ///
+    /// If you attempt to load the image again, it will be reloaded from scratch.
+    pub fn forget_image(&self, uri: &str) {
         self.write(|ctx| {
             use crate::load::BytesLoader as _;
 
@@ -1944,6 +1958,8 @@ impl Context {
 
     /// Try loading the bytes from the given uri using any available bytes loaders.
     ///
+    /// Loaders are expected to cache results, so that this call is immediate-mode safe.
+    ///
     /// This calls the loaders one by one in the order in which they were registered.
     /// If a loader returns [`LoadError::NotSupported`][not_supported],
     /// then the next loader is called. This process repeats until all loaders have
@@ -1971,6 +1987,8 @@ impl Context {
 
     /// Try loading the image from the given uri using any available image loaders.
     ///
+    /// Loaders are expected to cache results, so that this call is immediate-mode safe.
+    ///
     /// This calls the loaders one by one in the order in which they were registered.
     /// If a loader returns [`LoadError::NotSupported`][not_supported],
     /// then the next loader is called. This process repeats until all loaders have
@@ -1998,6 +2016,8 @@ impl Context {
 
     /// Try loading the texture from the given uri using any available texture loaders.
     ///
+    /// Loaders are expected to cache results, so that this call is immediate-mode safe.
+    ///
     /// This calls the loaders one by one in the order in which they were registered.
     /// If a loader returns [`LoadError::NotSupported`][not_supported],
     /// then the next loader is called. This process repeats until all loaders have

crates/egui/src/load.rs

@@ -1,6 +1,57 @@
+//! Types and traits related to image loading.
+//!
+//! If you just want to load some images, see [`egui_extras`](https://crates.io/crates/egui_extras/),
+//! which contains reasonable default implementations of these traits. You can get started quickly
+//! using [`egui_extras::loaders::install`](https://docs.rs/egui_extras/latest/egui_extras/loaders/fn.install.html).
+//!
+//! ## Loading process
+//!
+//! There are three kinds of loaders:
+//! - [`BytesLoader`]: load the raw bytes of an image
+//! - [`ImageLoader`]: decode the bytes into an array of colors
+//! - [`TextureLoader`]: ask the backend to put an image onto the GPU
+//!
+//! The different kinds of loaders represent different layers in the loading process:
+//!
+//! ```text,ignore
+//! ui.image2("file://image.png")
+//! └► ctx.try_load_texture("file://image.png", ...)
+//! └► TextureLoader::load("file://image.png", ...)
+//!    └► ctx.try_load_image("file://image.png", ...)
+//!    └► ImageLoader::load("file://image.png", ...)
+//!       └► ctx.try_load_bytes("file://image.png", ...)
+//!       └► BytesLoader::load("file://image.png", ...)
+//! ```
+//!
+//! As each layer attempts to load the URI, it first asks the layer below it
+//! for the data it needs to do its job. But this is not a strict requirement,
+//! an implementation could instead generate the data it needs!
+//!
+//! Loader trait implementations may be registered on a context with:
+//! - [`Context::add_bytes_loader`]
+//! - [`Context::add_image_loader`]
+//! - [`Context::add_texture_loader`]
+//!
+//! There may be multiple loaders of the same kind registered at the same time.
+//! The `try_load` methods on [`Context`] will attempt to call each loader one by one,
+//! until one of them returns something other than [`LoadError::NotSupported`].
+//!
+//! The loaders are stored in the context. This means they may hold state across frames,
+//! which they can (and _should_) use to cache the results of the operations they perform.
+//!
+//! For example, a [`BytesLoader`] that loads file URIs (`file://image.png`)
+//! would cache each file read. A [`TextureLoader`] would cache each combination
+//! of `(URI, TextureOptions)`, and so on.
+//!
+//! Each URI will be passed through the loaders as a plain `&str`.
+//! The loaders are free to derive as much meaning from the URI as they wish to.
+//! For example, a loader may determine that it doesn't support loading a specific URI
+//! if the protocol does not match what it expects.
+
 use crate::Context;
 use ahash::HashMap;
 use epaint::mutex::Mutex;
+use epaint::TextureHandle;
 use epaint::{textures::TextureOptions, ColorImage, TextureId, Vec2};
 use std::{error::Error as StdError, fmt::Display, sync::Arc};
 
@@ -33,9 +84,10 @@ pub type Result<T, E = LoadError> = std::result::Result<T, E>;
 /// All variants will preserve the original aspect ratio.
 ///
 /// Similar to `usvg::FitTo`.
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Default, Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum SizeHint {
     /// Keep original size.
+    #[default]
     Original,
 
     /// Scale to width.
@@ -50,7 +102,7 @@ pub enum SizeHint {
 
 impl From<Vec2> for SizeHint {
     fn from(value: Vec2) -> Self {
-        Self::Size(value.x as u32, value.y as u32)
+        Self::Size(value.x.round() as u32, value.y.round() as u32)
     }
 }
 
@@ -84,6 +136,9 @@ pub trait BytesLoader {
     /// Implementations should call `ctx.request_repaint` to wake up the ui
     /// once the data is ready.
     ///
+    /// The implementation should cache any result, so that calling this
+    /// is immediate-mode safe.
+    ///
     /// # Errors
     /// This may fail with:
     /// - [`LoadError::NotSupported`] if the loader does not support loading `uri`.
@@ -126,6 +181,9 @@ pub trait ImageLoader {
     /// Implementations should call `ctx.request_repaint` to wake up the ui
     /// once the image is ready.
     ///
+    /// The implementation should cache any result, so that calling this
+    /// is immediate-mode safe.
+    ///
     /// # Errors
     /// This may fail with:
     /// - [`LoadError::NotSupported`] if the loader does not support loading `uri`.
@@ -155,6 +213,15 @@ pub struct SizedTexture {
     pub size: Size,
 }
 
+impl SizedTexture {
+    pub fn from_handle(handle: &TextureHandle) -> Self {
+        Self {
+            id: handle.id(),
+            size: handle.size(),
+        }
+    }
+}
+
 #[derive(Clone)]
 pub enum TexturePoll {
     /// Texture is loading.
@@ -175,6 +242,9 @@ pub trait TextureLoader {
     /// Implementations should call `ctx.request_repaint` to wake up the ui
     /// once the texture is ready.
     ///
+    /// The implementation should cache any result, so that calling this
+    /// is immediate-mode safe.
+    ///
     /// # Errors
     /// This may fail with:
     /// - [`LoadError::NotSupported`] if the loader does not support loading `uri`.
@@ -209,11 +279,8 @@ pub(crate) struct IncludeBytesLoader {
 }
 
 impl IncludeBytesLoader {
-    pub(crate) fn insert(&self, name: &'static str, bytes: &'static [u8]) {
-        self.cache
-            .lock()
-            .entry(name)
-            .or_insert_with(|| bytes.into());
+    pub(crate) fn insert(&self, uri: &'static str, bytes: &'static [u8]) {
+        self.cache.lock().entry(uri).or_insert_with(|| bytes.into());
     }
 }
 
@@ -234,7 +301,10 @@ impl BytesLoader for IncludeBytesLoader {
     }
 }
 
-struct DefaultTextureLoader;
+#[derive(Default)]
+struct DefaultTextureLoader {
+    cache: Mutex<HashMap<(String, TextureOptions), TextureHandle>>,
+}
 
 impl TextureLoader for DefaultTextureLoader {
     fn load(
@@ -244,15 +314,19 @@ impl TextureLoader for DefaultTextureLoader {
         texture_options: TextureOptions,
         size_hint: SizeHint,
     ) -> TextureLoadResult {
-        match ctx.try_load_image(uri, size_hint)? {
-            ImagePoll::Pending { size } => Ok(TexturePoll::Pending { size }),
-            ImagePoll::Ready { image } => {
-                let handle = ctx.load_texture(uri, image, texture_options);
-                let texture = SizedTexture {
-                    id: handle.id(),
-                    size: handle.size(),
-                };
-                Ok(TexturePoll::Ready { texture })
+        let mut cache = self.cache.lock();
+        if let Some(handle) = cache.get(&(uri.into(), texture_options)) {
+            let texture = SizedTexture::from_handle(handle);
+            Ok(TexturePoll::Ready { texture })
+        } else {
+            match ctx.try_load_image(uri, size_hint)? {
+                ImagePoll::Pending { size } => Ok(TexturePoll::Pending { size }),
+                ImagePoll::Ready { image } => {
+                    let handle = ctx.load_texture(uri, image, texture_options);
+                    let texture = SizedTexture::from_handle(&handle);
+                    cache.insert((uri.into(), texture_options), handle);
+                    Ok(TexturePoll::Ready { texture })
+                }
             }
         }
     }
@@ -284,7 +358,7 @@ impl Default for Loaders {
             bytes: vec![include.clone()],
             image: Vec::new(),
             // By default we only include `DefaultTextureLoader`.
-            texture: vec![Arc::new(DefaultTextureLoader)],
+            texture: vec![Arc::new(DefaultTextureLoader::default())],
             include,
         }
     }

crates/egui/src/ui.rs

@@ -1591,6 +1591,20 @@ impl Ui {
         Image::new(texture_id, size).ui(self)
     }
 
+    /// Show an image available at the given `uri`.
+    ///
+    /// ⚠ This will do nothing unless you install some image loaders first!
+    /// The easiest way to do this is via [`egui_extras::loaders::install`](https://docs.rs/egui_extras/latest/egui_extras/loaders/fn.install.html).
+    ///
+    /// The loaders handle caching image data, sampled textures, etc. across frames, so calling this is immediate-mode safe.
+    ///
+    /// ```
+    /// # egui::__run_test_ui(|ui| {
+    /// ui.image2("file://ferris.svg");
+    /// # });
+    /// ```
+    ///
+    /// See also [`crate::Image2`] and [`crate::ImageSource`].
     #[inline]
     pub fn image2<'a>(&mut self, source: impl Into<ImageSource<'a>>) -> Response {
         Image2::new(source.into()).ui(self)