Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

gui: draw big images from dedicated textures instead of the glyph atlas

RoversX6a1383fa58ea
diff --git a/wezterm-gui/src/glyphcache.rs b/wezterm-gui/src/glyphcache.rs
index b8ec75d6..bb531fc3 100644
--- a/wezterm-gui/src/glyphcache.rs
+++ b/wezterm-gui/src/glyphcache.rs
@@ -593,18 +593,21 @@ pub struct ImageAllocRecord {
/// A one-shot streaming frame (nonce key): never requested again
/// under the same key, so each one is fresh atlas area.
pub nonce: bool,
+ /// Uploaded into its own texture rather than packed into the atlas.
+ pub dedicated: bool,
pub at: Instant,
}
impl ImageAllocRecord {
pub fn describe(&self, now: Instant) -> String {
format!(
- "{}x{}{}{}{} {}s",
+ "{}x{}{}{}{}{} {}s",
self.width,
self.height,
self.scale.map(|s| format!("/s{s}")).unwrap_or_default(),
if self.animated { " anim" } else { "" },
if self.nonce { " nonce" } else { "" },
+ if self.dedicated { " tex" } else { " atlas" },
now.saturating_duration_since(self.at).as_secs(),
)
}
@@ -1034,6 +1037,24 @@ impl GlyphCache {
scale,
animated,
nonce,
+ dedicated: false,
+ at: Instant::now(),
+ });
+ }
+
+ /// Record a picture uploaded into a dedicated texture (it never touches
+ /// the atlas), so the memory report shows which path each upload took.
+ pub(crate) fn note_dedicated_image(&mut self, width: u32, height: u32, nonce: bool) {
+ if self.image_alloc_log.len() >= IMAGE_ALLOC_LOG_LEN {
+ self.image_alloc_log.pop_front();
+ }
+ self.image_alloc_log.push_back(ImageAllocRecord {
+ width: width as usize,
+ height: height as usize,
+ scale: None,
+ animated: false,
+ nonce,
+ dedicated: true,
at: Instant::now(),
});
}
diff --git a/wezterm-gui/src/renderstate.rs b/wezterm-gui/src/renderstate.rs
index ec1385e6..b3c33421 100644
--- a/wezterm-gui/src/renderstate.rs
+++ b/wezterm-gui/src/renderstate.rs
@@ -13,6 +13,7 @@ use ::window::glium::{
use ::window::*;
use anyhow::Context;
use std::cell::{Cell, Ref, RefCell, RefMut};
+use std::collections::HashMap;
use std::convert::TryInto;
use std::rc::Rc;
use wezterm_font::FontConfiguration;
@@ -745,6 +746,225 @@ pub struct RenderState {
pub util_sprites: UtilSprites,
pub glyph_prog: Option<glium::Program>,
pub layers: RefCell<Vec<Rc<RenderLayer>>>,
+ /// Large images drawn from their own textures instead of the atlas
+ /// (WebGpu only; glium keeps packing everything into the atlas). Lives
+ /// here rather than in the glyph cache so an atlas recreation does not
+ /// throw the textures away.
+ pub dedicated_images: RefCell<DedicatedImageCache<crate::termwindow::webgpu::ImageTexture>>,
+}
+
+/// Images at or above this many RGBA bytes bypass the glyph atlas for a
+/// dedicated texture. Absolute rather than relative to the atlas: the atlas
+/// settles near 512 at startup, where a fraction of its area would send
+/// ordinary small pictures off-atlas too, and a threshold that moved with
+/// the atlas would flip the same picture between paths (and samplers) as
+/// the atlas grew.
+pub const DEDICATED_IMAGE_MIN_BYTES: usize = 1024 * 1024;
+
+/// Resident budget for dedicated image textures, live and pooled together,
+/// across all sizes -- a per-size pool has no bound on the number of sizes
+/// a drag-resize mints. Two 1632x1026 streams need about 27MiB: two live
+/// frames and two spares.
+pub const DEDICATED_IMAGE_BUDGET_BYTES: usize = 32 * 1024 * 1024;
+
+/// Whether an image can be drawn from a dedicated texture at all. Two
+/// gates: the GPU's per-side texture limit (queried from the adapter --
+/// 16384 on Apple GPUs -- because a 20000x1 kitty image is valid yet
+/// cannot be one texture), and the cache's own byte budget (an 8000x6000
+/// photo is 192MiB as one texture; while displayed it could never be
+/// evicted, so the budget would mean nothing). Either way the picture
+/// takes the atlas path, which knows how to downscale; failing the paint
+/// instead would keep the previous frame on screen for as long as the
+/// picture is placed.
+pub fn image_fits_dedicated_texture(width: u32, height: u32, max_side: u32) -> bool {
+ let bytes = width as usize * height as usize * 4;
+ width > 0
+ && height > 0
+ && width <= max_side
+ && height <= max_side
+ && bytes <= DEDICATED_IMAGE_BUDGET_BYTES
+}
+
+/// Whether an image should be drawn from a dedicated texture. Besides the
+/// size threshold, anything the atlas could never place -- a side longer
+/// than the atlas once its padding is added -- goes dedicated too, since
+/// packing it would only drive atlas growth. Callers gate this on
+/// `image_fits_dedicated_texture` first.
+pub fn image_wants_dedicated_texture(
+ width: u32,
+ height: u32,
+ padding: usize,
+ atlas_side: usize,
+) -> bool {
+ let bytes = width as usize * height as usize * 4;
+ // Atlas::allocate_with_padding reserves the caller's padding plus one
+ // texel of its own on each side.
+ let reserve = |dim: u32| dim as usize + padding + 2;
+ bytes >= DEDICATED_IMAGE_MIN_BYTES
+ || reserve(width) > atlas_side
+ || reserve(height) > atlas_side
+}
+
+/// What the cache needs to know about a texture; abstract so the eviction
+/// policy can be tested without a GPU.
+pub trait DedicatedTexture {
+ fn width(&self) -> u32;
+ fn height(&self) -> u32;
+ fn byte_size(&self) -> usize {
+ self.width() as usize * self.height() as usize * 4
+ }
+}
+
+impl DedicatedTexture for crate::termwindow::webgpu::ImageTexture {
+ fn width(&self) -> u32 {
+ self.width
+ }
+ fn height(&self) -> u32 {
+ self.height
+ }
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct DedicatedImageStats {
+ pub live: usize,
+ pub pooled: usize,
+ pub bytes: usize,
+}
+
+struct DedicatedImageEntry<T> {
+ texture: Rc<T>,
+ last_used: u64,
+}
+
+/// Dedicated textures keyed by image hash, with spares pooled by size so a
+/// stream of same-sized frames reuses one texture per frame instead of
+/// allocating. Bounded by a single byte budget across all sizes.
+pub struct DedicatedImageCache<T> {
+ entries: HashMap<[u8; 32], DedicatedImageEntry<T>>,
+ /// Retired textures, oldest first.
+ pool: Vec<Rc<T>>,
+ /// Advanced once per presented frame by `end_frame`, so the retry
+ /// passes of one frame all see the same value and a second pass hits
+ /// the entry the first pass uploaded.
+ frame: u64,
+ budget: usize,
+}
+
+impl<T: DedicatedTexture> DedicatedImageCache<T> {
+ pub fn new(budget: usize) -> Self {
+ Self {
+ entries: HashMap::new(),
+ pool: Vec::new(),
+ frame: 0,
+ budget,
+ }
+ }
+
+ /// The texture holding `hash`, uploading it via `upload` into a pooled
+ /// or freshly `create`d texture on a miss.
+ pub fn get_or_upload(
+ &mut self,
+ hash: [u8; 32],
+ width: u32,
+ height: u32,
+ create: impl FnOnce() -> anyhow::Result<T>,
+ upload: impl FnOnce(&T),
+ ) -> anyhow::Result<Rc<T>> {
+ if let Some(entry) = self.entries.get_mut(&hash) {
+ entry.last_used = self.frame;
+ return Ok(Rc::clone(&entry.texture));
+ }
+ let texture = match self
+ .pool
+ .iter()
+ .position(|t| t.width() == width && t.height() == height)
+ {
+ Some(idx) => self.pool.remove(idx),
+ None => Rc::new(create()?),
+ };
+ upload(&texture);
+ self.entries.insert(
+ hash,
+ DedicatedImageEntry {
+ texture: Rc::clone(&texture),
+ last_used: self.frame,
+ },
+ );
+ self.enforce_budget();
+ Ok(texture)
+ }
+
+ /// Call once per paint. Entries not drawn for two frames retire to
+ /// the pool; the budget is then re-applied.
+ pub fn end_frame(&mut self) {
+ // Budget first, while `frame` still marks what this paint drew:
+ // after the bump every entry looks idle, and an over-budget frame
+ // would destroy the very textures its composites are encoding,
+ // re-uploading them all next frame.
+ self.enforce_budget();
+ self.frame += 1;
+ let frame = self.frame;
+ let mut retired: Vec<(u64, Rc<T>)> = Vec::new();
+ self.entries.retain(|_, entry| {
+ if entry.last_used + 2 <= frame {
+ retired.push((entry.last_used, Rc::clone(&entry.texture)));
+ false
+ } else {
+ true
+ }
+ });
+ retired.sort_by_key(|(last_used, _)| *last_used);
+ self.pool.extend(retired.into_iter().map(|(_, t)| t));
+ // Spares only: the live set was already trimmed above, and what
+ // just retired may simply exceed the pool's share.
+ while self.resident_bytes() > self.budget && !self.pool.is_empty() {
+ self.pool.remove(0);
+ }
+ }
+
+ fn resident_bytes(&self) -> usize {
+ self.entries
+ .values()
+ .map(|e| e.texture.byte_size())
+ .chain(self.pool.iter().map(|t| t.byte_size()))
+ .sum()
+ }
+
+ /// Spares go first, oldest first; then the least recently drawn live
+ /// entries, never one drawn this frame (its composite is about to be
+ /// encoded).
+ fn enforce_budget(&mut self) {
+ while self.resident_bytes() > self.budget && !self.pool.is_empty() {
+ self.pool.remove(0);
+ }
+ while self.resident_bytes() > self.budget {
+ let victim = self
+ .entries
+ .iter()
+ .filter(|(_, e)| e.last_used < self.frame)
+ .min_by_key(|(_, e)| e.last_used)
+ .map(|(hash, _)| *hash);
+ match victim {
+ Some(hash) => {
+ self.entries.remove(&hash);
+ }
+ None => break,
+ }
+ }
+ }
+
+ pub fn clear(&mut self) {
+ self.entries.clear();
+ self.pool.clear();
+ }
+
+ pub fn stats(&self) -> DedicatedImageStats {
+ DedicatedImageStats {
+ live: self.entries.len(),
+ pooled: self.pool.len(),
+ bytes: self.resident_bytes(),
+ }
+ }
}
#[derive(Debug, Clone)]
@@ -766,6 +986,7 @@ pub struct RenderStateStats {
pub layers: usize,
pub layer_quads: usize,
pub vertex_buffers: usize,
+ pub dedicated_images: DedicatedImageStats,
}
impl RenderState {
@@ -795,6 +1016,9 @@ impl RenderState {
util_sprites,
glyph_prog,
layers: RefCell::new(vec![main_layer]),
+ dedicated_images: RefCell::new(DedicatedImageCache::new(
+ DEDICATED_IMAGE_BUDGET_BYTES,
+ )),
});
}
Err(OutOfTextureSpace {
@@ -973,6 +1197,7 @@ impl RenderState {
cursor_glyphs: glyph.cursor_glyphs,
color_sprites: glyph.color_sprites,
layers: layers.len(),
+ dedicated_images: self.dedicated_images.borrow().stats(),
layer_quads,
vertex_buffers: layers.len() * 3,
}
@@ -1056,3 +1281,167 @@ impl RenderState {
Ok(())
}
}
+
+#[cfg(test)]
+mod dedicated_image_tests {
+ use super::{
+ image_wants_dedicated_texture, DedicatedImageCache, DedicatedTexture,
+ DEDICATED_IMAGE_MIN_BYTES,
+ };
+ use std::cell::Cell;
+ use std::rc::Rc;
+
+ struct FakeTex(u32, u32);
+ impl DedicatedTexture for FakeTex {
+ fn width(&self) -> u32 {
+ self.0
+ }
+ fn height(&self) -> u32 {
+ self.1
+ }
+ }
+
+ fn hash(n: u8) -> [u8; 32] {
+ [n; 32]
+ }
+
+ // 512x512x4 = 1MiB per fake texture; a 3MiB budget holds three.
+ const SIDE: u32 = 512;
+ const MIB: usize = 1024 * 1024;
+
+ fn get(cache: &mut DedicatedImageCache<FakeTex>, n: u8, uploads: &Cell<usize>) -> Rc<FakeTex> {
+ cache
+ .get_or_upload(
+ hash(n),
+ SIDE,
+ SIDE,
+ || Ok(FakeTex(SIDE, SIDE)),
+ |_| uploads.set(uploads.get() + 1),
+ )
+ .unwrap()
+ }
+
+ #[test]
+ fn a_second_pass_in_the_same_frame_does_not_upload_again() {
+ let mut cache = DedicatedImageCache::new(3 * MIB);
+ let uploads = Cell::new(0);
+ let a = get(&mut cache, 1, &uploads);
+ let b = get(&mut cache, 1, &uploads);
+ assert!(Rc::ptr_eq(&a, &b));
+ assert_eq!(uploads.get(), 1);
+ }
+
+ #[test]
+ fn a_stream_reuses_one_pooled_texture_per_frame() {
+ let mut cache = DedicatedImageCache::new(3 * MIB);
+ let uploads = Cell::new(0);
+ let first = get(&mut cache, 1, &uploads);
+ cache.end_frame();
+ let second = get(&mut cache, 2, &uploads);
+ cache.end_frame();
+ // Frame 1 was last drawn two frames ago: retired to the pool.
+ assert_eq!(cache.stats().live, 1);
+ assert_eq!(cache.stats().pooled, 1);
+ let third = get(&mut cache, 3, &uploads);
+ // The retired texture is the one handed out, not a fresh one.
+ assert!(Rc::ptr_eq(&first, &third));
+ assert!(!Rc::ptr_eq(&second, &third));
+ assert_eq!(uploads.get(), 3);
+ assert_eq!(cache.stats().bytes, 2 * MIB);
+ }
+
+ #[test]
+ fn the_budget_drops_spares_first_then_the_least_recently_drawn() {
+ let mut cache = DedicatedImageCache::new(3 * MIB);
+ let uploads = Cell::new(0);
+ get(&mut cache, 1, &uploads);
+ cache.end_frame();
+ get(&mut cache, 2, &uploads);
+ cache.end_frame();
+ get(&mut cache, 3, &uploads);
+ cache.end_frame();
+ // Frame 3 took frame 1's retired texture, so only two textures
+ // exist: 3 live, 2's retired to the pool.
+ assert_eq!((cache.stats().live, cache.stats().pooled), (1, 1));
+ assert_eq!(cache.stats().bytes, 2 * MIB);
+
+ // A second live picture this frame takes the spare...
+ get(&mut cache, 4, &uploads);
+ assert_eq!((cache.stats().live, cache.stats().pooled), (2, 0));
+ // ...a third allocates, landing exactly on the budget...
+ get(&mut cache, 5, &uploads);
+ assert_eq!((cache.stats().live, cache.stats().pooled), (3, 0));
+ assert_eq!(cache.stats().bytes, 3 * MIB);
+ // ...and a fourth goes over: with no spares left, the least recently
+ // drawn live entry (3, drawn last frame) is evicted, never 4/5/6.
+ get(&mut cache, 6, &uploads);
+ assert_eq!(cache.stats().live, 3);
+ assert_eq!(cache.stats().bytes, 3 * MIB);
+ let before = uploads.get();
+ get(&mut cache, 4, &uploads);
+ get(&mut cache, 5, &uploads);
+ get(&mut cache, 6, &uploads);
+ assert_eq!(uploads.get(), before, "4/5/6 must still be resident");
+ get(&mut cache, 3, &uploads);
+ assert_eq!(uploads.get(), before + 1, "3 was evicted and re-uploads");
+ }
+
+ #[test]
+ fn entries_drawn_this_frame_are_never_evicted() {
+ let mut cache = DedicatedImageCache::new(MIB);
+ let uploads = Cell::new(0);
+ get(&mut cache, 1, &uploads);
+ get(&mut cache, 2, &uploads);
+ // Over budget, but both were drawn this frame: both stay.
+ assert_eq!(cache.stats().live, 2);
+ cache.end_frame();
+ cache.end_frame();
+ // Retired and trimmed back under budget.
+ assert!(cache.stats().bytes <= MIB);
+ }
+
+ #[test]
+ fn threshold_is_absolute_and_catches_unpackable_sides() {
+ assert!(image_wants_dedicated_texture(SIDE, SIDE, 16, 4096));
+ assert!(!image_wants_dedicated_texture(300, 300, 16, 4096));
+ assert_eq!(DEDICATED_IMAGE_MIN_BYTES, 512 * 512 * 4);
+ // Small in bytes but wider than the atlas once padded.
+ assert!(image_wants_dedicated_texture(500, 8, 16, 512));
+ assert!(!image_wants_dedicated_texture(490, 8, 16, 512));
+ }
+
+ #[test]
+ fn a_side_past_the_gpu_limit_cannot_be_dedicated() {
+ use super::image_fits_dedicated_texture;
+ assert!(image_fits_dedicated_texture(8192, 1, 8192));
+ assert!(!image_fits_dedicated_texture(8193, 1, 8192));
+ assert!(!image_fits_dedicated_texture(1, 20000, 8192));
+ assert!(!image_fits_dedicated_texture(0, 10, 8192));
+ }
+
+ #[test]
+ fn a_picture_bigger_than_the_whole_budget_cannot_be_dedicated() {
+ use super::{image_fits_dedicated_texture, DEDICATED_IMAGE_BUDGET_BYTES};
+ // 8000x6000 RGBA = 192MiB: six times the budget, unevictable while
+ // displayed. The atlas path downscales it instead.
+ assert!(!image_fits_dedicated_texture(8000, 6000, 16384));
+ let side = ((DEDICATED_IMAGE_BUDGET_BYTES / 4) as f64).sqrt() as u32;
+ assert!(image_fits_dedicated_texture(side, side, 16384));
+ }
+
+ #[test]
+ fn an_over_budget_frame_keeps_what_it_is_drawing() {
+ // Two live pictures against a one-picture budget: end_frame runs
+ // while their composites are still waiting to be encoded, so
+ // neither may be destroyed this frame. The next frame, with
+ // neither redrawn, trims back to the budget.
+ let mut cache = DedicatedImageCache::new(MIB);
+ let uploads = Cell::new(0);
+ get(&mut cache, 1, &uploads);
+ get(&mut cache, 2, &uploads);
+ cache.end_frame();
+ assert_eq!(cache.stats().live, 2, "hot textures survive the frame");
+ cache.end_frame();
+ assert!(cache.stats().bytes <= MIB, "idle textures trim next frame");
+ }
+}
diff --git a/wezterm-gui/src/settings_window.rs b/wezterm-gui/src/settings_window.rs
index 7e5ad4d1..26712e1a 100644
--- a/wezterm-gui/src/settings_window.rs
+++ b/wezterm-gui/src/settings_window.rs
@@ -4011,6 +4011,8 @@ impl SettingsWindow {
.render_state
.as_ref()
.context("settings render state not initialized")?;
+ // The settings window draws no terminal pictures.
+ let no_images = crate::termwindow::render::paint::ImageCompositeBatch::default();
draw_webgpu_layers(
webgpu,
render_state,
@@ -4025,6 +4027,7 @@ impl SettingsWindow {
pending: Vec::new(),
composites: Vec::new(),
},
+ &no_images,
&mut None,
&mut Vec::new(),
)?;
diff --git a/wezterm-gui/src/termwindow/mod.rs b/wezterm-gui/src/termwindow/mod.rs
index 24920786..10b7e18e 100644
--- a/wezterm-gui/src/termwindow/mod.rs
+++ b/wezterm-gui/src/termwindow/mod.rs
@@ -2134,6 +2134,17 @@ pub struct TermWindow {
card_frame_verts: RefCell<Vec<crate::quad::Vertex>>,
/// One textured quad per card standing in for its glyph quads.
card_composites: RefCell<Vec<crate::termwindow::render::paint::CardComposite>>,
+ /// Per-cell quads of pictures drawn from dedicated textures this pass
+ /// (see `populate_image_quad`), consumed by the composite passes.
+ image_composites: RefCell<crate::termwindow::render::paint::ImageCompositeBatch>,
+ /// Set by `populate_image_quad` when the line being rendered drew a
+ /// picture from a dedicated texture; the pane renderer then keeps that
+ /// line out of the line quad cache, whose replay would lose the picture.
+ dedicated_image_in_line: std::cell::Cell<bool>,
+ /// The (layer, cell) whose latest picture went to a dedicated texture,
+ /// so pictures stacked above it in the same cell follow it there and
+ /// keep their z-order; reset at the start of every line.
+ dedicated_image_cell: std::cell::Cell<Option<(usize, usize)>>,
/// The settled frame's composites, kept so a closing overview's ghost
/// can fade the card pictures out with it (the ghost heap itself holds
/// no thumbnail quads on the texture path).
@@ -2514,6 +2525,14 @@ pub struct TermWindow {
}
impl TermWindow {
+ /// Whether pictures may draw from dedicated textures right now. A
+ /// content-view transition records the whole terminal into one heap and
+ /// replays it scaled; per-cell composites cannot be replayed from a
+ /// heap, so those frames fall back to the atlas path.
+ pub(crate) fn dedicated_image_textures_allowed(&self) -> bool {
+ self.content_view_fade.is_none() && self.content_view_last_frame.is_none()
+ }
+
/// What the window was showing when the atlas overflowed; the report
/// uses it to tell an overview spike from a plain terminal frame.
pub(crate) fn atlas_scene(&self) -> &'static str {
@@ -2617,6 +2636,14 @@ impl TermWindow {
"{label}: recent_images=[{}]",
stats.recent_image_allocs.join("; ")
));
+ let dedicated = stats.dedicated_images;
+ lines.push(format!(
+ "{label}: dedicated_images live={} pooled={} {:.1}MiB budget={}MiB",
+ dedicated.live,
+ dedicated.pooled,
+ dedicated.bytes as f64 / (1024.0 * 1024.0),
+ crate::renderstate::DEDICATED_IMAGE_BUDGET_BYTES / (1024 * 1024),
+ ));
} else {
lines.push(format!("{label}: render_state=none"));
}
@@ -3015,6 +3042,9 @@ impl TermWindow {
self.publish_ui_shape_cache_diagnostics();
if let Some(render_state) = self.render_state.as_ref() {
render_state.shrink_quads_now();
+ // A hidden window paints no frames, so these could not age out
+ // through end_frame; re-upload on the next paint is cheap.
+ render_state.dedicated_images.borrow_mut().clear();
}
self.line_quad_cache.borrow_mut().clear();
// The buffers just dropped stay resident until a device maintain
@@ -3431,6 +3461,9 @@ impl TermWindow {
pending_card_renders: RefCell::new(Vec::new()),
card_frame_verts: RefCell::new(Vec::new()),
card_composites: RefCell::new(Vec::new()),
+ image_composites: RefCell::new(Default::default()),
+ dedicated_image_in_line: std::cell::Cell::new(false),
+ dedicated_image_cell: std::cell::Cell::new(None),
content_view_last_composites: RefCell::new(Vec::new()),
card_scratch: RefCell::new(None),
preview_scale_hold: RefCell::new(HashMap::new()),
diff --git a/wezterm-gui/src/termwindow/render/draw.rs b/wezterm-gui/src/termwindow/render/draw.rs
index 4ac0309c..1adeb5c7 100644
--- a/wezterm-gui/src/termwindow/render/draw.rs
+++ b/wezterm-gui/src/termwindow/render/draw.rs
@@ -1,5 +1,6 @@
use crate::colorease::ColorEaseUniform;
use crate::renderstate::{LoggedSrgbTexture2d, RenderState};
+use crate::termwindow::render::paint::{ImageComposite, ImageCompositeBatch, ImageCompositeSlot};
use crate::termwindow::webgpu::{ShaderUniform, WebGpuState};
use crate::termwindow::RenderFrame;
use crate::uniforms::UniformBuilder;
@@ -211,6 +212,7 @@ pub(crate) fn draw_webgpu_layers(
window_border: WindowBorder,
window_label: usize,
cards: CardDrawData,
+ images: &ImageCompositeBatch,
card_scratch: &mut Option<CardScratch>,
frame_verts: &mut Vec<crate::quad::Vertex>,
) -> anyhow::Result<()> {
@@ -275,6 +277,16 @@ pub(crate) fn draw_webgpu_layers(
composite_draws.push((composite.zindex, base as i32, composite));
}
}
+ // Dedicated-texture picture quads ride in the same scratch upload; each
+ // group is one bind + one indexed draw covering `quad_count` quads.
+ let image_base = frame_verts.len();
+ frame_verts.extend_from_slice(&images.verts);
+ let image_draws: Vec<(ImageCompositeSlot, i32, &ImageComposite)> = images
+ .groups
+ .iter()
+ .map(|group| (group.slot, (image_base + group.first_vertex) as i32, group))
+ .collect();
+ crate::perf::log_counter("image_composites", image_draws.len());
if !frame_verts.is_empty() {
let max_quads = cards
.pending
@@ -282,6 +294,7 @@ pub(crate) fn draw_webgpu_layers(
.map(|pending| pending.quad_count)
.max()
.unwrap_or(0)
+ .max(images.max_quad_count())
.max(1);
CardScratch::ensure(card_scratch, webgpu, frame_verts.len(), max_quads);
let scratch = card_scratch.as_ref().expect("just ensured");
@@ -411,17 +424,32 @@ pub(crate) fn draw_webgpu_layers(
// Card pictures composite between this layer's base fills and
// its glyph sub-buffers: above their own card background, below
- // every label drawn on top.
- if idx == 0
+ // every label drawn on top. Dedicated-texture terminal pictures
+ // join that pass when they belong under the text (z<0, formerly
+ // sub-buffer 0) and get an identical pass after the glyph
+ // sub-buffer when they belong over it (z>=0, formerly sub-buffer
+ // 2). Not after sub-buffer 2 itself: the context menu, scrollbar
+ // thumb, drag ghost and hover sidebar are emitted into that
+ // sub-buffer after the panes, and by quad order they sat above
+ // a z>=0 picture; a pass after it would paint the picture over
+ // them. Terminal panes live in layer 0.
+ let image_slot = match idx {
+ 0 => Some(ImageCompositeSlot::AfterFills),
+ 1 => Some(ImageCompositeSlot::AfterGlyphs),
+ _ => None,
+ };
+ let cards_here = idx == 0
&& composite_draws
.iter()
- .any(|(zindex, _, _)| *zindex == layer.zindex())
- {
+ .any(|(zindex, _, _)| *zindex == layer.zindex());
+ let images_here = layer.zindex() == 0
+ && image_slot.is_some_and(|slot| image_draws.iter().any(|(s, _, _)| *s == slot));
+ if cards_here || images_here {
let scratch = card_scratch
.as_ref()
.expect("composite draws imply the scratch exists");
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
- label: Some("Card Composite Pass"),
+ label: Some("Composite Pass"),
color_attachments: &[Some(wgpu::RenderPassColorAttachment {
view: &view,
resolve_target: None,
@@ -443,14 +471,31 @@ pub(crate) fn draw_webgpu_layers(
pass.set_bind_group(0, &window_uniforms, &[]);
pass.set_vertex_buffer(0, scratch.vb.slice(..));
pass.set_index_buffer(scratch.index.slice(..), wgpu::IndexFormat::Uint32);
- for (zindex, base, composite) in &composite_draws {
- if *zindex != layer.zindex() {
- continue;
+ if cards_here {
+ for (zindex, base, composite) in &composite_draws {
+ if *zindex != layer.zindex() {
+ continue;
+ }
+ pass.set_bind_group(1, &composite.texture.bind_group, &[]);
+ pass.set_bind_group(2, &composite.texture.bind_group, &[]);
+ pass.draw_indexed(0..6, *base, 0..1);
+ draw_calls += 1;
+ }
+ }
+ if images_here {
+ let slot = image_slot.expect("images_here implies a slot");
+ for (s, base, group) in &image_draws {
+ if *s != slot {
+ continue;
+ }
+ // Linear in slot 1, nearest in slot 2: the same
+ // pairing the main pass gives the atlas, so the
+ // shader's minification mix behaves identically.
+ pass.set_bind_group(1, &group.texture.bind_group_linear, &[]);
+ pass.set_bind_group(2, &group.texture.bind_group_nearest, &[]);
+ pass.draw_indexed(0..(group.quad_count * 6) as u32, *base, 0..1);
+ draw_calls += 1;
}
- pass.set_bind_group(1, &composite.texture.bind_group, &[]);
- pass.set_bind_group(2, &composite.texture.bind_group, &[]);
- pass.draw_indexed(0..6, *base, 0..1);
- draw_calls += 1;
}
}
@@ -527,6 +572,7 @@ impl crate::TermWindow {
};
let mut card_scratch = self.card_scratch.borrow_mut();
let mut frame_verts = self.card_frame_verts.borrow_mut();
+ let images = self.image_composites.borrow();
draw_webgpu_layers(
webgpu,
render_state,
@@ -543,9 +589,11 @@ impl crate::TermWindow {
window_border,
self.mux_window_id as usize,
cards,
+ &images,
&mut card_scratch,
&mut frame_verts,
)?;
+ drop(images);
render_state.maybe_shrink_quads();
Ok(())
}
diff --git a/wezterm-gui/src/termwindow/render/mod.rs b/wezterm-gui/src/termwindow/render/mod.rs
index 4c19ad0d..6f9761da 100644
--- a/wezterm-gui/src/termwindow/render/mod.rs
+++ b/wezterm-gui/src/termwindow/render/mod.rs
@@ -2,11 +2,16 @@ use crate::colorease::ColorEase;
use crate::customglyph::{BlockKey, *};
use crate::glyphcache::{CachedGlyph, GlyphCache};
use crate::quad::{
- HeapQuadAllocator, QuadAllocator, QuadImpl, QuadTrait, TripleLayerQuadAllocator,
- TripleLayerQuadAllocatorTrait,
+ HeapQuadAllocator, Quad, QuadAllocator, QuadImpl, QuadTrait, TripleLayerQuadAllocator,
+ TripleLayerQuadAllocatorTrait, Vertex,
+};
+use crate::renderstate::{
+ image_fits_dedicated_texture, image_wants_dedicated_texture, RenderContext,
};
use crate::shapecache::*;
use crate::termwindow::render::paint::AllowImage;
+use crate::termwindow::render::paint::ImageCompositeSlot;
+use crate::termwindow::webgpu::ImageTexture;
use crate::termwindow::{
BorrowedShapeCacheKey, MouseCapture, RenderState, ShapedInfo, TermWindowNotif,
};
@@ -590,6 +595,82 @@ impl crate::TermWindow {
padding.next_power_of_two()
};
+ // Large pictures -- streaming kitty frames, icat -- draw from their
+ // own texture instead of a slot in the shared atlas. The atlas cannot
+ // free a rectangle, so a stream of multi-megabyte frames filled it
+ // every few frames and each overflow cleared it: a 64MiB zero image,
+ // a 64MiB upload, every glyph re-rasterised and the frame painted a
+ // second time. WebGpu only (the composite pass is), static RGBA only
+ // (animations advance their frame clock inside cached_image), and
+ // never while a content-view transition records or replays the
+ // terminal as one heap.
+ if let RenderContext::WebGpu(webgpu) = &gl_state.context {
+ let atlas_side = gl_state.glyph_cache.borrow().atlas.size();
+ let guard = image.image_data().data();
+ if let termwiz::image::ImageDataType::Rgba8 {
+ data: rgba,
+ width,
+ height,
+ hash,
+ } = &*guard
+ {
+ let (width, height, hash) = (*width, *height, *hash);
+ {
+ // Once one picture in a cell has gone to the composite
+ // pass, every picture stacked above it in that cell
+ // goes too, whatever its size: the composite pass runs
+ // after the whole atlas layer, so a small atlas picture
+ // with a higher z would otherwise be painted under the
+ // big one instead of over it.
+ let stacked_on_dedicated =
+ self.dedicated_image_cell.get() == Some((layer_num, cell_idx));
+ let max_side = webgpu.device.limits().max_texture_dimension_2d;
+ let goes_dedicated = image_fits_dedicated_texture(width, height, max_side)
+ && (stacked_on_dedicated
+ || image_wants_dedicated_texture(width, height, padding, atlas_side));
+ // Marked before the transition check: a line painted
+ // through the atlas only because a content-view
+ // transition forbade the dedicated path must not be
+ // cached either, or its replay would pin the picture in
+ // the atlas long after the transition ended.
+ if goes_dedicated {
+ self.dedicated_image_in_line.set(true);
+ }
+ if goes_dedicated && self.dedicated_image_textures_allowed() {
+ let texture = gl_state
+ .dedicated_images
+ .borrow_mut()
+ .get_or_upload(
+ hash,
+ width,
+ height,
+ || ImageTexture::new(width, height, webgpu),
+ |texture| {
+ texture.upload(rgba);
+ gl_state.glyph_cache.borrow_mut().note_dedicated_image(
+ width,
+ height,
+ termwiz::image::ImageDataType::is_nonce_key(&hash),
+ );
+ },
+ )
+ .context("dedicated image texture")?;
+ drop(guard);
+ self.push_dedicated_image_quad(
+ image,
+ &texture,
+ layer_num,
+ cell_idx,
+ params,
+ hsv,
+ glyph_color,
+ );
+ return Ok(());
+ }
+ }
+ }
+ }
+
let (sprite, next_due, _load_state) = gl_state
.glyph_cache
.borrow_mut()
@@ -646,6 +727,62 @@ impl crate::TermWindow {
Ok(())
}
+ /// The dedicated-texture twin of the atlas quad above: same cell
+ /// geometry, but the texture coordinates are the cell's sub-rectangle
+ /// of the picture over a texture that holds exactly that picture, and
+ /// the quad goes to the composite batch instead of the layer buffers.
+ fn push_dedicated_image_quad(
+ &self,
+ image: &termwiz::image::ImageCell,
+ texture: &Rc<ImageTexture>,
+ layer_num: usize,
+ cell_idx: usize,
+ params: &RenderScreenLineParams,
+ hsv: Option<config::HsbTransform>,
+ glyph_color: LinearRgba,
+ ) {
+ let top_left = image.top_left();
+ let bottom_right = image.bottom_right();
+ let texture_rect = TextureRect::new(
+ TextureCoord::new(*top_left.x, *top_left.y),
+ TextureSize::new(*bottom_right.x - *top_left.x, *bottom_right.y - *top_left.y),
+ );
+
+ let mut vert: [Vertex; 4] = Default::default();
+ let mut quad = Quad { vert: &mut vert };
+ let cell_width = params.render_metrics.cell_size.width as f32;
+ let cell_height = params.render_metrics.cell_size.height as f32;
+ let pos_y = (self.dimensions.pixel_height as f32 / -2.) + params.top_pixel_y;
+ let pos_x = (self.dimensions.pixel_width as f32 / -2.)
+ + params.left_pixel_x
+ + (cell_idx as f32 * cell_width);
+ let (padding_left, padding_top, padding_right, padding_bottom) = image.padding();
+ quad.set_position(
+ pos_x + padding_left as f32,
+ pos_y + padding_top as f32,
+ pos_x + cell_width + padding_left as f32 - padding_right as f32,
+ pos_y + cell_height + padding_top as f32 - padding_bottom as f32,
+ );
+ quad.set_hsv(hsv);
+ quad.set_fg_color(glyph_color);
+ quad.set_texture(texture_rect);
+ quad.set_has_color(true);
+
+ // Sub-buffer 0 is where z<0 pictures went (under the glyphs),
+ // sub-buffer 2 where z>=0 went (over them); the composite passes
+ // sit at the same two points.
+ let slot = if layer_num == 0 {
+ ImageCompositeSlot::AfterFills
+ } else {
+ ImageCompositeSlot::AfterGlyphs
+ };
+ self.image_composites
+ .borrow_mut()
+ .push_quad(texture, slot, vert);
+ self.dedicated_image_in_line.set(true);
+ self.dedicated_image_cell.set(Some((layer_num, cell_idx)));
+ }
+
fn ensure_min_contrast(&self, fg_color: LinearRgba, bg_color: LinearRgba) -> LinearRgba {
match self.config.text_min_contrast_ratio {
Some(ratio) => fg_color
diff --git a/wezterm-gui/src/termwindow/render/paint.rs b/wezterm-gui/src/termwindow/render/paint.rs
index 5037d7f2..089dc96b 100644
--- a/wezterm-gui/src/termwindow/render/paint.rs
+++ b/wezterm-gui/src/termwindow/render/paint.rs
@@ -1,5 +1,5 @@
use crate::quad::{
- HeapQuadAllocator, HeapQuadMark, QuadClipRect, QuadTrait, TripleLayerQuadAllocator,
+ HeapQuadAllocator, HeapQuadMark, QuadClipRect, QuadTrait, TripleLayerQuadAllocator, Vertex,
};
use crate::termwindow::content_view::{ContentViewTypography, TerminalPreviewRequest};
use crate::termwindow::render::{LineToEleShapeCacheKey, RenderScreenLineParams};
@@ -229,6 +229,71 @@ pub(crate) struct CardComposite {
pub zindex: i8,
}
+/// Where a dedicated-texture image composite is drawn relative to the
+/// terminal layer's sub-buffers, mirroring the sub-buffer the atlas path
+/// would have used: under the glyphs for z<0 pictures, over them for z>=0.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ImageCompositeSlot {
+ AfterFills,
+ AfterGlyphs,
+}
+
+/// A run of per-cell quads that all sample one dedicated image texture,
+/// drawn with a single bind + draw in the composite pass.
+pub(crate) struct ImageComposite {
+ pub texture: Rc<crate::termwindow::webgpu::ImageTexture>,
+ pub slot: ImageCompositeSlot,
+ /// Offset into `ImageCompositeBatch::verts`.
+ pub first_vertex: usize,
+ pub quad_count: usize,
+}
+
+/// The dedicated-texture image quads of one paint pass. Persistent and
+/// cleared per pass like `card_frame_verts`, so a stream does not allocate
+/// per frame; consecutive quads on the same texture and slot coalesce into
+/// one composite.
+#[derive(Default)]
+pub(crate) struct ImageCompositeBatch {
+ pub verts: Vec<Vertex>,
+ pub groups: Vec<ImageComposite>,
+}
+
+impl ImageCompositeBatch {
+ pub fn push_quad(
+ &mut self,
+ texture: &Rc<crate::termwindow::webgpu::ImageTexture>,
+ slot: ImageCompositeSlot,
+ quad: [Vertex; 4],
+ ) {
+ let first_vertex = self.verts.len();
+ self.verts.extend_from_slice(&quad);
+ match self.groups.last_mut() {
+ Some(group)
+ if group.slot == slot
+ && Rc::ptr_eq(&group.texture, texture)
+ && group.first_vertex + group.quad_count * 4 == first_vertex =>
+ {
+ group.quad_count += 1;
+ }
+ _ => self.groups.push(ImageComposite {
+ texture: Rc::clone(texture),
+ slot,
+ first_vertex,
+ quad_count: 1,
+ }),
+ }
+ }
+
+ pub fn clear(&mut self) {
+ self.verts.clear();
+ self.groups.clear();
+ }
+
+ pub fn max_quad_count(&self) -> usize {
+ self.groups.iter().map(|g| g.quad_count).max().unwrap_or(0)
+ }
+}
+
fn preview_quad_key(
preview: &TerminalPreviewRequest,
dimensions: &Dimensions,
@@ -995,6 +1060,13 @@ impl crate::TermWindow {
}
log::debug!("paint_impl before call_draw elapsed={:?}", start.elapsed());
+ // One paint, presented or not: retire dedicated textures nobody
+ // drew. Ticking only after a successful draw left the cache's
+ // budget switched off for exactly the frames that fail or are
+ // skipped, while every pass kept uploading a fresh texture.
+ if let Some(render_state) = self.render_state.as_ref() {
+ render_state.dedicated_images.borrow_mut().end_frame();
+ }
let draw_result = if present_frame || !matches!(frame, RenderFrame::WebGpu) {
self.call_draw(frame).map(|_| true)
} else {
@@ -3490,6 +3562,7 @@ impl crate::TermWindow {
self.card_composites.borrow_mut().clear();
// Truncate, not drop: the buffer's capacity is the whole point.
self.card_frame_verts.borrow_mut().clear();
+ self.image_composites.borrow_mut().clear();
{
let gl_state = self.render_state.as_ref().unwrap();
for layer in gl_state.layers.borrow().iter() {
diff --git a/wezterm-gui/src/termwindow/render/pane.rs b/wezterm-gui/src/termwindow/render/pane.rs
index 8839a8ba..0760eda0 100644
--- a/wezterm-gui/src/termwindow/render/pane.rs
+++ b/wezterm-gui/src/termwindow/render/pane.rs
@@ -1769,6 +1769,7 @@ impl crate::TermWindow {
},
};
+ self.term_window.dedicated_image_in_line.set(false);
let render_result = self
.term_window
.render_screen_line(
@@ -1836,10 +1837,15 @@ impl crate::TermWindow {
&quad_key,
&quad_value,
);
- self.term_window
- .line_quad_cache
- .borrow_mut()
- .put_weighted(quad_key, quad_value, weight);
+ // A line that drew a picture from a dedicated texture
+ // emitted composites as a side effect; replaying its
+ // cached heap would repaint the line without the picture.
+ if !self.term_window.dedicated_image_in_line.replace(false) {
+ self.term_window
+ .line_quad_cache
+ .borrow_mut()
+ .put_weighted(quad_key, quad_value, weight);
+ }
Ok(())
}
diff --git a/wezterm-gui/src/termwindow/render/screen_line.rs b/wezterm-gui/src/termwindow/render/screen_line.rs
index fc2f4e66..9a7010ea 100644
--- a/wezterm-gui/src/termwindow/render/screen_line.rs
+++ b/wezterm-gui/src/termwindow/render/screen_line.rs
@@ -28,6 +28,7 @@ impl crate::TermWindow {
params: RenderScreenLineParams,
layers: &mut TripleLayerQuadAllocator,
) -> anyhow::Result<RenderScreenLineResult> {
+ self.dedicated_image_cell.set(None);
if params.line.is_double_height_bottom() {
// The top and bottom lines are required to have the same content.
// For the sake of simplicity, we render both of them as part of
@@ -917,7 +918,17 @@ impl crate::TermWindow {
let shaped = Rc::new(shaped);
- if let Some(shape_key) = params.shape_key {
+ // A line carrying pictures is not cached. The clusters keep the
+ // cells' image attachments, so every entry pins its frame's pixels;
+ // a streaming client changes those attachments every frame, every
+ // line hashes differently, and the cache ends up holding thousands
+ // of entries times a multi-megabyte frame each until LFU pressure --
+ // gigabytes for pictures that were overwritten long ago. Shaping a
+ // line of mostly blank cells again is cheap.
+ let holds_images = shaped
+ .iter()
+ .any(|item| item.cluster.attrs.images().is_some());
+ if let (Some(shape_key), false) = (params.shape_key, holds_images) {
let item = LineToElementShapeItem {
expires,
shaped: Rc::clone(&shaped),
diff --git a/wezterm-gui/src/termwindow/webgpu.rs b/wezterm-gui/src/termwindow/webgpu.rs
index 81aff326..ec64d176 100644
--- a/wezterm-gui/src/termwindow/webgpu.rs
+++ b/wezterm-gui/src/termwindow/webgpu.rs
@@ -317,6 +317,113 @@ impl CardRenderTexture {
}
}
+/// A dedicated texture for one large image -- a streaming kitty frame, an
+/// `icat` picture -- drawn as its own composite instead of being packed into
+/// the shared glyph atlas. The atlas cannot free a rectangle, so a stream of
+/// multi-megabyte frames filled it every few frames and forced a full clear
+/// (a 64MiB zero image, a 64MiB upload and a second paint pass) each time.
+/// These textures are reused across frames of the same size, so a stream
+/// costs one `write_texture` per frame and nothing else.
+pub struct ImageTexture {
+ pub texture: wgpu::Texture,
+ /// Same layout as the atlas bind groups, so the composite pass binds
+ /// linear into slot 1 and nearest into slot 2 exactly like the main pass
+ /// does for the atlas, and the shader's minification mix behaves the
+ /// same on both paths (a single linear binding would soften 1:1 output).
+ pub bind_group_linear: wgpu::BindGroup,
+ pub bind_group_nearest: wgpu::BindGroup,
+ pub width: u32,
+ pub height: u32,
+ queue: Arc<wgpu::Queue>,
+}
+
+impl ImageTexture {
+ pub fn new(width: u32, height: u32, state: &WebGpuState) -> anyhow::Result<Self> {
+ let limit = state.device.limits().max_texture_dimension_2d;
+ if width == 0 || height == 0 || width > limit || height > limit {
+ anyhow::bail!(
+ "image texture dimensions {width}x{height} are outside the \
+ 1..={limit} range supported by your GPU"
+ );
+ }
+ gpu_debug(format!(
+ "create WebGpu texture label=Image Texture size={width}x{height} bytes={}",
+ width as usize * height as usize * 4
+ ));
+ // The same format as the atlas: the pixels are the same RGBA8 bytes
+ // the atlas path uploads today, just not through the allocator.
+ let texture = state.device.create_texture(&wgpu::TextureDescriptor {
+ size: wgpu::Extent3d {
+ width,
+ height,
+ depth_or_array_layers: 1,
+ },
+ mip_level_count: 1,
+ sample_count: 1,
+ dimension: wgpu::TextureDimension::D2,
+ format: wgpu::TextureFormat::Rgba8UnormSrgb,
+ usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
+ label: Some("Image Texture"),
+ view_formats: &[],
+ });
+ let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
+ let make = |sampler: &wgpu::Sampler, label: &str| {
+ state.device.create_bind_group(&wgpu::BindGroupDescriptor {
+ layout: &state.texture_bind_group_layout,
+ entries: &[
+ wgpu::BindGroupEntry {
+ binding: 0,
+ resource: wgpu::BindingResource::TextureView(&view),
+ },
+ wgpu::BindGroupEntry {
+ binding: 1,
+ resource: wgpu::BindingResource::Sampler(sampler),
+ },
+ ],
+ label: Some(label),
+ })
+ };
+ let bind_group_linear = make(&state.texture_linear_sampler, "image texture linear");
+ let bind_group_nearest = make(&state.texture_nearest_sampler, "image texture nearest");
+ Ok(Self {
+ texture,
+ bind_group_linear,
+ bind_group_nearest,
+ width,
+ height,
+ queue: Arc::clone(&state.queue),
+ })
+ }
+
+ /// Upload tightly packed RGBA8 pixels covering the whole texture.
+ pub fn upload(&self, rgba: &[u8]) {
+ debug_assert_eq!(rgba.len(), self.byte_size());
+ self.queue.write_texture(
+ wgpu::TexelCopyTextureInfo {
+ texture: &self.texture,
+ mip_level: 0,
+ origin: wgpu::Origin3d::ZERO,
+ aspect: wgpu::TextureAspect::All,
+ },
+ rgba,
+ wgpu::TexelCopyBufferLayout {
+ offset: 0,
+ bytes_per_row: Some(self.width * 4),
+ rows_per_image: Some(self.height),
+ },
+ wgpu::Extent3d {
+ width: self.width,
+ height: self.height,
+ depth_or_array_layers: 1,
+ },
+ );
+ }
+
+ pub fn byte_size(&self) -> usize {
+ self.width as usize * self.height as usize * 4
+ }
+}
+
pub fn adapter_info_to_gpu_info(info: wgpu::AdapterInfo) -> GpuInfo {
GpuInfo {
name: info.name,