Struct PerfOverlay 

pub struct PerfOverlay<'a, const N: usize = 120> { /* private fields */ }

A bordered panel showing live FrameStats.

An NNNfps MM.Mms minMM.M maxMM.M <backend> readout, any extra caller-supplied metric rows (VSync state, resolution, render backend details, …), and a scrolling frame-time Sparkline.

The richer counterpart to DefaultPerfRenderer: composed entirely from existing widgets (Panel, Text, Sparkline), it draws through Surface like every other widget in this crate, so it already works on every backend. Hand it to PerfOverlayApp::with_closure as a closure to use it instead of the built-in renderer:

use retroglyph_core::app::{App, Flow, Frame};
use retroglyph_core::backend::{Backend, Headless};
use retroglyph_core::grid::Size;
use retroglyph_core::terminal::Terminal;
use retroglyph_ui::{PerfOverlay, PerfOverlayApp, Widget};

struct MyGame;
impl<B: Backend> App<B> for MyGame {
    fn update(&mut self, _term: &mut Terminal<B>, frame: &Frame) -> Flow {
        if frame.frame >= 1 { Flow::Exit } else { Flow::Continue }
    }
}

let term = Terminal::new(Headless::new(60, 12));
let app = PerfOverlayApp::with_closure(MyGame, "software", |stats, backend, area, surface| {
    PerfOverlay::new(stats)
        .backend(backend)
        .metrics(&[("res", "1920x1080"), ("vsync", "on")])
        .render(&mut surface.scope(area));
})
.size(Size::new(34, 8));
retroglyph_core::app::run_blocking(term, app).expect("run_blocking");

N must match the FrameStats window it’s built from; this crate’s PerfOverlayApp always uses 120 samples (FRAME_HISTORY), the default here too.

As an AnimatedWidget

This type is read-only: it borrows an already-updated FrameStats (new(stats)), which is exactly what Widget rendering wants but is the wrong shape for AnimatedWidget, whose state: &mut FrameStats argument needs to record into the same data a draw call reads – an immutable borrow baked into self and a mutable one for state can’t coexist. Use AnimatedPerfOverlay instead for a call site that owns one FrameStats field and wants to record and draw in a single call, with no PerfOverlayApp decorator wrapping the app.

Rows beyond the panel’s available interior height are silently dropped: the readout row draws first, then one row per metrics entry, then the sparkline, each only if there’s still room, so a caller that under-sizes the area loses the least important rows first rather than panicking or overflowing the border.

Implementations

impl<'a, const N: usize> PerfOverlay<'a, N>

pub fn new(stats: &'a FrameStats<N>) -> Self

A perf overlay reading stats, titled "perf", with no backend label and no extra metrics, styled from Theme::DARK (as if PerfOverlay::theme had been called).

pub const fn backend(self, backend: &'a str) -> Self

Sets the backend label appended to the readout row (e.g. "crossterm", "software"). Omitted entirely if left empty (the default).

pub const fn title(self, title: &'a str) -> Self

Sets the panel’s title. Defaults to "perf".

pub const fn metrics(self, metrics: &'a [(&'a str, &'a str)]) -> Self

Sets extra (label, value) metric rows drawn below the readout: resolution, VSync state, render backend details, or anything else an app wants visible. Defaults to none.

pub const fn text_style(self, style: Style) -> Self

Sets the readout/metric text’s style. Defaults to Theme::DARK’s fg role.

pub const fn sparkline_style(self, style: Style) -> Self

Sets the frame-time sparkline’s bar color (every bar, uniformly; see Sparkline::style).

Defaults to a fixed accent color, not Sparkline’s own green-to-red ramp: the sparkline scrolls, so “tallest bar in the visible window” isn’t the same thing as “a slow frame”: the same absolute frame time reads as short one moment and tall the next as the window’s own max shifts. A ramp keyed to that relative height would tell a story the data doesn’t support; one fixed color makes height the only signal, which is the honest one.

pub fn theme(self, theme: Theme) -> Self

Applies theme’s named roles: border_style/fill_style map the same way as Panel::theme, and text_style becomes theme.fg on theme.panel_bg.

Call before any manual style override you want to keep.

Trait Implementations

impl<'a, const N: usize> Clone for PerfOverlay<'a, N>

fn clone(&self) -> PerfOverlay<'a, N>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, const N: usize> Debug for PerfOverlay<'a, N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize> Widget for PerfOverlay<'_, N>

fn render(&self, surface: &mut Surface<'_>)

Draw this widget into surface, filling surface.area().

impl<'a, const N: usize> Copy for PerfOverlay<'a, N>