egui_extras/
loaders.rs

Help
1// TODO(jprochazk): automatic cache eviction
2
3/// Installs a set of image loaders.
4///
5/// Calling this enables the use of [`egui::Image`] and [`egui::Ui::image`].
6///
7/// ⚠ This will do nothing and you won't see any images unless you also enable some feature flags on `egui_extras`:
8///
9/// - `file` feature: `file://` loader on non-Wasm targets
10/// - `http` feature: `http(s)://` loader
11/// - `image` feature: Loader of png, jpeg etc using the [`image`] crate
12/// - `svg` feature: `.svg` loader
13///
14/// Calling this multiple times on the same [`egui::Context`] is safe.
15/// It will never install duplicate loaders.
16///
17/// - If you just want to be able to load `file://` and `http://` URIs, enable the `all_loaders` feature.
18/// - The supported set of image formats is configured by adding the [`image`](https://crates.io/crates/image)
19///   crate as your direct dependency, and enabling features on it:
20///
21/// ```toml,ignore
22/// egui_extras = { version = "*", features = ["all_loaders"] }
23/// image = { version = "0.25", features = ["jpeg", "png"] } # Add the types you want support for
24/// ```
25///
26/// ⚠ You have to configure both the supported loaders in `egui_extras` _and_ the supported image formats
27/// in `image` to get any output!
28///
29/// ## Loader-specific information
30///
31/// ⚠ The exact way bytes, images, and textures are loaded is subject to change,
32/// but the supported protocols and file extensions are not.
33///
34/// The `file` loader is a [`BytesLoader`][`egui::load::BytesLoader`].
35/// It will attempt to load `file://` URIs, and infer the content type from the extension.
36/// The path will be passed to [`std::fs::read`] after trimming the `file://` prefix,
37/// and is resolved the same way as with `std::fs::read(path)`:
38/// - Relative paths are relative to the current working directory
39/// - Absolute paths are left as is.
40///
41/// The `http` loader is a [`BytesLoader`][`egui::load::BytesLoader`].
42/// It will attempt to load `http://` and `https://` URIs, and infer the content type from the `Content-Type` header.
43///
44/// The `image` loader is an [`ImageLoader`][`egui::load::ImageLoader`].
45/// It will attempt to load any URI with any extension other than `svg`.
46/// It will also try to load any URI without an extension.
47/// The content type specified by [`BytesPoll::Ready::mime`][`egui::load::BytesPoll::Ready::mime`] always takes precedence.
48/// This means that even if the URI has a `png` extension, and the `png` image format is enabled, if the content type is
49/// not one of the supported and enabled image formats, the loader will return [`LoadError::NotSupported`][`egui::load::LoadError::NotSupported`],
50/// allowing a different loader to attempt to load the image.
51///
52/// The `svg` loader is an [`ImageLoader`][`egui::load::ImageLoader`].
53/// It will attempt to load any URI with an `svg` extension. It will _not_ attempt to load a URI without an extension.
54/// The content type specified by [`BytesPoll::Ready::mime`][`egui::load::BytesPoll::Ready::mime`] always takes precedence,
55/// and must include `svg` for it to be considered supported. For example, `image/svg+xml` would be loaded by the `svg` loader.
56///
57/// See [`egui::load`] for more information about how loaders work.
58pub fn install_image_loaders(ctx: &egui::Context) {
59    #[cfg(all(not(target_arch = "wasm32"), feature = "file"))]
60    if !ctx.is_loader_installed(self::file_loader::FileLoader::ID) {
61        ctx.add_bytes_loader(std::sync::Arc::new(self::file_loader::FileLoader::default()));
62        log::trace!("installed FileLoader");
63    }
64
65    #[cfg(feature = "http")]
66    if !ctx.is_loader_installed(self::ehttp_loader::EhttpLoader::ID) {
67        ctx.add_bytes_loader(std::sync::Arc::new(
68            self::ehttp_loader::EhttpLoader::default(),
69        ));
70        log::trace!("installed EhttpLoader");
71    }
72
73    #[cfg(feature = "image")]
74    if !ctx.is_loader_installed(self::image_loader::ImageCrateLoader::ID) {
75        ctx.add_image_loader(std::sync::Arc::new(
76            self::image_loader::ImageCrateLoader::default(),
77        ));
78        log::trace!("installed ImageCrateLoader");
79    }
80
81    #[cfg(feature = "gif")]
82    if !ctx.is_loader_installed(self::gif_loader::GifLoader::ID) {
83        ctx.add_image_loader(std::sync::Arc::new(self::gif_loader::GifLoader::default()));
84        log::trace!("installed GifLoader");
85    }
86
87    #[cfg(feature = "svg")]
88    if !ctx.is_loader_installed(self::svg_loader::SvgLoader::ID) {
89        ctx.add_image_loader(std::sync::Arc::new(self::svg_loader::SvgLoader::default()));
90        log::trace!("installed SvgLoader");
91    }
92
93    #[cfg(all(
94        any(target_arch = "wasm32", not(feature = "file")),
95        not(feature = "http"),
96        not(feature = "image"),
97        not(feature = "svg")
98    ))]
99    log::warn!("`install_image_loaders` was called, but no loaders are enabled");
100
101    let _ = ctx;
102}
103
104#[cfg(not(target_arch = "wasm32"))]
105mod file_loader;
106
107#[cfg(feature = "http")]
108mod ehttp_loader;
109
110#[cfg(feature = "gif")]
111mod gif_loader;
112#[cfg(feature = "image")]
113mod image_loader;
114#[cfg(feature = "svg")]
115mod svg_loader;
egui_extras/loaders.rs

egui_extras/
loaders.rs
