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:
- Split on a worker thread:
PreparedTiles::from_rgbacrops the image intoArc<ColorImage>tiles usingPORTABLE_TILE_SIDE(worker threads have noegui::Contextto ask for the real limit). - Upload on the GUI thread:
TiledTexture::uploadturns pending tiles into egui textures, only as many per frame as anUploadBudgetallows, optionally only the ones on screen (UploadScope::visible). Uploading a prepared tile is a reference bump, not a pixel copy. - Paint:
TiledTexture::paintdraws the visible tiles through aPlacement(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
- Tile side and the backend limit.
max_texture_sidereads the running backend’s limit;TileGrid::for_context/tile_side_forcap a preferred side to it. A tile larger than the limit is rejected byuploadwith a log line (egui itself would onlydebug_assert!). - No gutters. Each tile is its own texture sampled with clamp-to-edge, so under linear magnification the pixels along a tile seam blend with themselves, not with the neighbouring tile. Changing the tile side moves the seams; keep it fixed if pixel-exact output matters.
- Dirty tiles.
TiledTexture::mark_dirtymarks the tiles under a pixel rect; the nextuploadre-sends them in place (TextureHandle::set, theTextureIdis kept), and the old pixels keep drawing meanwhile.TiledTexture::set_options(e.g.NEARESTwhen zoomed in) works the same way. - Memory.
TiledTexture::resident_bytes,TiledTexture::drop_texturesandTiledTexture::last_painted_frame(stamped bypaint, or byTiledTexture::mark_paintedafter a custom draw) are the hooks for your own eviction policy; the crate has none. After a drop, theTileSourcemust be able to supply the pixels again. - Repaints.
UploadReport::wants_repaintis true while the budget deferred tiles to a later frame. Tiles waiting for their source (TileContent::NotReady) are not a reason to repaint: whoever makes the pixels ready requests the repaint. - Threading. Everything in
TileGrid,Placement, the crop functions andPreparedTilesis plain data and runs anywhere.TiledTexturemethods that take aContextorPainterrun on the GUI thread, and so does aTileSource.
Structs§
- Paint
Report - What one
TiledTexture::paintcall did. - Placement
- How image pixels map to screen points. Opaque so new mappings can be added without a breaking change.
- Prepared
Tiles - Every tile of one image, split on the CPU and ready for upload.
- PxRect
- An axis-aligned rectangle in image pixels:
x..x + widthbyy..y + height(max exclusive). - Tile
Grid - The row-major grid of square tiles (edge tiles shorter) that covers an image.
- Tiled
Texture - A large image as a grid of egui textures.
- Upload
Budget - Per-frame upload allowance in tiles and bytes.
- Upload
Report - What one
TiledTexture::uploadcall did. - Visible
Scope - The visible-tiles upload scope: tiles whose screen rect (under
placement) intersectscull— the same testTiledTexture::paintuses, so what is painted is what gets uploaded.
Enums§
- Alpha
- How the alpha channel of raw RGBA8 input is encoded.
- Grid
Error - Why a
TileGridcould not be built. - Split
Error - Why a crop or split failed.
- Tile
Content - A source’s answer for one tile.
- Upload
Scope - Which tiles an
TiledTexture::uploadcall considers.
Constants§
- MAX_
TILES - The most tiles a
TiledTextureorPreparedTilesaccepts (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 asGridError::TooManyTilesinstead 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 noegui::Contextis available, e.g. on worker threads.
Traits§
- Tile
Source - Supplies tile pixels to
crate::TiledTexture::upload.
Functions§
- crop_
color_ image - Crops
rectout of aColorImage(pixels are copied as they are; no alpha conversion). - crop_
rgba - Crops
rectout of a raw RGBA8 image (image_size=[width, height], rows top to bottom, no padding) into aColorImage. - max_
texture_ side - The running backend’s maximum texture side in pixels, as reported to
ctx(egui’sInputState::max_texture_side; 2048 before the backend’s first frame). - tile_
side_ for preferredcapped at the backend’s maximum texture side, and at least 1.