Module egui::load

Image loading

If you just want to display some images, egui_extras will get you up and running quickly with its reasonable default implementations of the traits described below.

1. Add egui_extras as a dependency with the all_loaders feature.
2. Add a call to egui_extras::install_image_loaders in your app’s setup code.
3. Use Ui::image with some ImageSource.

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:

ui.image("file://image.png")
└► Context::try_load_texture
└► TextureLoader::load
   └► Context::try_load_image
   └► ImageLoader::load
      └► Context::try_load_bytes
      └► BytesLoader::load

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.

Macros

• generate_loader_id
  Used to get a unique ID when implementing one of the loader traits: BytesLoader::id, ImageLoader::id, and TextureLoader::id.

Structs

• DefaultBytesLoader
  Maps URI:s to Bytes, e.g. found with include_bytes!.
• DefaultTextureLoader
• Loaders
  The loaders of bytes, images, and textures.
• SizedTexture
  A texture with a known size.

Enums

• Bytes
  Represents a byte buffer.
• BytesPoll
  Represents bytes which are currently being loaded.
• ImagePoll
  Represents an image which is currently being loaded.
• LoadError
  Represents a failed attempt at loading an image.
• SizeHint
  Given as a hint for image loading requests.
• TexturePoll
  Represents a texture is currently being loaded.

Traits

• BytesLoader
  Represents a loader capable of loading raw unstructured bytes from somewhere, e.g. from disk or network.
• ImageLoader
  An ImageLoader decodes raw bytes into a ColorImage.
• TextureLoader
  A TextureLoader uploads a ColorImage to the GPU, returning a SizedTexture.

Type Aliases

• BytesLoadResult
• ImageLoadResult
• Result
• TextureLoadResult