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: record each line's quads into one scratch recorder, cached at exact size

RoversXf7b8910ee26f
diff --git a/thinkterm-render/src/quad.rs b/thinkterm-render/src/quad.rs
index aeeb86d6..6baa44d3 100644
--- a/thinkterm-render/src/quad.rs
+++ b/thinkterm-render/src/quad.rs
@@ -718,6 +718,35 @@ impl HeapQuadAllocator {
self.position_transform = None;
}
+ /// Move the recording into a new allocator whose vectors have no spare
+ /// capacity, leaving this one empty but keeping its buffers for whatever
+ /// is recorded next.
+ ///
+ /// This is how a scratch recorder hands a finished surface to a
+ /// byte-accounted cache. `resident_bytes()` counts capacity, so a buffer
+ /// that grew by doubling would charge the cache ~33% more than it holds
+ /// and keep that hole resident for the life of the entry. The quads are
+ /// moved, not cloned: `BoxedQuad::clone` deep-copies every corner
+ /// gradient box, so a clone would trade the doubling slack for an
+ /// allocation per gradient quad.
+ pub fn take_exact(&mut self) -> Self {
+ fn drain_exact(src: &mut Vec<BoxedQuad>) -> Vec<BoxedQuad> {
+ // with_capacity + extend rather than collect: the exactness is
+ // the point, and must not depend on an iterator specialisation.
+ let mut out = Vec::with_capacity(src.len());
+ out.extend(src.drain(..));
+ out
+ }
+ let out = Self {
+ layer0: drain_exact(&mut self.layer0),
+ layer1: drain_exact(&mut self.layer1),
+ layer2: drain_exact(&mut self.layer2),
+ position_transform: self.position_transform,
+ };
+ self.position_transform = None;
+ out
+ }
+
/// Estimated resident heap bytes for the recorded quads. Counts vector
/// capacity, not length: a buffer that grew during recording keeps that
/// allocation until it is dropped, and capacity is what a byte-accounted
@@ -1033,6 +1062,7 @@ impl TripleLayerQuadAllocatorTrait for HeapQuadAllocator {
let src_quads: &[[Vertex; VERTICES_PER_CELL]] =
unsafe { std::slice::from_raw_parts(vertices.as_ptr().cast(), vertices.len() / 4) };
+ dest_quads.reserve(src_quads.len());
for quad in src_quads {
let mut quad = BoxedQuad::from_vertices(quad);
if let Some(transform) = position_transform {
@@ -1058,6 +1088,121 @@ fn size() {
assert_eq!(std::mem::size_of::<BoxedQuad>(), 96);
}
+#[cfg(test)]
+fn record_quads(heap: &mut HeapQuadAllocator, per_layer: [usize; 3]) {
+ let mut layers = heap;
+ for (layer_num, count) in per_layer.into_iter().enumerate() {
+ for i in 0..count {
+ let x = (layer_num * 1000 + i * 10) as f32;
+ let mut quad = layers.allocate(layer_num).unwrap();
+ quad.set_position(x, 0.0, x + 5.0, 5.0);
+ }
+ }
+}
+
+#[cfg(test)]
+#[test]
+fn take_exact_produces_exact_capacity_and_keeps_the_scratch_buffers() {
+ let mut scratch = HeapQuadAllocator::default();
+ record_quads(&mut scratch, [5, 3, 0]);
+ let grown = scratch.resident_bytes();
+ // Doubling from zero leaves slack behind; that slack is the point.
+ assert!(grown > 8 * std::mem::size_of::<BoxedQuad>());
+
+ let out = scratch.take_exact();
+ assert_eq!(out.quad_count(), 8);
+ assert_eq!(out.resident_bytes(), 8 * std::mem::size_of::<BoxedQuad>());
+ assert_eq!(scratch.quad_count(), 0);
+ assert_eq!(scratch.resident_bytes(), grown, "the scratch keeps its buffers");
+}
+
+#[cfg(test)]
+#[test]
+fn take_exact_preserves_layer_assignment_and_recorded_order() {
+ let mut scratch = HeapQuadAllocator::default();
+ record_quads(&mut scratch, [2, 1, 3]);
+ let out = scratch.take_exact();
+ assert_eq!(out.layer0.len(), 2);
+ assert_eq!(out.layer1.len(), 1);
+ assert_eq!(out.layer2.len(), 3);
+ assert_eq!(out.layer0[1].position, (10.0, 0.0, 15.0, 5.0));
+ assert_eq!(out.layer1[0].position, (1000.0, 0.0, 1005.0, 5.0));
+ assert_eq!(out.layer2[2].position, (2020.0, 0.0, 2025.0, 5.0));
+}
+
+#[cfg(test)]
+#[test]
+fn take_exact_moves_corner_gradients_intact() {
+ let mut scratch = HeapQuadAllocator::default();
+ {
+ let mut layers = &mut scratch;
+ let mut quad = layers.allocate(1).unwrap();
+ quad.set_corner_gradient(
+ LinearRgba::with_components(0.1, 0.0, 0.0, 1.0),
+ LinearRgba::with_components(0.2, 0.0, 0.0, 1.0),
+ LinearRgba::with_components(0.3, 0.0, 0.0, 1.0),
+ LinearRgba::with_components(0.4, 0.0, 0.0, 1.0),
+ );
+ }
+ let out = scratch.take_exact();
+ let vertices = out.layer1[0].to_vertices();
+ assert_eq!(vertices[V_TOP_LEFT].fg_color, [0.1, 0.0, 0.0, 1.0]);
+ assert_eq!(vertices[V_TOP_RIGHT].fg_color, [0.2, 0.0, 0.0, 1.0]);
+ assert_eq!(vertices[V_BOT_LEFT].fg_color, [0.3, 0.0, 0.0, 1.0]);
+ assert_eq!(vertices[V_BOT_RIGHT].fg_color, [0.4, 0.0, 0.0, 1.0]);
+}
+
+#[cfg(test)]
+#[test]
+fn a_recycled_scratch_records_the_same_surface_as_a_fresh_allocator() {
+ let line_a = [4usize, 7, 1];
+ let mut fresh = HeapQuadAllocator::default();
+ record_quads(&mut fresh, line_a);
+
+ // A wider line first, so the scratch's buffers are larger than line A
+ // needs when it is recorded second.
+ let mut scratch = HeapQuadAllocator::default();
+ record_quads(&mut scratch, [40, 70, 10]);
+ let _wide = scratch.take_exact();
+ scratch.recycle();
+ record_quads(&mut scratch, line_a);
+ let reused = scratch.take_exact();
+
+ let (mut expected, mut actual) = (Vec::new(), Vec::new());
+ fresh.extract_vertices(&mut expected);
+ reused.extract_vertices(&mut actual);
+ assert_eq!(actual.len(), expected.len());
+ for (a, e) in actual.iter().zip(expected.iter()) {
+ assert_eq!(a.position, e.position);
+ assert_eq!(a.fg_color, e.fg_color);
+ assert_eq!(a.tex, e.tex);
+ }
+ assert_eq!(reused.quad_count(), fresh.quad_count());
+ assert_eq!(reused.resident_bytes(), 12 * std::mem::size_of::<BoxedQuad>());
+}
+
+#[cfg(test)]
+#[test]
+fn take_exact_clears_the_position_transform() {
+ let source = QuadClipRect::from_top_left_pixels(0.0, 0.0, 100.0, 100.0, &TEST_ORIGIN);
+ let target = QuadClipRect::from_top_left_pixels(0.0, 0.0, 200.0, 200.0, &TEST_ORIGIN);
+ let mut scratch = HeapQuadAllocator::default();
+ {
+ let mut layers = &mut scratch;
+ layers.set_position_transform(Some(QuadPositionTransform::new(source, target).unwrap()));
+ let mut quad = layers.allocate(0).unwrap();
+ quad.set_position(10.0, 10.0, 20.0, 20.0);
+ }
+ let out = scratch.take_exact();
+ assert_eq!(out.layer0[0].position, (20.0, 20.0, 40.0, 40.0));
+ {
+ let mut layers = &mut scratch;
+ let mut quad = layers.allocate(0).unwrap();
+ quad.set_position(10.0, 10.0, 20.0, 20.0);
+ }
+ assert_eq!(scratch.layer0[0].position, (10.0, 10.0, 20.0, 20.0));
+}
+
#[cfg(test)]
#[test]
fn boxed_quad_preserves_vertical_gradient_colors() {
diff --git a/wezterm-gui/src/glyphcache.rs b/wezterm-gui/src/glyphcache.rs
index 14cef0d1..2768be9f 100644
--- a/wezterm-gui/src/glyphcache.rs
+++ b/wezterm-gui/src/glyphcache.rs
@@ -662,6 +662,13 @@ pub struct GlyphCacheStats {
}
impl GlyphCache {
+ /// Entry count only; `stats()` builds strings and is not per-frame
+ /// material. This is the counter for the one unbounded map in the
+ /// renderer, which is only cleared when the atlas is rebuilt.
+ pub fn glyph_entries(&self) -> usize {
+ self.glyph_cache.len()
+ }
+
pub fn stats(&self) -> GlyphCacheStats {
let now = Instant::now();
GlyphCacheStats {
diff --git a/wezterm-gui/src/termwindow/mod.rs b/wezterm-gui/src/termwindow/mod.rs
index 7de2c025..56b897fd 100644
--- a/wezterm-gui/src/termwindow/mod.rs
+++ b/wezterm-gui/src/termwindow/mod.rs
@@ -2410,6 +2410,19 @@ pub struct TermWindow {
next_line_state_id: u64,
line_quad_cache: RefCell<LfuCache<LineQuadCacheKey, LineQuadCacheValue>>,
+ /// Scratch recorder every line's quads go into before they are moved
+ /// into `line_quad_cache` at exact size. A fresh
+ /// `HeapQuadAllocator::default()` per cache miss reached a line's ~25 KiB
+ /// of quads by doubling from zero: measured 1.5 GiB of alloc/copy/free
+ /// in 15 minutes of a 4 Hz full-screen TUI, with the doubling slack
+ /// then kept resident by the cache. One reused recorder makes the
+ /// steady state allocation-free apart from the exact-size copy that
+ /// becomes the entry.
+ ///
+ /// Exactly one line is recorded at a time: `LineRender::render_line` is
+ /// the only borrower and nothing under `render_screen_line` re-enters
+ /// it, so a double borrow would be a real bug and should panic.
+ line_quad_scratch: RefCell<HeapQuadAllocator>,
last_status_call: Instant,
/// Throttle for `log_gpu_allocator_throttled`; runtime-only diagnostics.
@@ -3434,6 +3447,8 @@ impl TermWindow {
render_state.dedicated_images.borrow_mut().clear();
}
self.line_quad_cache.borrow_mut().clear();
+ // Likewise the scratch recorder: a hidden window records no lines.
+ *self.line_quad_scratch.borrow_mut() = HeapQuadAllocator::default();
// The buffers just dropped stay resident until a device maintain
// runs, and an occluded window submits no frames — poll once so
// the memory actually returns now rather than at the reveal.
@@ -3897,6 +3912,7 @@ impl TermWindow {
line_quad_cache_budget,
&config,
)),
+ line_quad_scratch: RefCell::new(HeapQuadAllocator::default()),
line_to_ele_shape_cache: RefCell::new(LfuCache::new_weighted(
"line_to_ele_shape_cache.hit.rate",
"line_to_ele_shape_cache.miss.rate",
diff --git a/wezterm-gui/src/termwindow/render/mod.rs b/wezterm-gui/src/termwindow/render/mod.rs
index c91bd832..d17c52a5 100644
--- a/wezterm-gui/src/termwindow/render/mod.rs
+++ b/wezterm-gui/src/termwindow/render/mod.rs
@@ -1462,4 +1462,31 @@ mod line_quad_cache_tests {
assert_ne!(wide, key(80, 800));
assert_ne!(wide, key(120, 1_000));
}
+
+ #[test]
+ fn a_cached_line_quad_entry_is_weighed_at_exactly_what_it_holds() {
+ let mut scratch = HeapQuadAllocator::default();
+ {
+ let layers = &mut scratch;
+ for layer_num in [0usize, 1, 1, 1, 2] {
+ let mut quad = layers.allocate(layer_num).unwrap();
+ quad.set_position(0.0, 0.0, 8.0, 16.0);
+ }
+ }
+ let value = LineQuadCacheValue {
+ expires: None,
+ layers: scratch.take_exact(),
+ current_highlight: None,
+ invalidate_on_hover_change: false,
+ };
+ let quads = value.layers.quad_count() * std::mem::size_of::<crate::quad::BoxedQuad>();
+ assert_eq!(value.layers.resident_bytes(), quads, "no doubling slack");
+ assert_eq!(
+ estimate_line_quad_entry_bytes(&key(80, 800), &value),
+ CACHE_ENTRY_FIXED_OVERHEAD
+ + std::mem::size_of::<LineQuadCacheKey>()
+ + std::mem::size_of::<LineQuadCacheValue>()
+ + quads
+ );
+ }
}
diff --git a/wezterm-gui/src/termwindow/render/paint.rs b/wezterm-gui/src/termwindow/render/paint.rs
index 7c1e86c7..63879f07 100644
--- a/wezterm-gui/src/termwindow/render/paint.rs
+++ b/wezterm-gui/src/termwindow/render/paint.rs
@@ -898,6 +898,47 @@ impl crate::TermWindow {
"line_state_cache_bytes",
self.line_state_cache.borrow().total_weight(),
);
+ // The UI shape caches, the glyph map and the
+ // atlas are what the four counters above
+ // cannot see, and together they are the larger
+ // half of the render memory: note alone is
+ // budgeted 32 MiB, file_preview 16, and the
+ // glyph map has no bound at all. Every value
+ // here is a field read or a len(), so unlike
+ // the GPU allocator report below this needs no
+ // throttle.
+ {
+ use crate::shapecache::UiTextDomain;
+ let ui = self.ui_shape_caches.borrow();
+ crate::perf::log_counter(
+ "ui_shape_chrome_bytes",
+ ui.domain(UiTextDomain::Chrome).total_weight(),
+ );
+ crate::perf::log_counter(
+ "ui_shape_note_bytes",
+ ui.domain(UiTextDomain::Note).total_weight(),
+ );
+ crate::perf::log_counter(
+ "ui_shape_file_preview_bytes",
+ ui.domain(UiTextDomain::FilePreview).total_weight(),
+ );
+ }
+ crate::perf::log_counter(
+ "line_quad_scratch_bytes",
+ self.line_quad_scratch.borrow().resident_bytes(),
+ );
+ if let Some(render_state) = self.render_state.as_ref() {
+ let glyphs = render_state.glyph_cache.borrow();
+ crate::perf::log_counter(
+ "glyph_cache_entries",
+ glyphs.glyph_entries(),
+ );
+ crate::perf::log_counter("atlas_side", glyphs.atlas.size());
+ crate::perf::log_counter(
+ "atlas_packed_px",
+ glyphs.atlas.usage().allocated_px,
+ );
+ }
// The GPU allocator is the other half of the
// picture and the cache counters cannot see it.
// Throttled because generating the report walks
diff --git a/wezterm-gui/src/termwindow/render/pane.rs b/wezterm-gui/src/termwindow/render/pane.rs
index 365fd484..5fa47986 100644
--- a/wezterm-gui/src/termwindow/render/pane.rs
+++ b/wezterm-gui/src/termwindow/render/pane.rs
@@ -1936,7 +1936,12 @@ impl crate::TermWindow {
}
}
- let mut buf = HeapQuadAllocator::default();
+ // Recorded into the window's one scratch recorder and
+ // moved out at exact size below, rather than growing a
+ // fresh allocator from zero on every miss. Recycled on
+ // entry so an early `?` return leaves nothing stale.
+ let mut buf = self.term_window.line_quad_scratch.borrow_mut();
+ buf.recycle();
let next_due = self.term_window.has_animation.borrow_mut().take();
let shape_key = LineToEleShapeCacheKey {
@@ -1999,7 +2004,7 @@ impl crate::TermWindow {
allow_images: true,
simple_shaping: false,
},
- &mut TripleLayerQuadAllocator::Heap(&mut buf),
+ &mut TripleLayerQuadAllocator::Heap(&mut *buf),
)
.context("render_screen_line")?;
@@ -2008,7 +2013,7 @@ impl crate::TermWindow {
replay_line(
self.layers,
- &buf,
+ &*buf,
self.scroll_px,
self.pane_clip,
line_idx,
@@ -2016,25 +2021,29 @@ impl crate::TermWindow {
)
.context("HeapQuadAllocator::apply_to")?;
- let quad_value = LineQuadCacheValue {
- layers: buf,
- expires,
- invalidate_on_hover_change: render_result.invalidate_on_hover_change,
- current_highlight: if render_result.invalidate_on_hover_change {
- self.term_window.current_highlight.clone()
- } else {
- None
- },
- };
-
- let weight = crate::termwindow::render::estimate_line_quad_entry_bytes(
- &quad_key,
- &quad_value,
- );
// 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) {
+ // Moved out at exactly its length, so the weight
+ // computed from `resident_bytes()` (which counts
+ // capacity) is what the entry really holds, and the
+ // scratch keeps its buffers for the next line.
+ let quad_value = LineQuadCacheValue {
+ layers: buf.take_exact(),
+ expires,
+ invalidate_on_hover_change: render_result.invalidate_on_hover_change,
+ current_highlight: if render_result.invalidate_on_hover_change {
+ self.term_window.current_highlight.clone()
+ } else {
+ None
+ },
+ };
+ drop(buf);
+ let weight = crate::termwindow::render::estimate_line_quad_entry_bytes(
+ &quad_key,
+ &quad_value,
+ );
self.term_window
.line_quad_cache
.borrow_mut()