zgui

Images

Load raster images from files or memory, size and fit them with CSS, label them for screen readers, and understand decoding and caching.

The image element draws encoded raster data in its content box. The standard app supports PNG, JPEG, WebP, and GIF. A GIF draws its first frame.

Load a file

Set src to a file-system path:

use zgui::prelude::*;

view! {
    image(
        class = "avatar",
        src = "assets/avatar.webp",
        a11y:label = "Ada Lovelace",
    )
}
.avatar {
    width: 96px;
    height: 96px;
    border-radius: 50%;
    overflow: hidden;
}

src is a local path, not an HTTP URL. zgui first reads only the file header to learn the natural size. After layout, it decodes the pixels off the UI thread at the size the element needs, and the frame updates when the decode finishes. Layout can therefore use the natural size before the pixels are ready.

src can be reactive:

image(src = move || selected_path.get())

Changing or removing src detaches the old content. A source that fails to load stays blank, logs a warning with the zgui::images tracing target, and is not retried every frame.

Load bytes from memory

Use zgui_image::ImageBytes when the image has no file path. Add the crate:

Cargo.toml
[dependencies]
zgui = "0.1"
zgui-image = "0.1"
let picture = zgui_image::ImageBytes::new(include_bytes!("avatar.png"));
let src = picture.url();

let view = image(src = src);

The URL is a registry key. Keep picture alive while an element may need it: dropping the last ImageBytes clone unregisters the bytes, and later decodes of that URL fail.

Size and fit

The natural size is the source's pixel size, in CSS pixels. A 640 by 480 file is 640 by 480 CSS pixels with a 4:3 ratio, regardless of the window scale factor or the resolution zgui decodes. CSS can override it:

.preview { width: 100%; aspect-ratio: 16 / 9; }

Until the header has been read, the image has no natural size. Give it an explicit size if a late layout change is not acceptable.

object-fit controls how the picture fills the content box. The initial value is fill.

.avatar  { width: 96px; height: 96px; object-fit: cover; }
.preview { width: 480px; height: 320px; object-fit: contain; }
.stamp   { width: 160px; height: 120px; object-fit: none; object-position: 100% 0%; }
ValueResult
fillStretches the picture to the box. The ratio can change.
containKeeps the ratio and fits the whole picture inside the box.
coverKeeps the ratio and fills the box. The excess is clipped.
noneDraws at the natural size. The box can clip it.
scale-downThe smaller of none and contain.

object-position places the fitted picture in the remaining space. It accepts percentages and lengths; the initial value is 50% 50%. Rounded corners and the content box clip the picture, and a contain letterbox shows the element's background.

Describe an image for screen readers

The accessibility tree does not read alt. Set a11y:label on a meaningful image, as the avatar example above does, and a11y:hidden = true on a decorative one:

image(class = "divider", src = "assets/flourish.png", a11y:hidden = true)

Decoding and caching

zgui decodes for the device-pixel size of the laid-out box, so a thumbnail does not hold the full source in memory. The fit matters: fill, contain, and scale-down need no more than the box, cover includes the clipped overflow, and none decodes at the source size times the display scale.

The decoded size is rounded up to a long edge of 64, 128, 256, 512, 1024, or 2048 device pixels, so a one-pixel layout change does not start another decode. Larger demands use the source size, up to the GPU's texture limit. zgui never upscales past the source.

The src string identifies an image. Elements with the same source share decoded variants and textures. A larger use adds a larger variant; while it decodes, zgui draws the best smaller one.

Variants up to 512 pixels on the long edge share atlas textures. Larger ones get their own texture with mipmaps for smooth minification. After upload, zgui frees the decoded pixels unless they are 64 KiB or smaller; if a texture is later evicted or the device is lost, the variant is decoded again.

Under memory pressure, zgui drops unused variants before used ones and the least recently used sources first. The natural size is kept, so eviction does not change layout.

Calling zgui_image::decode or decode_scaled directly takes a Limits value whose default maximum dimension is 2048 pixels. Decoded texels are premultiplied, sRGB-encoded RGBA, tightly packed, top row first.

Next

On this page