Module 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