Struct IMAGES

pub struct IMAGES;

Image loading, cache and render service.

If the app is running without a VIEW_PROCESS all images are dummy, see load_in_headless for details.

Implementations

impl IMAGES

pub fn render<N, R>(&self, mask: Option<ImageMaskMode>, render: N) -> ImageVar

where N: FnOnce() -> R + Send + Sync + 'static, R: ImageRenderWindowRoot,

Render the window generated by render to an image.

The window is created as a headless surface and rendered to the returned image. You can use the IMAGE_RENDER.retain var create an image that updates with new frames, or by default only render once.

The closure runs in the WINDOW context of the headless window.

pub fn render_node<U, N>( &self, render_mode: RenderMode, scale_factor: impl Into<Factor>, mask: Option<ImageMaskMode>, render: N, ) -> ImageVar

where U: UiNode, N: FnOnce() -> U + Send + Sync + 'static,

Render an UiNode to an image.

This method is a shortcut to render a node without needing to declare the headless window, note that a headless window is still used, the node does not have the same context as the calling widget.

impl IMAGES

pub fn load_in_headless(&self) -> ArcVar<bool>

If should still download/read image bytes in headless/renderless mode.

When an app is in headless mode without renderer no VIEW_PROCESS is available, so images cannot be decoded, in this case all images are the dummy image and no attempt to download/read the image files is made. You can enable loading in headless tests to detect IO errors, in this case if there is an error acquiring the image file the image will be a dummy with error.

pub fn limits(&self) -> ArcVar<ImageLimits>

Default loading and decoding limits for each image.

pub fn dummy(&self, error: Option<Txt>) -> ImageVar

Returns a dummy image that reports it is loaded or an error.

pub fn read(&self, path: impl Into<PathBuf>) -> ImageVar

Cache or load an image file from a file system path.

pub fn download(&self, uri: impl TryUri, accept: Option<Txt>) -> ImageVar

Get a cached uri or download it.

Optionally define the HTTP ACCEPT header, if not set all image formats supported by the view-process backend are accepted.

pub fn from_static( &self, data: &'static [u8], format: impl Into<ImageDataFormat>, ) -> ImageVar

Get a cached image from &'static [u8] data.

The data can be any of the formats described in ImageDataFormat.

The image key is a ImageHash of the image data.

Examples

Get an image from a PNG file embedded in the app executable using include_bytes!.

let image_var = IMAGES.from_static(include_bytes!("ico.png"), "png");

pub fn from_data( &self, data: Arc<Vec<u8>>, format: impl Into<ImageDataFormat>, ) -> ImageVar

Get a cached image from shared data.

The image key is a ImageHash of the image data. The data reference is held only until the image is decoded.

The data can be any of the formats described in ImageDataFormat.

pub fn cache(&self, source: impl Into<ImageSource>) -> ImageVar

Get a cached image or add it to the cache.

pub fn retry(&self, source: impl Into<ImageSource>) -> ImageVar

Get a cached image or add it to the cache or retry if the cached image is an error.

pub fn reload(&self, source: impl Into<ImageSource>) -> ImageVar

Load an image, if it was already cached update the cached image with the reloaded data.

pub fn image( &self, source: impl Into<ImageSource>, cache_mode: impl Into<ImageCacheMode>, limits: Option<ImageLimits>, downscale: Option<ImageDownscale>, mask: Option<ImageMaskMode>, ) -> ImageVar

Get or load an image.

If limits is None the IMAGES.limits is used.

pub fn image_task<F>( &self, source: impl IntoFuture<IntoFuture = F>, cache_mode: impl Into<ImageCacheMode>, cache_key: Option<ImageHash>, limits: Option<ImageLimits>, downscale: Option<ImageDownscale>, mask: Option<ImageMaskMode>, ) -> ImageVar

where F: Future<Output = ImageSource> + Send + 'static,

Await for an image source, then get or load the image.

If limits is None the IMAGES.limits is used.

This method returns immediately with a loading ImageVar, when source is ready it is used to get the actual ImageVar and binds it to the returned image.

Note that the cache_mode always applies to the inner image, and only to the return image if cache_key is set.

pub fn register( &self, key: ImageHash, image: ViewImage, ) -> Result<ImageVar, (ViewImage, ImageVar)>

Associate the image with the key in the cache.

Returns Ok(ImageVar) with the new image var that tracks image, or Err(ViewImage, ImageVar) that returns the image and a clone of the var already associated with the key.

pub fn clean(&self, key: ImageHash) -> bool

Remove the image from the cache, if it is only held by the cache.

You can use ImageSource::hash128_read and ImageSource::hash128_download to get the key for files or downloads.

Returns true if the image was removed.

pub fn purge(&self, key: &ImageHash) -> bool

Remove the image from the cache, even if it is still referenced outside of the cache.

You can use ImageSource::hash128_read and ImageSource::hash128_download to get the key for files or downloads.

Returns true if the image was cached.

pub fn cache_key(&self, image: &Img) -> Option<ImageHash>

Gets the cache key of an image.

pub fn is_cached(&self, image: &Img) -> bool

If the image is cached.

pub fn detach(&self, image: ImageVar) -> ImageVar

Returns an image that is not cached.

If the image is the only reference returns it and removes it from the cache. If there are other references a new ImageVar is generated from a clone of the image.

pub fn clean_all(&self)

Clear cached images that are not referenced outside of the cache.

pub fn purge_all(&self)

Clear all cached images, including images that are still referenced outside of the cache.

Image memory only drops when all strong references are removed, so if an image is referenced outside of the cache it will merely be disconnected from the cache by this method.

pub fn install_proxy(&self, proxy: Box<dyn ImageCacheProxy>)

Add a cache proxy.

Proxies can intercept cache requests and map to a different request or return an image directly.

pub fn available_decoders(&self) -> Vec<Txt>

Image format decoders implemented by the current view-process.

pub fn available_encoders(&self) -> Vec<Txt>

Image format encoders implemented by the current view-process.