diff --git a/meshterm/services/basemap.py b/meshterm/services/basemap.py index 95afd5f..6ee7c31 100644 --- a/meshterm/services/basemap.py +++ b/meshterm/services/basemap.py @@ -43,6 +43,7 @@ import os import threading import urllib.error import urllib.request +from collections import OrderedDict from pathlib import Path from typing import Container, NamedTuple, Optional @@ -70,6 +71,11 @@ _DEFAULT_MAX_DECODED_BYTES = 64 * 1024 * 1024 #: the directory, which is slow on the SD card the PicoCalc runs from. _PRUNE_AFTER_BYTES = 8 * 1024 * 1024 +#: Decoded tiles held in RAM. A viewport spans at most a handful of tiles, so this covers +#: the view plus the ring a pan or a zoom step reaches into, and little more — the PicoCalc +#: has 100 MB of RAM in total and decoded layers are not small. +_MEMO_TILES = 24 + _log = logging.getLogger(__name__) @@ -136,6 +142,12 @@ class BasemapSource: # than on disk so the claim expires with the process: a blank tile is cheap to # re-ask about, and a stale one on disk is a permanent hole in the map. self._blank: set[tuple[int, int, int]] = set() + # Decoded layers kept in RAM, most-recently-used last. The sidecar already spares + # the protobuf decode, but a marshal load off the SD card is still ~96 ms on the + # PicoCalc — and a map paints its whole viewport's worth of tiles on *every* + # frame, so panning one dot re-read every tile that had not moved. Bounded because + # decoded layers are the fattest thing this class holds. + self._memo: "OrderedDict[tuple[int, int, int], list[Layer]]" = OrderedDict() # -- metadata --------------------------------------------------------------- @@ -219,8 +231,13 @@ class BasemapSource: key = (z, x, y) if key in self._blank: return None + hot = self._memo.get(key) + if hot is not None: + self._memo.move_to_end(key) + return hot ready = self._read_decoded(z, x, y) if ready is not None: + self._remember(key, ready) return ready path = self._tile_path(z, x, y) cached = self._read_cached(path) @@ -228,6 +245,7 @@ class BasemapSource: layers = self._decode(cached, key) if layers is not None: self._write_decoded(z, x, y, layers) + self._remember(key, layers) return layers # Nothing drawable came out: a zero-byte marker from a build that cached # network failures, or bytes truncated by a link (or a power cut) mid-write. @@ -243,8 +261,16 @@ class BasemapSource: return None self._write_cached(path, raw) self._write_decoded(z, x, y, layers) + self._remember(key, layers) return layers + def _remember(self, key: tuple[int, int, int], layers: list[Layer]) -> None: + """Hold a decoded tile in RAM, evicting the least recently used past the budget.""" + self._memo[key] = layers + self._memo.move_to_end(key) + while len(self._memo) > _MEMO_TILES: + self._memo.popitem(last=False) + # -- the decoded sidecar ---------------------------------------------------- def _read_decoded(self, z: int, x: int, y: int) -> Optional[list[Layer]]: diff --git a/meshterm/ui/tui/fastrender.py b/meshterm/ui/tui/fastrender.py new file mode 100644 index 0000000..68f25c1 --- /dev/null +++ b/meshterm/ui/tui/fastrender.py @@ -0,0 +1,145 @@ +"""Write an already-composed frame straight to the terminal, one changed row at a time. + +MeshTerm composes every frame itself: :func:`~meshterm.ui.tui.frame.compose_base` returns +a finished ANSI string, exactly one line per terminal row, already sliced to the viewport +and already folded to the platform's glyph set. prompt_toolkit's own renderer then takes +that string and does a full round trip with it — parses the ANSI back into style/text +fragments, writes every one of the ~1400 cells into a fresh grid of ``Char`` objects, +diffs that grid against the previous frame's grid, and re-emits ANSI for the cells that +moved. + +That round trip is the single largest cost in a keystroke on the PicoCalc, and it is paid +in full on *every* paint — a measured 70-125 ms whether the frame changed by one row, by +all of them, or not at all (the 2 s header tick recomposes an identical frame and still +pays it). Since we already know the frame as rows of text, the same pixels can be reached +by comparing this frame's rows against the last frame's rows and rewriting only the ones +that differ: ~0.1 ms, and a smaller write besides. + +The bypass is deliberately narrow. It runs only when the frame is a plain full-screen +composition — one base screen, no floating dialog and no busy overlay — because those are +laid out by prompt_toolkit's float containers rather than by us, and compositing them here +would mean re-implementing that placement. Anything else falls straight through to the +stock renderer, which stays the authority: :meth:`FastRenderer.render` is an accelerator +for the common case, never a second implementation of the whole layout engine. + +Two details make the row diff safe rather than merely fast: + +* **A row is rewritten whole, from column 0.** The terminal's own cursor advance re-lays + the line, so a glyph it draws narrower than we measured cannot leave the rest of the row + shifted — the same guarantee :meth:`~meshterm.ui.tui.session.TuiSession._emit` relies on, + reached here for free rather than by a scrub pass. +* **Each row is prefixed with a reset and followed by an erase-to-end-of-line**, so no + style leaks in from the row above and a row that got shorter leaves no tail behind. +""" + +from __future__ import annotations + +import os +from typing import Callable, Optional + +from prompt_toolkit.renderer import Renderer + + +def enabled() -> bool: + """Whether the direct row writer is active. + + Off by default while it earns its keep on the device; set ``MESHTERM_FASTRENDER=1`` + to turn it on, ``=0`` to force the stock renderer. + """ + return os.environ.get("MESHTERM_FASTRENDER", "") == "1" + + +class FastRenderer(Renderer): + """A :class:`~prompt_toolkit.renderer.Renderer` that short-circuits simple frames. + + Args: + frame_source: Returns the composed full-screen frame as one ANSI string (rows + joined by newlines), or ``None`` when this paint is not a plain base frame + and must go through prompt_toolkit's layout instead. + """ + + def __init__(self, *args, frame_source: Callable[[], Optional[str]], **kwargs) -> None: + super().__init__(*args, **kwargs) + self._frame_source = frame_source + self._prev_rows: Optional[list[str]] = None + self._prev_size: Optional[tuple[int, int]] = None + #: Paints answered here vs handed to the stock renderer — read by the bench. + self.fast_paints = 0 + self.slow_paints = 0 + + def reset(self, _scroll: bool = False, leave_alternate_screen: bool = True) -> None: + """Forget the last frame along with prompt_toolkit's own render state.""" + self._prev_rows = None + super().reset(_scroll=_scroll, leave_alternate_screen=leave_alternate_screen) + + def erase(self, leave_alternate_screen: bool = True) -> None: + """The screen is being cleared out from under us — the next paint must be full.""" + self._prev_rows = None + super().erase(leave_alternate_screen=leave_alternate_screen) + + def render(self, app, layout, is_done: bool = False) -> None: # noqa: ANN001 + """Paint the frame, taking the row-diff path when this frame is a plain one.""" + text = None if is_done else self._frame_source() + if text is None: + # A dialog, the busy overlay, or the closing paint: prompt_toolkit lays those + # out, so it must also own the diff — its grid is the only record of what is + # on screen, and it is about to be rebuilt from scratch anyway. + self._prev_rows = None + self.slow_paints += 1 + super().render(app, layout, is_done) + return + + output = self.output + if self.full_screen and not self._in_alternate_screen: + self._in_alternate_screen = True + output.enter_alternate_screen() + if not self._bracketed_paste_enabled: + output.enable_bracketed_paste() + self._bracketed_paste_enabled = True + if not self._cursor_key_mode_reset: + output.reset_cursor_key_mode() + self._cursor_key_mode_reset = True + + size = output.get_size() + dims = (size.rows, size.columns) + rows = text.split("\n")[: size.rows] + + # A resize invalidates both records of the screen: ours and prompt_toolkit's. + full = self._prev_rows is None or self._prev_size != dims + if full: + self._last_screen = None + output.hide_cursor() + output.reset_attributes() + output.erase_screen() + output.cursor_goto(0, 0) + + write = output.write_raw + prev = self._prev_rows + last = -2 + for i, row in enumerate(rows): + if not full and i < len(prev) and prev[i] == row: + continue + # Stepping down a row with CRLF returns the terminal to a true column 0 + # whatever happened on the row above, and costs three bytes less than a + # cursor address; only a real jump pays for one. + write("\r\n" if i == last + 1 else f"\x1b[{i + 1};1H") + # Erase *before* drawing, never after. A row that fills the terminal exactly + # leaves the cursor in the last column with wrap pending, and an erase-to-end + # there wipes the very character just written (the row's last cell went + # missing on the PicoCalc's 53-column console). Clearing first also drops the + # tail of a row that got shorter, which is what the erase was for. + write("\x1b[0m\x1b[K") + write(row) + last = i + # Park the cursor out of the text. The app hides it, but a terminal that ignores + # that should not leave it blinking in the middle of a row. + write(f"\x1b[{len(rows)};1H") + output.flush() + + self._prev_rows = rows + self._prev_size = dims + self._last_size = size + # prompt_toolkit's grid no longer describes the screen — if a later paint falls + # back to it, it must redraw everything rather than diff against a stale record. + self._last_screen = None + self.fast_paints += 1 diff --git a/meshterm/ui/tui/frame.py b/meshterm/ui/tui/frame.py index 0e80012..390b1e1 100644 --- a/meshterm/ui/tui/frame.py +++ b/meshterm/ui/tui/frame.py @@ -368,7 +368,8 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str: # Size the box to its widest real row (probe at a generous width, then measure), never # wider than the terminal and never narrower than the title/hint it must show. probe = max(10, min(cols - 6, 100)) - measured = max((_ansi_width(line) for line in screen.render_body(probe)), default=10) + probe_lines = screen.render_body(probe) + measured = max((_ansi_width(line) for line in probe_lines), default=10) # Size to the fullest the footer can get, not this frame's — a screen whose hint grows # as the highlight moves (a select's per-row "Del remove") reports that width here, so # the box is reserved for it up front and never widens mid-navigation. @@ -387,7 +388,11 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str: footnote_h = 1 if screen.footnote else 0 # the note sits directly under the logo # Rows left for the box below the fixed banner block: the panel border is 2 rows. below = rows - top - banner_h - footnote_h - gap - body_lines = screen.render_body(inner_w) + # The probe render is the answer whenever it was already made at the width we settled + # on — the common case, since a body narrower than the probe *is* what set inner_w. + # The splash repaints on every tick while the device list sits there, and rendering + # the same body twice was a measured third of that paint on the PicoCalc. + body_lines = probe_lines if inner_w == probe else screen.render_body(inner_w) budget = below - 2 vpad = _breathing_room(len(body_lines), budget) viewport = max(1, min(len(body_lines), budget - 2 * vpad)) @@ -407,8 +412,14 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str: padding=(vpad, 1), width=inner_w + 4, ) - # Glow before centering, while the box still starts at column 0 of its own lines. - panel_lines = _center(apply_corner_glow(render_lines(panel, inner_w + 4)), cols) + # Glow before centering, while the box still starts at column 0 of its own lines. Gated + # on the platform exactly as compose_base gates it: the pass only ever recolours + # truecolor foregrounds, so on the 16-slot console it walked every line of the splash + # to hand back the identical list, on every tick. + panel_lines = render_lines(panel, inner_w + 4) + if get_platform().effects: + panel_lines = apply_corner_glow(panel_lines) + panel_lines = _center(panel_lines, cols) # A small muted line (e.g. a copyright notice) sits immediately under the logo, its right # edge hung off the logo's right edge so the two read as one signed block. @@ -499,7 +510,10 @@ def compose_dialog(screen: Screen, cols: int, rows: int) -> str: padding=(vpad, 1), width=max_w, ) - out = "\n".join(apply_corner_glow(render_lines(panel, max_w))) + dialog_lines = render_lines(panel, max_w) + if get_platform().effects: + dialog_lines = apply_corner_glow(dialog_lines) + out = "\n".join(dialog_lines) _DIALOG_CACHE[key] = out if len(_DIALOG_CACHE) > _DIALOG_CACHE_MAX: _DIALOG_CACHE.popitem(last=False) diff --git a/meshterm/ui/tui/session.py b/meshterm/ui/tui/session.py index 7ef8cad..325ee3f 100644 --- a/meshterm/ui/tui/session.py +++ b/meshterm/ui/tui/session.py @@ -31,7 +31,7 @@ from rich.text import Text from ...platforms import get_platform from ...services import modifier_watch -from . import fkeys, frame +from . import fastrender, fkeys, frame from .overlay import BusyOverlay from .progress import TuiProgress from .prompt import ( @@ -1129,7 +1129,7 @@ class TuiSession: ), ], ) - return Application( + app = Application( layout=Layout(root, focused_element=base_window), key_bindings=self._key_bindings(), full_screen=True, @@ -1137,9 +1137,29 @@ class TuiSession: # Keeps the live monitor counter in the header ticking. Per-platform, so a host # where an idle repaint is expensive can breathe more slowly between frames. refresh_interval=get_platform().tick_s, + # Repaint as soon as the loop is free, rather than spinning the event loop for + # up to 10 ms first. prompt_toolkit's default postpone is there to protect a + # UI whose *own* output floods it with invalidations (its motivating case was + # a terminal multiplexer); here an invalidation is a keystroke or the 2 s + # header tick, so the delay buys nothing and was measured as a flat 3 ms on + # the PicoCalc and 10 ms on desktop, paid on every single key. + max_render_postpone_time=None, input=self._input, output=self._resolve_output(), ) + if fastrender.enabled(): + # Swap in the row-diff renderer for plain full-screen frames. Built with the + # same arguments Application gave the stock one, so everything except the + # paint itself — CPR, alternate screen, mouse, cursor shape — is unchanged. + app.renderer = fastrender.FastRenderer( + app._merged_style, + app.output, + full_screen=True, + mouse_support=False, + cpr_not_supported_callback=app.cpr_not_supported_callback, + frame_source=self._plain_frame, + ) + return app def _resolve_output(self) -> Any: """The output the app renders to — optionally widened to reclaim the last column. @@ -1310,6 +1330,20 @@ class TuiSession: frame.compose_base(self._header(cols), base, footer, cols, rows, footer_lane=lane) ) + def _plain_frame(self) -> Optional[str]: + """The composed full-screen frame, when this paint is one the fast path may take. + + Answers ``None`` — meaning "let prompt_toolkit lay this one out" — whenever the + frame is more than a single background screen: a floating dialog or the busy + overlay is placed by pt's float containers, not by us (see + :mod:`~meshterm.ui.tui.fastrender`). Composing the base is not wasted in that + case: the float layers draw *over* it, so pt asks for it a moment later and gets + the memoized composition. + """ + if self._has_float() or self._overlay_visible() or not self._stack: + return None + return self._render_base().value + @staticmethod def _fkey_lane(active: Screen) -> Optional[Callable[[], Text]]: """A deferred F-key lane row for ``active``, or ``None`` on a platform without one. diff --git a/tests/test_performance.py b/tests/test_performance.py index c9e759a..06a3aeb 100644 --- a/tests/test_performance.py +++ b/tests/test_performance.py @@ -16,6 +16,8 @@ import subprocess import sys from pathlib import Path +from prompt_toolkit.data_structures import Size +from prompt_toolkit.output import DummyOutput from rich.text import Text from meshterm.persistence import db @@ -237,3 +239,110 @@ def test_spinner_interval_reads_the_active_platform() -> None: assert spinner_interval() == REGULAR.spinner_tick_s set_platform(PICOCALC) assert spinner_interval() == PICOCALC.spinner_tick_s + + +# --- the direct row-diff renderer --------------------------------------------------- + + +class _CapturingOutput(DummyOutput): + """A DummyOutput that records what the renderer wrote, at a fixed console size.""" + + def __init__(self, rows: int = 26, columns: int = 53) -> None: + super().__init__() + self.written: list[str] = [] + self._size = Size(rows=rows, columns=columns) + + def get_size(self) -> Size: + return self._size + + def write_raw(self, data: str) -> None: + self.written.append(data) + + def cursor_goto(self, row: int = 0, column: int = 0) -> None: + self.written.append(f"") + + def erase_screen(self) -> None: + self.written.append("") + + @property + def stream(self) -> str: + return "".join(self.written) + + +def _fast_renderer(frames: list[str]) -> tuple["FastRenderer", _CapturingOutput]: + """A FastRenderer fed a scripted sequence of composed frames.""" + from prompt_toolkit.styles import Style + + from meshterm.ui.tui.fastrender import FastRenderer + + out = _CapturingOutput() + pending = list(frames) + renderer = FastRenderer( + Style([]), out, full_screen=True, frame_source=lambda: pending.pop(0) + ) + return renderer, out + + +def test_fastrender_is_off_unless_asked_for(monkeypatch) -> None: # noqa: ANN001 + """The bypass is opt-in: an unset environment leaves prompt_toolkit in charge.""" + from meshterm.ui.tui import fastrender + + monkeypatch.delenv("MESHTERM_FASTRENDER", raising=False) + assert not fastrender.enabled() + monkeypatch.setenv("MESHTERM_FASTRENDER", "1") + assert fastrender.enabled() + + +def test_fastrender_rewrites_only_the_rows_that_changed() -> None: + """The whole point: a keystroke that moves one row must not repaint the screen.""" + rows_a = [f"row {i:02d}" for i in range(26)] + rows_b = list(rows_a) + rows_b[7] = "row 07 SELECTED" + renderer, out = _fast_renderer(["\n".join(rows_a), "\n".join(rows_b)]) + + renderer.render(None, None) # first paint: everything + out.written.clear() + renderer.render(None, None) # second: one row moved + + stream = out.stream + assert "row 07 SELECTED" in stream + # Every *other* row's text stayed off the wire. + assert "row 06" not in stream + assert "row 08" not in stream + assert "\x1b[8;1H" in stream # addressed row 8 (1-based) directly + + +def test_fastrender_erases_before_it_draws_so_a_full_row_keeps_its_last_cell() -> None: + """Erase-to-end *after* a full-width row wipes the character just written. + + A row that exactly fills the console leaves the cursor in the last column with wrap + pending; an erase there clears that cell, and the row's final glyph goes missing (it + did, on the PicoCalc's 53 columns). So the erase has to lead, never follow. + """ + full = "x" * 53 + renderer, out = _fast_renderer(["\n".join([full] * 26), "\n".join([full] * 26)]) + renderer.render(None, None) + stream = out.stream + assert "\x1b[K" in stream + # In every row the clear precedes that row's text, and no clear trails it. + for chunk in stream.split("\x1b[0m")[1:]: + assert chunk.startswith("\x1b[K"), chunk[:40] + assert not chunk.rstrip().endswith("\x1b[K"), chunk[-40:] + + +def test_fastrender_hands_dialogs_back_to_prompt_toolkit(monkeypatch) -> None: # noqa: ANN001 + """A ``None`` frame means a float is up, which pt lays out — it must own that paint.""" + from prompt_toolkit.renderer import Renderer + from prompt_toolkit.styles import Style + + from meshterm.ui.tui.fastrender import FastRenderer + + calls: list[bool] = [] + monkeypatch.setattr(Renderer, "render", lambda *a, **k: calls.append(True)) + renderer = FastRenderer( + Style([]), _CapturingOutput(), full_screen=True, frame_source=lambda: None + ) + renderer.render(None, None) + assert calls == [True] + assert renderer.slow_paints == 1 + assert renderer.fast_paints == 0