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:
[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%; }| Value | Result |
|---|---|
fill | Stretches the picture to the box. The ratio can change. |
contain | Keeps the ratio and fits the whole picture inside the box. |
cover | Keeps the ratio and fills the box. The excess is clipped. |
none | Draws at the natural size. The box can clip it. |
scale-down | The 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
Images and drawing
Choose between decoded images, declarative vectors, imperative canvases, GPU surfaces, custom elements, and shader effects.
Vector and canvas
Draw icons and SVG documents with vector, draw shapes from Rust with canvas, pan and zoom with a view transform, plot data series, and keep drawings fast.