Skip to main content

Crate egui_large_image

Crate egui_large_image 

Source
Expand description

Draw images larger than the GPU texture limit in egui.

egui uploads every texture in one piece, and a backend accepts only textures up to max_texture_side pixels per side (2048 is the portable minimum; desktop GPUs usually allow 8192-16384). A long webtoon page, a scan or a map does not fit. This crate splits such an image into a grid of tiles and treats the grid as one image:

  1. Split on a worker thread: PreparedTiles::from_rgba crops the image into Arc<ColorImage> tiles using PORTABLE_TILE_SIDE (worker threads have no egui::Context to ask for the real limit).
  2. Upload on the GUI thread: TiledTexture::upload turns pending tiles into egui textures, only as many per frame as an UploadBudget allows, optionally only the ones on screen (UploadScope::visible). Uploading a prepared tile is a reference bump, not a pixel copy.
  3. Paint: TiledTexture::paint draws the visible tiles through a Placement (pixel to screen mapping), culled against a screen rect.
use egui_large_image::{Alpha, Placement, PreparedTiles, TiledTexture, UploadBudget, UploadScope, PORTABLE_TILE_SIDE};

// On a worker thread (the pixels are an RGBA8 buffer, e.g. `image::RgbaImage::as_raw()`):
let prepared = PreparedTiles::from_rgba(rgba, [width, height], Alpha::Unmultiplied, PORTABLE_TILE_SIDE)?;

// On the GUI thread, every frame:
let placement = Placement::scaled(ui.min_rect().min, zoom);
let cull = ui.clip_rect();
let mut budget = UploadBudget::new(4, 24 * 1024 * 1024);
let report = texture.upload(ui.ctx(), prepared, &mut budget, UploadScope::visible(placement, cull));
texture.paint(ui.painter(), placement, cull, egui::Color32::WHITE);
if report.wants_repaint() {
    ui.ctx().request_repaint(); // the budget left tiles for the next frame
}
// Once, when the prepared tiles arrive:
let texture = TiledTexture::new(*prepared.grid(), "my-page", egui::TextureOptions::LINEAR)?;

§Details worth knowing

Structs§

PaintReport
What one TiledTexture::paint call did.
Placement
How image pixels map to screen points. Opaque so new mappings can be added without a breaking change.
PreparedTiles
Every tile of one image, split on the CPU and ready for upload.
PxRect
An axis-aligned rectangle in image pixels: x..x + width by y..y + height (max exclusive).
TileGrid
The row-major grid of square tiles (edge tiles shorter) that covers an image.
TiledTexture
A large image as a grid of egui textures.
UploadBudget
Per-frame upload allowance in tiles and bytes.
UploadReport
What one TiledTexture::upload call did.
VisibleScope
The visible-tiles upload scope: tiles whose screen rect (under placement) intersects cull — the same test TiledTexture::paint uses, so what is painted is what gets uploaded.

Enums§

Alpha
How the alpha channel of raw RGBA8 input is encoded.
GridError
Why a TileGrid could not be built.
SplitError
Why a crop or split failed.
TileContent
A source’s answer for one tile.
UploadScope
Which tiles an TiledTexture::upload call considers.

Constants§

MAX_TILES
The most tiles a TiledTexture or PreparedTiles accepts (2^20). Both allocate one entry per tile up front; a tile side far too small for the image (say 1 px on a 100 000 x 100 000 image) is reported as GridError::TooManyTiles instead of exhausting memory. Real grids stay far below it (an 8192 x 65 536 page at 256-px tiles is 8192 tiles).
PORTABLE_TILE_SIDE
A tile side every egui backend accepts (egui’s own default max_texture_side, the WebGL2 / GL ES 3 minimum). Use it where no egui::Context is available, e.g. on worker threads.

Traits§

TileSource
Supplies tile pixels to crate::TiledTexture::upload.

Functions§

crop_color_image
Crops rect out of a ColorImage (pixels are copied as they are; no alpha conversion).
crop_rgba
Crops rect out of a raw RGBA8 image (image_size = [width, height], rows top to bottom, no padding) into a ColorImage.
max_texture_side
The running backend’s maximum texture side in pixels, as reported to ctx (egui’s InputState::max_texture_side; 2048 before the backend’s first frame).
tile_side_for
preferred capped at the backend’s maximum texture side, and at least 1.