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.
Rust agentagent-orchestrationaiai-agentsclaude-codecodexcoding-agentlinuxmacosmultiplayermultiplexerrustterminalterminal-emulatorterminal-multiplexertmuxtuiweztermwindows
gui,window: instrument the glyph atlas and cap its growth
RoversX6e01c2db0447
diff --git a/wezterm-gui/src/glyphcache.rs b/wezterm-gui/src/glyphcache.rsindex d241f960..b8ec75d6 100644--- a/wezterm-gui/src/glyphcache.rs+++ b/wezterm-gui/src/glyphcache.rs@@ -3,7 +3,7 @@ use crate::customglyph::*;use crate::renderstate::RenderContext;use crate::termwindow::render::paint::AllowImage;use crate::termwindow::ui::icons::{BrandIcon, MaterialIcon, SvgIcon};-use ::window::bitmaps::atlas::{Atlas, OutOfTextureSpace, Sprite};+use ::window::bitmaps::atlas::{Atlas, AtlasTag, AtlasUsage, OutOfTextureSpace, Sprite};use ::window::bitmaps::{BitmapImage, Image, ImageTexture, Texture2d};use ::window::color::SrgbaPixel;use ::window::{Point, Rect};@@ -16,7 +16,7 @@ use image::{use lfucache::LfuCache;use ordered_float::NotNan;use std::cell::RefCell;-use std::collections::HashMap;+use std::collections::{HashMap, HashSet, VecDeque};use std::io::Seek;use std::rc::Rc;use std::sync::atomic::{AtomicBool, Ordering};@@ -581,6 +581,40 @@ impl DecodedImage {}}+/// One image upload into the atlas. The atlas only knows areas; this is+/// what lets the memory report name the pictures that took the space.+#[derive(Debug, Clone)]+pub struct ImageAllocRecord {+ pub width: usize,+ pub height: usize,+ /// The downscale divisor the frame was uploaded at, if any.+ pub scale: Option<usize>,+ pub animated: bool,+ /// A one-shot streaming frame (nonce key): never requested again+ /// under the same key, so each one is fresh atlas area.+ pub nonce: bool,+ pub at: Instant,+}++impl ImageAllocRecord {+ pub fn describe(&self, now: Instant) -> String {+ format!(+ "{}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 { "" },+ now.saturating_duration_since(self.at).as_secs(),+ )+ }+}++/// How many recent image uploads the report keeps. Survives atlas+/// recreation (the render state carries it across) so the uploads that+/// forced a grow are still listed afterwards.+const IMAGE_ALLOC_LOG_LEN: usize = 16;+/// A number of items here are HashMaps rather than LfuCaches;/// eviction is managed by recreating Self when the Atlas is filledpub struct GlyphCache {@@ -589,6 +623,10 @@ pub struct GlyphCache {pub fonts: Rc<FontConfiguration>,pub image_cache: LfuCache<[u8; 32], DecodedImage>,frame_cache: HashMap<[u8; 32], Sprite>,+ /// Frames that were uploaded downscaled, so the hash-keyed frame cache+ /// can drop them once full size is allowed again.+ scaled_frames: HashSet<[u8; 32]>,+ pub(crate) image_alloc_log: VecDeque<ImageAllocRecord>,line_glyphs: HashMap<LineKey, Sprite>,pub block_glyphs: HashMap<SizedBlockKey, Sprite>,pub svg_icons: HashMap<SizedSvgIconKey, Sprite>,@@ -603,6 +641,9 @@ pub struct GlyphCache {#[derive(Debug, Clone)]pub struct GlyphCacheStats {pub atlas_size: usize,+ pub atlas_usage: AtlasUsage,+ /// Newest first.+ pub recent_image_allocs: Vec<String>,pub glyphs: usize,pub decoded_images: usize,pub image_frames: usize,@@ -616,8 +657,16 @@ pub struct GlyphCacheStats {impl GlyphCache {pub fn stats(&self) -> GlyphCacheStats {+ let now = Instant::now();GlyphCacheStats {atlas_size: self.atlas.size(),+ atlas_usage: self.atlas.usage(),+ recent_image_allocs: self+ .image_alloc_log+ .iter()+ .rev()+ .map(|record| record.describe(now))+ .collect(),glyphs: self.glyph_cache.len(),decoded_images: self.image_cache.len(),image_frames: self.frame_cache.len(),@@ -644,6 +693,8 @@ impl GlyphCache {&fonts.config(),),frame_cache: HashMap::new(),+ scaled_frames: HashSet::new(),+ image_alloc_log: VecDeque::new(),atlas,line_glyphs: HashMap::new(),block_glyphs: HashMap::new(),@@ -677,6 +728,8 @@ impl GlyphCache {&fonts.config(),),frame_cache: HashMap::new(),+ scaled_frames: HashSet::new(),+ image_alloc_log: VecDeque::new(),atlas,line_glyphs: HashMap::new(),block_glyphs: HashMap::new(),@@ -937,7 +990,9 @@ impl GlyphCache {(scale, raw_im)};- let tex = self.atlas.allocate(&raw_im)?;+ let tex = self+ .atlas+ .allocate_tagged(&raw_im, None, None, AtlasTag::Glyph)?;let g = CachedGlyph {brightness_adjust,@@ -963,9 +1018,47 @@ impl GlyphCache {Ok(Rc::new(glyph))}+ fn note_image_alloc(+ log: &mut VecDeque<ImageAllocRecord>,+ (width, height): (usize, usize),+ scale: Option<usize>,+ animated: bool,+ nonce: bool,+ ) {+ if log.len() >= IMAGE_ALLOC_LOG_LEN {+ log.pop_front();+ }+ log.push_back(ImageAllocRecord {+ width,+ height,+ scale,+ animated,+ nonce,+ at: Instant::now(),+ });+ }++ /// Forget the sprites that were uploaded downscaled. The frame cache is+ /// keyed by image hash alone, so without this a lapsed downscale hold+ /// would keep serving the small copies until some unrelated atlas+ /// rebuild. The atlas area they occupy is not reclaimed (the allocator+ /// cannot free a rectangle); the next paint re-uploads at full size,+ /// which is exactly the probe the hold's expiry is for.+ pub fn evict_scaled_frames(&mut self) -> usize {+ let mut evicted = 0;+ for hash in self.scaled_frames.drain() {+ if self.frame_cache.remove(&hash).is_some() {+ evicted += 1;+ }+ }+ evicted+ }+fn cached_image_impl(frame_cache: &mut HashMap<[u8; 32], Sprite>,+ scaled_frames: &mut HashSet<[u8; 32]>,atlas: &mut Atlas,+ image_alloc_log: &mut VecDeque<ImageAllocRecord>,decoded: &DecodedImage,padding: Option<usize>,min_frame_duration: Duration,@@ -975,10 +1068,17 @@ impl GlyphCache {h: decoded.image.data(),current_frame: *decoded.current_frame.borrow(),};+ let nonce = ImageDataType::is_nonce_key(&decoded.image.hash());let scale_down = match allow_image {+ AllowImage::Yes => None,AllowImage::Scale(n) => Some(n),- _ => None,+ // Callers that can skip an image at `No` do so before getting+ // here (terminal cells, the window background, the sidebar).+ // Anything that still asks must never re-upload the original:+ // that is the size the atlas just failed to hold, and the retry+ // would end on an incomplete frame instead of recovering.+ AllowImage::No => Some(8),};match &*handle.h {@@ -987,9 +1087,19 @@ impl GlyphCache {return Ok((sprite.clone(), None, LoadState::Loaded));}let sprite = atlas- .allocate_with_padding(&handle, padding, scale_down)+ .allocate_tagged(&handle, padding, scale_down, AtlasTag::Image).context("atlas.allocate_with_padding")?;+ Self::note_image_alloc(+ image_alloc_log,+ handle.image_dimensions(),+ scale_down,+ false,+ nonce,+ );frame_cache.insert(*hash, sprite.clone());+ if scale_down.is_some() {+ scaled_frames.insert(*hash);+ }return Ok((sprite, None, LoadState::Loaded));}@@ -1043,10 +1153,20 @@ impl GlyphCache {}let sprite = atlas- .allocate_with_padding(&handle, padding, scale_down)+ .allocate_tagged(&handle, padding, scale_down, AtlasTag::Image).context("atlas.allocate_with_padding")?;+ Self::note_image_alloc(+ image_alloc_log,+ handle.image_dimensions(),+ scale_down,+ true,+ nonce,+ );frame_cache.insert(hash, sprite.clone());+ if scale_down.is_some() {+ scaled_frames.insert(hash);+ }return Ok((sprite,@@ -1135,9 +1255,19 @@ impl GlyphCache {frames.current_frame.height,frame_data,);- let sprite = atlas.allocate_with_padding(&frame, padding, scale_down)?;+ let sprite = atlas.allocate_tagged(&frame, padding, scale_down, AtlasTag::Image)?;+ Self::note_image_alloc(+ image_alloc_log,+ (frames.current_frame.width, frames.current_frame.height),+ scale_down,+ true,+ nonce,+ );frame_cache.insert(hash, sprite.clone());+ if scale_down.is_some() {+ scaled_frames.insert(hash);+ }Ok((sprite,@@ -1174,7 +1304,9 @@ impl GlyphCache {let decoded = DecodedImage::load(image_data);return Self::cached_image_impl(&mut self.frame_cache,+ &mut self.scaled_frames,&mut self.atlas,+ &mut self.image_alloc_log,&decoded,padding,self.min_frame_duration,@@ -1185,7 +1317,9 @@ impl GlyphCache {if let Some(decoded) = self.image_cache.get(&hash) {Self::cached_image_impl(&mut self.frame_cache,+ &mut self.scaled_frames,&mut self.atlas,+ &mut self.image_alloc_log,decoded,padding,self.min_frame_duration,@@ -1195,7 +1329,9 @@ impl GlyphCache {let decoded = DecodedImage::load(image_data);let res = Self::cached_image_impl(&mut self.frame_cache,+ &mut self.scaled_frames,&mut self.atlas,+ &mut self.image_alloc_log,&decoded,padding,self.min_frame_duration,@@ -1549,3 +1685,62 @@ impl GlyphCache {self.line_sprite(key, metrics)}}++#[cfg(test)]+mod scaled_frame_tests {+ use super::*;+ use wezterm_font::FontConfiguration;++ fn glyph_cache() -> GlyphCache {+ config::use_test_configuration();+ let fonts =+ Rc::new(FontConfiguration::new(None, ::window::default_dpi() as usize).unwrap());+ GlyphCache::new_in_memory(&fonts, 256).unwrap()+ }++ fn image(side: u32, fill: u8) -> Arc<ImageData> {+ Arc::new(ImageData::with_data(+ ImageDataType::new_single_frame_content_hashed(+ side,+ side,+ vec![fill; (side * side * 4) as usize],+ ),+ ))+ }++ #[test]+ fn evicting_scaled_frames_drops_only_the_downscaled_sprites() {+ let mut cache = glyph_cache();+ let full = image(16, 255);+ let scaled = image(32, 128);++ cache.cached_image(&full, None, AllowImage::Yes).unwrap();+ let (small, _, _) = cache+ .cached_image(&scaled, None, AllowImage::Scale(2))+ .unwrap();+ assert_eq!(small.coords.width(), 16);+ assert_eq!(cache.frame_cache.len(), 2);++ // Hash-only lookup: full size asked for, small copy served.+ let (still_small, _, _) = cache.cached_image(&scaled, None, AllowImage::Yes).unwrap();+ assert_eq!(still_small.coords.width(), 16);++ assert_eq!(cache.evict_scaled_frames(), 1);+ assert_eq!(cache.frame_cache.len(), 1);+ assert_eq!(cache.evict_scaled_frames(), 0);++ let (reprobed, _, _) = cache.cached_image(&scaled, None, AllowImage::Yes).unwrap();+ assert_eq!(reprobed.coords.width(), 32);+ assert_eq!(cache.frame_cache.len(), 2);+ }++ #[test]+ fn no_never_uploads_the_original_size() {+ let mut cache = glyph_cache();+ let (sprite, _, _) = cache+ .cached_image(&image(64, 7), None, AllowImage::No)+ .unwrap();+ assert_eq!(sprite.coords.width(), 8);+ assert_eq!(cache.scaled_frames.len(), 1);+ }+}diff --git a/wezterm-gui/src/renderstate.rs b/wezterm-gui/src/renderstate.rsindex 49f17cc2..ec1385e6 100644--- a/wezterm-gui/src/renderstate.rs+++ b/wezterm-gui/src/renderstate.rs@@ -751,6 +751,9 @@ pub struct RenderState {pub struct RenderStateStats {pub backend: &'static str,pub atlas_size: usize,+ pub atlas_usage: ::window::bitmaps::atlas::AtlasUsage,+ /// Newest first.+ pub recent_image_allocs: Vec<String>,pub glyphs: usize,pub decoded_images: usize,pub image_frames: usize,@@ -940,6 +943,11 @@ impl RenderState {self.glyph_cache.borrow_mut().config_changed();}+ /// See [`GlyphCache::evict_scaled_frames`].+ pub fn evict_scaled_image_frames(&self) -> usize {+ self.glyph_cache.borrow_mut().evict_scaled_frames()+ }+pub fn stats(&self) -> RenderStateStats {let glyph = self.glyph_cache.borrow().stats();let layers = self.layers.borrow();@@ -953,6 +961,8 @@ impl RenderState {RenderContext::WebGpu(_) => "WebGpu",},atlas_size: glyph.atlas_size,+ atlas_usage: glyph.atlas_usage,+ recent_image_allocs: glyph.recent_image_allocs,glyphs: glyph.glyphs,decoded_images: glyph.decoded_images,image_frames: glyph.image_frames,@@ -996,6 +1006,16 @@ impl RenderState {..}) = err.downcast_ref::<OutOfTextureSpace>(){+ // This loop only has to fit the utility sprites; it+ // must not become a back door past the cap the+ // paint loop enforces.+ if needed_size > crate::termwindow::MAX_ATLAS_SIZE {+ anyhow::bail!(+ "texture atlas would need {needed_size} texels per side \+ for the utility sprites, past the {} cap",+ crate::termwindow::MAX_ATLAS_SIZE+ );+ }size.replace(needed_size);continue;}@@ -1025,6 +1045,12 @@ impl RenderState {&mut glyph_cache.image_cache,&mut new_glyph_cache.image_cache,);+ // The upload log is diagnostics for exactly this moment: keep the+ // pictures that forced the recreation visible in the report.+ std::mem::swap(+ &mut glyph_cache.image_alloc_log,+ &mut new_glyph_cache.image_alloc_log,+ );*glyph_cache = new_glyph_cache;Ok(())diff --git a/wezterm-gui/src/settings_window.rs b/wezterm-gui/src/settings_window.rsindex 060eb2e2..7e5ad4d1 100644--- a/wezterm-gui/src/settings_window.rs+++ b/wezterm-gui/src/settings_window.rs@@ -3942,6 +3942,34 @@ impl SettingsWindow {}) = err.root_cause().downcast_ref::<OutOfTextureSpace>(){let size = size.max(current_size);+ if size > crate::termwindow::MAX_ATLAS_SIZE {+ // The settings window draws no images, so a+ // glyph working set past the cap is not+ // something a downscale could fix. The failed+ // pass already cleared the layers, so drawing+ // now would present a half-built frame: return+ // without drawing and the previous frame stays.+ log::error!(+ "settings window atlas would need {size} texels per side, \+ past the {} cap; keeping the previous frame",+ crate::termwindow::MAX_ATLAS_SIZE+ );+ // Clear in place before giving up: a full atlas+ // of stale glyphs asks for double its size, and+ // without a clear every later paint would hit+ // this same branch and the window would freeze.+ if let Err(err) =+ self.render_state.as_mut().unwrap().recreate_texture_atlas(+ &self.fonts,+ &self.metrics,+ Some(current_size),+ )+ {+ log::error!("settings window atlas clear failed: {err:#}");+ }+ self.invalidate_shaped_text();+ return Ok(false);+ }crate::perf::log_counter("settings_atlas_reallocate", size);let recreated = self.render_state.as_mut().unwrap().recreate_texture_atlas(&self.fonts,diff --git a/wezterm-gui/src/termwindow/background.rs b/wezterm-gui/src/termwindow/background.rsindex 37890869..9e5262be 100644--- a/wezterm-gui/src/termwindow/background.rs+++ b/wezterm-gui/src/termwindow/background.rs@@ -425,6 +425,13 @@ impl crate::TermWindow {layer_index: i8,top: StableRowIndex,) -> anyhow::Result<bool> {+ // Once the atlas overflow chain reached `No`, no picture uploads+ // this frame -- same rule as terminal cells and the sidebar. The+ // caller already skips the whole background at `No`; this keeps+ // the guarantee local to the one place that uploads.+ if self.allow_images == crate::termwindow::render::paint::AllowImage::No {+ return Ok(false);+ }let render_layer = gl_state.layer_for_zindex(layer_index)?;let vbs = render_layer.vb.borrow();let mut layer0 = vbs[0].map();diff --git a/wezterm-gui/src/termwindow/mod.rs b/wezterm-gui/src/termwindow/mod.rsindex 2c423e3f..24920786 100644--- a/wezterm-gui/src/termwindow/mod.rs+++ b/wezterm-gui/src/termwindow/mod.rs@@ -278,6 +278,45 @@ const ATLAS_SIZE: usize = 128;/// one-off glyphs a closed overview leaves behind.const MAX_GROWN_ATLAS_SIZE: usize = 2048;+/// Absolute ceiling for the glyph atlas on any paint pass, in texels per+/// side; 8192² of RGBA is 256MiB. [`MAX_GROWN_ATLAS_SIZE`] only bounds the+/// first pass: the retry passes grow to whatever the frame asked for, and+/// without this cap that reaches the GPU maximum (16384² = 1GiB) before+/// image downscaling is even attempted. A request past the cap is handled+/// as an allocation failure -- the atlas is cleared in place and+/// `AllowImage` advances -- never by silently rounding the request down,+/// which would rebuild at the same size, succeed, and overflow again on the+/// next pass forever. (Startup lands at 512; 2048 is a conservative floor+/// for any future shrink, not the initial state.)+pub(crate) const MAX_ATLAS_SIZE: usize = 8192;++/// How many atlas-driven repaints one frame may take before it gives up and+/// keeps the previous frame on screen. The worst legitimate case is four+/// doublings up to the cap, one clear, and four image downscale steps.+pub(crate) const MAX_ATLAS_RETRIES: usize = 10;++/// Once a frame had to downscale images to fit the atlas, later frames+/// start at that level for this long instead of probing full size every+/// frame. When it lapses the downscaled sprites are evicted from the frame+/// cache (it is keyed by hash alone and would otherwise keep serving them),+/// the next frame probes full size, and the hold re-arms if that overflows.+pub(crate) const ATLAS_SCALE_HOLD: Duration = Duration::from_secs(30);++/// How many atlas overflow events the memory report keeps.+const ATLAS_OVERFLOW_LOG_LEN: usize = 32;++/// One atlas overflow, kept so the memory report can say what the window+/// was showing when the atlas had to grow or clear.+#[derive(Debug, Clone, Copy)]+pub(crate) struct AtlasOverflowRecord {+ pub at: Instant,+ pub pass: usize,+ pub have: usize,+ pub want: usize,+ pub action: &'static str,+ pub scene: &'static str,+}+/// How long a full-window view takes to arrive or leave.////// Shorter than the Space swipe settle: that one continues a gesture the hand@@ -2446,6 +2485,11 @@ pub struct TermWindow {/// We use this to attempt to do something reasonable/// if we run out of texture spaceallow_images: AllowImage,+ /// Image downscale level carried across frames after an atlas overflow,+ /// and when it was armed. See [`ATLAS_SCALE_HOLD`].+ atlas_scale_hold: Option<(AllowImage, Instant)>,+ /// Recent atlas overflow events, oldest first, for the memory report.+ atlas_overflow_log: std::collections::VecDeque<AtlasOverflowRecord>,scheduled_animation: RefCell<Option<Instant>>,/// Single-flight latch for the unfocused repaint throttle: the@@ -2470,6 +2514,39 @@ pub struct TermWindow {}impl TermWindow {+ /// 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 {+ if self.content_view_transition_running() {+ "transition"+ } else if self.content_view_foreground() {+ "content_view"+ } else {+ "terminal"+ }+ }++ pub(crate) fn note_atlas_overflow(+ &mut self,+ pass: usize,+ have: usize,+ want: usize,+ action: &'static str,+ ) {+ let scene = self.atlas_scene();+ if self.atlas_overflow_log.len() >= ATLAS_OVERFLOW_LOG_LEN {+ self.atlas_overflow_log.pop_front();+ }+ self.atlas_overflow_log.push_back(AtlasOverflowRecord {+ at: Instant::now(),+ pass,+ have,+ want,+ action,+ scene,+ });+ }+pub(crate) fn memory_resource_lines(&self, label: &str) -> Vec<String> {let backend = if self.webgpu.is_some() {"WebGpu"@@ -2510,9 +2587,65 @@ impl TermWindow {"{label}: layers={} vertex_buffers={} quad_capacity={} line_glyphs={}",stats.layers, stats.vertex_buffers, stats.layer_quads, stats.line_glyphs));+ // RGBA texels -> MiB. Packed area is a high-water mark since the+ // last clear (the allocator never frees a rectangle), so+ // "used" means "was packed", not "is on screen".+ let mib = |px: u64| px as f64 * 4.0 / (1024.0 * 1024.0);+ let usage = stats.atlas_usage;+ let capacity_px = (stats.atlas_size * stats.atlas_size) as u64;+ let percent = if capacity_px == 0 {+ 0.0+ } else {+ usage.allocated_px as f64 * 100.0 / capacity_px as f64+ };+ let tag = |t: ::window::bitmaps::atlas::AtlasTag| {+ let u = usage.tag(t);+ format!("{:.1}MiB/{}", mib(u.allocated_px), u.allocations)+ };+ lines.push(format!(+ "{label}: atlas_packed={:.1}MiB/{:.0}MiB ({percent:.0}%) glyph={} image={} other(icons/blocks/lines/util)={} max_rect={}x{} failures={}",+ mib(usage.allocated_px),+ mib(capacity_px),+ tag(::window::bitmaps::atlas::AtlasTag::Glyph),+ tag(::window::bitmaps::atlas::AtlasTag::Image),+ tag(::window::bitmaps::atlas::AtlasTag::Other),+ usage.max_rect.0,+ usage.max_rect.1,+ usage.failures,+ ));+ lines.push(format!(+ "{label}: recent_images=[{}]",+ stats.recent_image_allocs.join("; ")+ ));} else {lines.push(format!("{label}: render_state=none"));}+ {+ let now = Instant::now();+ let recent: Vec<String> = self+ .atlas_overflow_log+ .iter()+ .rev()+ .take(8)+ .map(|r| {+ format!(+ "{}s:p{} {}->{} {} {}",+ now.saturating_duration_since(r.at).as_secs(),+ r.pass,+ r.have,+ r.want,+ r.action,+ r.scene+ )+ })+ .collect();+ lines.push(format!(+ "{label}: atlas_overflows={} scale_hold={:?} recent=[{}]",+ self.atlas_overflow_log.len(),+ self.atlas_scale_hold.map(|(level, _)| level),+ recent.join("; ")+ ));+ }lines.push(format!("{label}: caches shape={} ({}KiB) line_state={} ({}KiB) line_quad={} ({}KiB) line_to_element_shape={} ({}KiB) pane_font={} semantic_zones={}",@@ -3364,6 +3497,8 @@ impl TermWindow {unfocused_invalidate_due: None,unfocused_next_allowed: Instant::now(),allow_images: AllowImage::Yes,+ atlas_scale_hold: None,+ atlas_overflow_log: std::collections::VecDeque::new(),semantic_zones: HashMap::new(),ui_items: vec![],context_menu: None,diff --git a/wezterm-gui/src/termwindow/render/paint.rs b/wezterm-gui/src/termwindow/render/paint.rsindex d0dc14cf..5037d7f2 100644--- a/wezterm-gui/src/termwindow/render/paint.rs+++ b/wezterm-gui/src/termwindow/render/paint.rs@@ -446,6 +446,89 @@ pub enum AllowImage {No,}+impl AllowImage {+ /// The next coarser level after an atlas overflow, or None when there+ /// is nothing left to give up.+ fn coarser(self) -> Option<AllowImage> {+ match self {+ AllowImage::Yes => Some(AllowImage::Scale(2)),+ AllowImage::Scale(2) => Some(AllowImage::Scale(4)),+ AllowImage::Scale(4) => Some(AllowImage::Scale(8)),+ AllowImage::Scale(_) => Some(AllowImage::No),+ AllowImage::No => None,+ }+ }+}++/// What the overflow handler does about an atlas that could not fit the+/// frame. Pure so the freeze case below can be pinned by a test.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub(crate) enum AtlasAction {+ /// Rebuild at this larger size.+ Grow(usize),+ /// Rebuild at the current size to evict sprites no frame needs any more.+ ClearInPlace,+ /// The frame wants more than the cap allows. Handled as an allocation+ /// failure: clear in place and downscale images. Never rounded down to+ /// the cap -- at the cap that rebuild would succeed, skip the downscale+ /// step, and overflow identically on the next pass, forever.+ CapExceeded,+}++/// `pass` is the ordinal of this atlas overflow within the frame (0 for+/// the first), not the paint loop's pass counter, which also advances on+/// quad-growth and shape-cache retries.+///+/// First overflow: grow while there is headroom under `grow_ceiling` rather+/// than clearing in place. Clearing answers "the atlas is full of glyphs we+/// no longer need"; it is the wrong answer to "the working set does not+/// fit", because the frame that overflowed fits once the atlas is empty, so+/// the growth branch is never reached and the next frame that wants the+/// same glyphs overflows again -- toggling the overview used to clear the+/// atlas every single time. At the ceiling, clearing is all that is left,+/// and it is also what reclaims the one-off glyphs a closed overview leaves+/// behind.+///+/// Later overflows: the working set did not fit even after a clear, so grow+/// to what the frame asked for -- up to `cap`, past which the request is a+/// failure (see [`AtlasAction::CapExceeded`]).+pub(crate) fn atlas_overflow_action(+ pass: usize,+ current: usize,+ wanted: usize,+ grow_ceiling: usize,+ cap: usize,+) -> AtlasAction {+ if pass == 0 {+ let grown = wanted.min(grow_ceiling);+ if grown > current {+ AtlasAction::Grow(grown)+ } else {+ AtlasAction::ClearInPlace+ }+ } else if wanted > cap {+ AtlasAction::CapExceeded+ } else if wanted > current {+ AtlasAction::Grow(wanted)+ } else {+ AtlasAction::ClearInPlace+ }+}++/// The image level a frame starts at, and the hold to carry forward: a+/// downscale forced by an earlier overflow holds for `hold_for`, after+/// which the next frame probes full size again.+pub(crate) fn sticky_allow_images(+ hold: Option<(AllowImage, Instant)>,+ now: Instant,+ hold_for: Duration,+) -> (AllowImage, Option<(AllowImage, Instant)>) {+ match hold {+ Some((level, since)) if now.saturating_duration_since(since) < hold_for => (level, hold),+ _ => (AllowImage::Yes, None),+ }+}+impl crate::TermWindow {fn paint_frontend_handoff_overlay(&mut self,@@ -647,8 +730,28 @@ impl crate::TermWindow {// If nothing on screen needs animating, then we can avoid// invalidating as frequently*self.has_animation.borrow_mut() = None;- // Start with the assumption that we should allow images to render- self.allow_images = AllowImage::Yes;+ // Start at full-size images unless a recent overflow forced a+ // downscale; that level holds for ATLAS_SCALE_HOLD so the frames+ // after it do not each re-probe full size and overflow again.+ let had_hold = self.atlas_scale_hold.is_some();+ let (allow_images, hold) = sticky_allow_images(+ self.atlas_scale_hold,+ Instant::now(),+ crate::termwindow::ATLAS_SCALE_HOLD,+ );+ self.allow_images = allow_images;+ self.atlas_scale_hold = hold;+ if had_hold && hold.is_none() {+ // The hold lapsed: drop the downscaled sprites so this frame+ // really does re-probe full size. The frame cache is keyed by+ // hash alone and would otherwise keep serving the small copies.+ if let Some(render_state) = self.render_state.as_ref() {+ let evicted = render_state.evict_scaled_image_frames();+ if evicted > 0 {+ log::trace!("atlas downscale hold lapsed; evicted {evicted} scaled frames");+ }+ }+ }let start = Instant::now();self.advance_tab_scroll_animation(start);@@ -682,6 +785,7 @@ impl crate::TermWindow {// half a second of nothing.const MAX_SHAPE_CACHE_RETRIES: usize = 1;let mut shape_retries = 0usize;+ let mut atlas_retries = 0usize;// Cleared when the retry cap gives up on this frame: the quad buffers// then hold however much of the window the aborted pass got through,// and presenting that paints the terminal without its chrome for the@@ -731,36 +835,81 @@ impl crate::TermWindow {"paint_retry_atlas",format!("pass={pass} have={current_size} want={size}"),);- let result = if pass == 0 {- // Grow while there is headroom, rather than- // clearing in place.- //- // Clearing answers "the atlas is full of glyphs we- // no longer need". It is the wrong answer to "the- // working set does not fit": the frame that- // overflowed fits once the atlas is empty, so this- // never reached the growth branch below, and the- // next frame that wants the same glyphs overflows- // again. Toggling the overview cleared the atlas- // every single time, re-rasterising every glyph on- // screen -- and taking the recorded transition- // frames, whose texture coordinates the rebuild- // invalidates, with it.- let grown = size.min(crate::termwindow::MAX_GROWN_ATLAS_SIZE);- if grown > current_size {- log::trace!("grow texture atlas {current_size} -> {grown}");- self.recreate_texture_atlas(Some(grown))- } else {- // At the ceiling: clearing is all that is left,- // and it is also what reclaims the one-off- // glyphs a closed overview leaves behind.+ atlas_retries += 1;+ if atlas_retries > crate::termwindow::MAX_ATLAS_RETRIES {+ // Keep the previous complete frame rather than+ // present a half-built one (only WebGpu can skip+ // the present; glium swaps regardless). Unlike+ // the shape-retry cap below this does NOT+ // re-invalidate: clearing shape caches changes+ // the next frame, but a working set that will+ // not fit at the cap even with images downscaled+ // paints identically, and re-arming would turn+ // every vsync into ten atlas rebuilds.+ crate::perf::log_counter("paint_atlas_retry_capped", atlas_retries);+ log::error!(+ "texture atlas: {atlas_retries} rebuilds in one frame \+ (have={current_size} want={size}); keeping the previous frame"+ );+ self.note_atlas_overflow(pass, current_size, size, "gave-up");+ present_frame = false;+ break 'pass;+ }+ // The outer `pass` also counts quad-growth and+ // shape-cache retries, so the first *atlas* overflow+ // of a frame is not necessarily pass 0. The policy+ // wants the atlas overflow ordinal.+ let action = atlas_overflow_action(+ atlas_retries - 1,+ current_size,+ size,+ crate::termwindow::MAX_GROWN_ATLAS_SIZE,+ crate::termwindow::MAX_ATLAS_SIZE,+ );+ let (result, action_name) = match action {+ AtlasAction::Grow(grown) => {+ // Growth up to the first-pass ceiling is+ // routine (startup climbs 128 -> 512 this+ // way); only growth past it is the event+ // worth a default-level log line.+ if grown > crate::termwindow::MAX_GROWN_ATLAS_SIZE {+ log::warn!(+ "texture atlas grow {current_size}->{grown} pass={pass} scene={}",+ self.atlas_scene()+ );+ } else {+ log::trace!("grow texture atlas {current_size} -> {grown}");+ }+ (self.recreate_texture_atlas(Some(grown)), "grow")+ }+ AtlasAction::ClearInPlace => {log::trace!("recreate_texture_atlas at {current_size}");- self.recreate_texture_atlas(Some(current_size))+ (self.recreate_texture_atlas(Some(current_size)), "clear")+ }+ AtlasAction::CapExceeded => {+ log::warn!(+ "texture atlas wants {size} texels per side, past the {} cap \+ (have {current_size}); clearing and downscaling images, pass={pass} scene={}",+ crate::termwindow::MAX_ATLAS_SIZE,+ self.atlas_scene()+ );+ // Clear first: the frame cache would otherwise+ // keep handing out the full-size sprites by+ // hash and the downscaled retry would change+ // nothing. Then take the failure path below.+ let cleared = self.recreate_texture_atlas(Some(current_size));+ (+ cleared.and_then(|()| {+ Err(anyhow::anyhow!(+ "texture atlas cap {} exceeded (wanted {size})",+ crate::termwindow::MAX_ATLAS_SIZE+ ))+ }),+ "cap",+ )}- } else {- log::trace!("grow texture atlas to {}", size);- self.recreate_texture_atlas(Some(size))};+ self.note_atlas_overflow(pass, current_size, size, action_name);self.invalidate_fancy_tab_bar();self.invalidate_modal();// Captured sidebars hold atlas UV coordinates, not@@ -772,20 +921,35 @@ impl crate::TermWindow {self.discard_content_view_captures_after_atlas_recreation();if let Err(err) = result {- self.allow_images = match self.allow_images {- AllowImage::Yes => AllowImage::Scale(2),- AllowImage::Scale(2) => AllowImage::Scale(4),- AllowImage::Scale(4) => AllowImage::Scale(8),- AllowImage::Scale(8) => AllowImage::No,- AllowImage::No | _ => {+ if !matches!(action, AtlasAction::CapExceeded) {+ // The rebuild failed at the GPU (limit or+ // memory) and left the old atlas in place,+ // full-size sprites included. Clear it so the+ // downscaled retry does not just hit them by+ // hash and overflow the same way.+ if let Err(clear_err) =+ self.recreate_texture_atlas(Some(current_size))+ {log::error!(- "Failed to {} texture: {}",- if pass == 0 { "clear" } else { "resize" },- err+ "texture atlas clear after failed resize also failed: {clear_err:#}");- break 'pass;}+ }+ let Some(coarser) = self.allow_images.coarser() else {+ log::error!(+ "Failed to {} texture: {}",+ if pass == 0 { "clear" } else { "resize" },+ err+ );+ // Nothing left to give up. The atlas was just+ // cleared (or the rebuild failed), so the+ // quads built this pass point at a zeroed or+ // stale texture: keep the previous frame.+ present_frame = false;+ break 'pass;};+ self.allow_images = coarser;+ self.atlas_scale_hold = Some((coarser, Instant::now()));log::info!("Not enough texture space ({:#}); \@@ -4092,3 +4256,91 @@ mod tests {);}}++#[cfg(test)]+mod atlas_policy_tests {+ use super::{atlas_overflow_action, sticky_allow_images, AllowImage, AtlasAction};+ use std::time::{Duration, Instant};++ const CEIL: usize = 2048;+ const CAP: usize = 8192;++ #[test]+ fn first_pass_grows_only_up_to_the_ceiling() {+ assert_eq!(+ atlas_overflow_action(0, 512, 1024, CEIL, CAP),+ AtlasAction::Grow(1024)+ );+ assert_eq!(+ atlas_overflow_action(0, 1024, 4096, CEIL, CAP),+ AtlasAction::Grow(CEIL)+ );+ }++ #[test]+ fn first_pass_at_or_past_the_ceiling_clears_in_place() {+ assert_eq!(+ atlas_overflow_action(0, CEIL, 4096, CEIL, CAP),+ AtlasAction::ClearInPlace+ );+ assert_eq!(+ atlas_overflow_action(0, CAP, 16384, CEIL, CAP),+ AtlasAction::ClearInPlace+ );+ }++ #[test]+ fn retry_passes_grow_to_the_request_within_the_cap() {+ assert_eq!(+ atlas_overflow_action(1, CEIL, 4096, CEIL, CAP),+ AtlasAction::Grow(4096)+ );+ assert_eq!(+ atlas_overflow_action(2, 4096, CAP, CEIL, CAP),+ AtlasAction::Grow(CAP)+ );+ }++ #[test]+ fn a_request_past_the_cap_is_a_failure_not_a_rounding() {+ // The freeze case: already at the cap, asked for more. Rounding to+ // the cap would rebuild at the same size, succeed, and overflow+ // identically on the next pass.+ assert_eq!(+ atlas_overflow_action(1, CAP, 16384, CEIL, CAP),+ AtlasAction::CapExceeded+ );+ assert_eq!(+ atlas_overflow_action(1, 4096, 16384, CEIL, CAP),+ AtlasAction::CapExceeded+ );+ }++ #[test]+ fn downscale_levels_end_at_no_images() {+ assert_eq!(AllowImage::Yes.coarser(), Some(AllowImage::Scale(2)));+ assert_eq!(AllowImage::Scale(2).coarser(), Some(AllowImage::Scale(4)));+ assert_eq!(AllowImage::Scale(4).coarser(), Some(AllowImage::Scale(8)));+ assert_eq!(AllowImage::Scale(8).coarser(), Some(AllowImage::No));+ assert_eq!(AllowImage::No.coarser(), None);+ }++ #[test]+ fn sticky_hold_carries_the_level_until_it_lapses() {+ let armed = Instant::now();+ let hold = Some((AllowImage::Scale(2), armed));+ let hold_for = Duration::from_secs(30);++ let (level, kept) = sticky_allow_images(hold, armed + Duration::from_secs(10), hold_for);+ assert_eq!(level, AllowImage::Scale(2));+ assert_eq!(kept, hold);++ let (level, kept) = sticky_allow_images(hold, armed + Duration::from_secs(31), hold_for);+ assert_eq!(level, AllowImage::Yes);+ assert_eq!(kept, None);++ let (level, kept) = sticky_allow_images(None, armed, hold_for);+ assert_eq!(level, AllowImage::Yes);+ assert_eq!(kept, None);+ }+}diff --git a/wezterm-gui/src/termwindow/ui/right_sidebar.rs b/wezterm-gui/src/termwindow/ui/right_sidebar.rsindex 048d147b..c167eb32 100644--- a/wezterm-gui/src/termwindow/ui/right_sidebar.rs+++ b/wezterm-gui/src/termwindow/ui/right_sidebar.rs@@ -9404,6 +9404,11 @@ impl crate::TermWindow {let Some(gl_state) = self.render_state.as_ref() else {return Ok(());};+ // Same rule as terminal-cell images: once the atlas overflow chain+ // reached `No`, nothing uploads a picture this frame.+ if self.allow_images == crate::termwindow::render::paint::AllowImage::No {+ return Ok(());+ }let (sprite, next_due, _load_state) = gl_state.glyph_cache.borrow_mut()@@ -15463,6 +15468,9 @@ impl crate::TermWindow {let draw_x = metrics.x as f32 + (max_width - draw_width) / 2.0;let draw_y = metrics.y as f32 + (max_height - draw_height) / 2.0;+ if self.allow_images == crate::termwindow::render::paint::AllowImage::No {+ return Ok(());+ }let gl_state = self.render_state.as_ref().unwrap();let (sprite, next_due, _load_state) = gl_state.glyph_cachediff --git a/window/src/bitmaps/atlas.rs b/window/src/bitmaps/atlas.rsindex d8b37066..41541364 100644--- a/window/src/bitmaps/atlas.rs+++ b/window/src/bitmaps/atlas.rs@@ -15,6 +15,71 @@ pub struct OutOfTextureSpace {pub current_size: usize,}+/// Who asked for the sprite. The atlas cannot tell a glyph from a kitty+/// frame, so callers tag their allocations and the usage report splits+/// the packed area by tag.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum AtlasTag {+ Glyph,+ Image,+ Other,+}++impl AtlasTag {+ fn index(self) -> usize {+ match self {+ AtlasTag::Glyph => 0,+ AtlasTag::Image => 1,+ AtlasTag::Other => 2,+ }+ }+}++#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]+pub struct AtlasTagUsage {+ pub allocated_px: u64,+ pub allocations: u32,+}++/// Packing accounting since the last `clear()`. `allocated_px` is the+/// padded reservation area and only ever grows: the allocator cannot+/// release a single rectangle, so this is the high-water mark of what+/// was packed, not the live working set. `max_rect` is the largest single+/// reservation (padded, width x height), the number that decides whether+/// a smaller atlas could have held the same content at all.+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]+pub struct AtlasUsage {+ pub allocated_px: u64,+ pub allocations: u32,+ pub per_tag: [AtlasTagUsage; 3],+ pub max_rect: (i32, i32),+ pub failures: u32,+}++impl AtlasUsage {+ pub fn tag(&self, tag: AtlasTag) -> AtlasTagUsage {+ self.per_tag[tag.index()]+ }++ fn record_success(&mut self, tag: AtlasTag, width: i32, height: i32) {+ let area = width as u64 * height as u64;+ self.allocated_px += area;+ self.allocations += 1;+ let slot = &mut self.per_tag[tag.index()];+ slot.allocated_px += area;+ slot.allocations += 1;+ // Largest by longest side, not by area: the longest side is what+ // sets the smallest square atlas that could hold the reservation+ // (a 3000x1 strip needs a 4096 atlas; a 100x100 square does not).+ let side = width.max(height);+ let current_side = self.max_rect.0.max(self.max_rect.1);+ let current_area = self.max_rect.0 as u64 * self.max_rect.1 as u64;+ if side > current_side || (side == current_side && area > current_area) {+ self.max_rect = (width, height);+ }+ }+}+/// Atlases are bitmaps of srgba data that are sized as a power of 2./// We allocate sprites out of the available space, using AtlasAllocator/// to manage the available rectangles.@@ -25,6 +90,8 @@ pub struct Atlas {/// Dimensions of the textureside: usize,++ usage: AtlasUsage,}impl Atlas {@@ -46,6 +113,7 @@ impl Atlas {texture: Rc::clone(texture),side,allocator,+ usage: AtlasUsage::default(),})}@@ -64,6 +132,18 @@ impl Atlas {im: &dyn BitmapImage,padding: Option<usize>,scale_down: Option<usize>,+ ) -> Result<Sprite, OutOfTextureSpace> {+ self.allocate_tagged(im, padding, scale_down, AtlasTag::Other)+ }++ /// Reserve space for a sprite, attributing the packed area to `tag`+ /// in the usage report.+ pub fn allocate_tagged(+ &mut self,+ im: &dyn BitmapImage,+ padding: Option<usize>,+ scale_down: Option<usize>,+ tag: AtlasTag,) -> Result<Sprite, OutOfTextureSpace> {let (width, height) = im.image_dimensions();@@ -71,9 +151,11 @@ impl Atlas {let mut copied = crate::Image::new(width, height);copied.draw_image(Point::new(0, 0), None, im);- let scaled = copied.resize(width / scale_down, height / scale_down);+ // A source smaller than the divisor must not become 0x0: the+ // sprite's dimensions feed texture-coordinate divisions.+ let scaled = copied.resize((width / scale_down).max(1), (height / scale_down).max(1));- return self.allocate_with_padding(&scaled, padding, None);+ return self.allocate_tagged(&scaled, padding, None, tag);}// If we can't convert the sizes to i32, then we'll never@@ -106,6 +188,8 @@ impl Atlas {);self.texture.write(rect, im);+ self.usage+ .record_success(tag, reserve_width, reserve_height);metrics::histogram!("window.atlas.allocate.success.rate").record(1.);Ok(Sprite {@@ -115,6 +199,7 @@ impl Atlas {} else {// It's not possible to satisfy that requestlet size = (reserve_width.max(reserve_height) as usize).next_power_of_two();+ self.usage.failures += 1;metrics::histogram!("window.atlas.allocate.failure.rate").record(1.);Err(OutOfTextureSpace {size: Some((self.side * 2).max(size)),@@ -130,6 +215,11 @@ impl Atlas {self.side}+ /// Packing accounting since the last `clear()`.+ pub fn usage(&self) -> AtlasUsage {+ self.usage+ }+/// Zero out the texture, and forget all allocated regionspub fn clear(&mut self) {let iside = self.side as isize;@@ -137,6 +227,7 @@ impl Atlas {let rect = Rect::new(Point::new(0, 0), Size::new(iside, iside));self.texture.write(rect, &image);self.allocator.clear();+ self.usage = AtlasUsage::default();}}@@ -170,3 +261,88 @@ impl Sprite {self.texture.to_texture_coords(self.coords)}}++#[cfg(test)]+mod usage_tests {+ use super::{Atlas, AtlasTag, AtlasUsage, PADDING};+ use crate::bitmaps::{ImageTexture, Texture2d};+ use std::rc::Rc;++ fn atlas(side: usize) -> Atlas {+ let texture: Rc<dyn Texture2d> = Rc::new(ImageTexture::new(side, side));+ Atlas::new(&texture).unwrap()+ }++ fn padded(w: usize, h: usize) -> (i32, i32) {+ (w as i32 + PADDING * 2, h as i32 + PADDING * 2)+ }++ #[test]+ fn accounts_padded_area_per_tag_and_tracks_the_largest_rect() {+ let mut atlas = atlas(64);+ let glyph = crate::Image::new(10, 10);+ let frame = crate::Image::new(20, 5);+ atlas+ .allocate_tagged(&glyph, None, None, AtlasTag::Glyph)+ .unwrap();+ atlas+ .allocate_tagged(&frame, None, None, AtlasTag::Image)+ .unwrap();+ atlas.allocate(&glyph).unwrap();++ let (gw, gh) = padded(10, 10);+ let (fw, fh) = padded(20, 5);+ let glyph_px = (gw * gh) as u64;+ let frame_px = (fw * fh) as u64;++ let usage = atlas.usage();+ assert_eq!(usage.allocations, 3);+ assert_eq!(usage.allocated_px, glyph_px * 2 + frame_px);+ assert_eq!(usage.tag(AtlasTag::Glyph).allocations, 1);+ assert_eq!(usage.tag(AtlasTag::Glyph).allocated_px, glyph_px);+ assert_eq!(usage.tag(AtlasTag::Image).allocated_px, frame_px);+ assert_eq!(usage.tag(AtlasTag::Other).allocated_px, glyph_px);+ assert_eq!(usage.max_rect, (fw, fh));+ assert_eq!(usage.failures, 0);+ }++ #[test]+ fn max_rect_follows_the_longest_side_not_the_area() {+ let mut atlas = atlas(256);+ atlas+ .allocate_tagged(&crate::Image::new(200, 1), None, None, AtlasTag::Image)+ .unwrap();+ atlas+ .allocate_tagged(&crate::Image::new(50, 50), None, None, AtlasTag::Glyph)+ .unwrap();+ // 52x52 has the larger area, but 202x3 is what forces the atlas side.+ assert_eq!(atlas.usage().max_rect, padded(200, 1));+ }++ #[test]+ fn scaled_allocations_account_the_scaled_rect() {+ let mut atlas = atlas(64);+ let big = crate::Image::new(40, 40);+ atlas+ .allocate_tagged(&big, None, Some(2), AtlasTag::Image)+ .unwrap();+ let (w, h) = padded(20, 20);+ assert_eq!(atlas.usage().max_rect, (w, h));+ assert_eq!(+ atlas.usage().tag(AtlasTag::Image).allocated_px,+ (w * h) as u64+ );+ }++ #[test]+ fn failures_count_and_clear_resets_everything() {+ let mut atlas = atlas(32);+ atlas.allocate(&crate::Image::new(8, 8)).unwrap();+ assert!(atlas.allocate(&crate::Image::new(100, 100)).is_err());+ assert_eq!(atlas.usage().failures, 1);+ assert_eq!(atlas.usage().allocations, 1);++ atlas.clear();+ assert_eq!(atlas.usage(), AtlasUsage::default());+ }+}