plotter/README.md

# plot

An embeddable OpenGL time-series plotting library for real-time, high-sample-rate data.
The core (`plot::core`, C++20, OpenGL 3.3 core) has no third-party dependency at all;
the host integrations that own a window and an event loop are separate, opt-in targets
built on top of it.

## Hosts, and what a frame costs

| host | CMake target | source |
|---|---|---|
| GLFW | `plot::glfw` | `adapters/glfw/` |
| Dear ImGui | `plot::imgui` (build-tree only) | `adapters/imgui/` |
| Qt6 | `plot::qt6` | `adapters/qt6/` |
| GTK4 | `plot::gtk4` | `adapters/gtk4/` |

The GTK4 adapter exists for, and is exercised by, a real consumer: **udpscope**, an oscilloscope-style viewer
for a UDPStreamer source, at <https://git.ferrarinas.it/martino/udpscope>. It embeds the core through
`plot::gtk4`, and the library's interaction layer — cursors, measurement marks, the shading of a span a host
has declared invalid — has been shaped by what that host needed. The notes in `src/`, `docs/` and `tests/`
that say "in udpscope's case" are those places.

The visible x range is mapped onto sample indices through the series' own x
(`Series::neighbours()`, a binary search over the real stamps), never through the
`(x - x0()) / dx()` grid: `dx()` is a *nominal* spacing, and a series whose x is a streamed
timestamp would otherwise have its draw window land inside the visible range and lose the two
segments that enter and leave the frame — the empty left and right margins of a zoomed-in view.
Per-frame rendering cost is O(visible pixels + samples produced since the last frame),
not O(samples): a trace denser than one sample per pixel is drawn from a min/max LOD
pyramid rather than from raw samples. The `plot_multiplot_demo` run stages **20,901 GPU
segments** to draw **~4.5 million visible samples** across six traces — the frame is
bounded by the pixels it lights, not by the sample count behind them. That figure is from
a `linux-release` build under `xvfb-run` on **llvmpipe** (Mesa's software rasteriser); no
run touched a GPU, so read it as an upper bound and a record of the software path.

## Features

- a trace whose series answers a *clamped* stamp for its oldest slots -- a ring whose published
  window is pinned while it slides -- is drawn from its longest increasing *suffix*, so an unreadable
  front cannot draw a segment from the newest sample back to the oldest (a line across the whole
  panel);
- a following group's window stays on its members' data: while the members retain at least a
  window's worth, the scroll offset is bounded by `retained - span`, so a pan or a zoom-in near an
  edge cannot leave the window's own span over data the scope never had (a window *wider* than the
  data keeps the older placement -- right edge on the newest sample);
- a trace whose gathered window is denser than the axis is reduced **onto the pixel grid** --
  one snapped vertical segment per integer column, lit from that column's own extremes --
  because an LOD envelope staged as a polyline puts three or four near-vertical hairlines per
  column at as many sub-pixel phases, and the beat between the bucket pitch and the pixel pitch
  is a crawling moiré; one segment per column leaves one phase, so there is nothing to beat
  (`FrameStats::column_traces`, and `docs/data-and-performance.md` for the four rules it keeps);
- and such a column can be drawn **graded by dwell** instead of as one flat band
  (`Style::intensity_grading`, off by default, `FrameStats::graded_traces`): bright where the
  signal sits, faint where it only passes through, the way a digital-phosphor scope reads. It is
  what puts back the information the reduction throws away — a column's min and max are the same
  whether its samples fill the span or pile at its two ends — so the gather is asked at a level
  finer than the pixel grid and the distribution read from those sub-buckets. Below the density at
  which columns are reduced the same switch grades the **polyline** by each segment's slope
  (`FrameStats::slope_traces`), so the look does not change as a window narrows past the
  threshold;
- a **phosphor density** a host can turn on for a plot (`Plot::set_density()`, an image rather
  than a set of retained traces): **one grid per trace**, in that trace's own colour, one `f32`
  cell per device pixel of the axes rect, drawn *in place of* the traces -- a host may not also
  draw them over it -- into which each acquisition is deposited, 1.0 per cell a trace crosses, so
  brightness is how often it passed. It fades either by a **time constant** in stream seconds or by
  a **per-acquisition factor**, and the newest acquisition is deposited like every other, so it
  fades too. Memory is the screen's times the traces on screen (a 640x360 viewport's axes is
  179 349 cells per trace, 717 kB), the deposit walks the axes' columns rather than
  the samples, and a frame whose grids did not move costs one draw call per trace
  (`FrameStats::density_cells`/`density_upload_bytes`); see `docs/data-and-performance.md`;
- sample **markers** when a window is sparse enough that its samples are the shape
  (`Style::marker_below_samples`, 50 by default, `marker_px` across, in the trace's own colour);
- grid with independent major/minor line classes (`Style::grid_major_visible`,
  `grid_minor_visible`), each with its own colour, width and (for the minors) dash — the
  subdivisions default to thinner, dashed and alpha-blended, so they read as texture under the
  labelled grid rather than as a second set of ticks;
- x and y axes, with a vertical (bottom-to-top) y-axis title;
- cursors in both orientations — vertical markers and horizontal rulers;
- draggable regions and measurement bands with exact interval statistics;
- a signal legend anchored to an axes corner;
- a hover crosshair with a per-signal readout, quoting the nearest sample and marking it
  (`CrosshairValue::NearestSample`, the default) or interpolating between two
  (`CrosshairValue::Interpolated`);
- a multi-plot `Figure` of stacked rows sharing one synchronised x axis;
- live follow (`XFollow::Live`) with relative (multiplicative) zoom and mouse panning;
- XY series for irregularly sampled data (`plot/data/xy_series.hpp`): sorted-ascending x
  with binary-searched crosshair, measurement and index snapping;
- per-trace draw modes: dash patterns (`Trace::dash_on`/`dash_off`, logical px, 0 = solid)
  and point markers (`Trace::marker`: cross, circle, square) with a manual
  `marker_every` stride or an automatic one; `width == 0` draws the markers alone
  (scatter);
- three downsample policies per trace (`Trace::mode`, `GatherMode`): `Envelope`
  (min/max pairs — the default), `Nearest` (one raw sample per bucket) and `Mean`
  (one averaged point per bucket);
- readout text colour: crosshair value rows render in their row's trace colour, labels in
  the axis text colour;
- input parity across hosts: pinch-zoom and pan gestures on Qt6 and GTK4 drive the same
  controller paths as mouse and wheel (touch parity), with keyboard panning
  (arrow keys), Escape cancelling a drag or box-zoom, double-click re-fitting the axes,
  and modifier-masked box zoom (Shift = both axes, Ctrl = x only, Alt = y only), the area being
  chosen framed as the drag runs -- a low-alpha fill under a light border, widened along the axis
  the release will *not* zoom, so Ctrl's frame is the band it is about to apply rather than the
  sliver a straight horizontal drag sweeps;
- DPI-consistent sizing: metrics are logical units converted once through
  `Style::ui_scale`;
- an anti-aliased embedded monospaced font, plus an optional runtime TrueType backend
  (`plot::font_ttf`).

## Build and install

Needs a C++20 compiler and CMake **3.24+**. Presets live in `CMakePresets.json`
(`linux-debug`, `linux-release`, `linux-asan`, `linux-coverage`).

```sh
cmake --preset linux-release
cmake --build build/release
cmake --install build/release --prefix /where/you/want
```

Install is on by default (`PLOT_INSTALL=ON`) and, via `GNUInstallDirs`, installs the
`plot_core` archive under `lib/`, the public headers under `include/plot/` — including the
generated `plot/version.hpp` — a CMake package config under `lib/cmake/plot/`, a pkg-config
file under `lib/pkgconfig/plot.pc`, and the licences under `share/licenses/plot/`. A
consumer then needs only:

```cmake
find_package(plot 0.1 REQUIRED)
target_link_libraries(my_app PRIVATE plot::core)
```

**Versioning.** The package config carries **SameMinorVersion** compatibility: at 0.x the
major component promises nothing and the minor is what moves when the surface breaks, so
`find_package(plot 0.1 REQUIRED)` accepts 0.1.x and refuses anything newer. A shared build
(`BUILD_SHARED_LIBS=ON`) names its ABI on the file itself — `libplot_core.so.0`, the
SOVERSION being the major component. What a header set *is* is in its generated
`<plot/version.hpp>`: `plot::version::major`/`minor`/`patch`/`string`, or the
`PLOT_VERSION_*` macros for a preprocessor test. The full layout is tabled in
[docs/building-and-testing.md](docs/building-and-testing.md).

## Embedding

A host owns the window, the GL context and the event loop; `plot` owns none of them. This
is the whole of a minimal GLFW program — the adapter opens the window, runs the loop and
feeds the controller, and the callback is where live data would be pushed. It is committed
at the repository root as `readme_main.cpp`:

```cpp
#include <glfw/glfw_host.hpp>   // the optional GLFW adapter
#include <plot/plot.hpp>

#include <cmath>
#include <vector>

int main() {
  plot::glfw::Host host;
  plot::Plot& p = host.plot();

  std::vector<plot::f32> y(512);
  for (plot::usize i = 0; i < y.size(); ++i)
    y[i] = static_cast<plot::f32>(std::sin(0.05 * static_cast<double>(i)));
  plot::data::ArraySeries series(std::move(y), 0.0, 1.0);

  const plot::u32 x = p.add_x_axis({"x", {0.0, 511.0}, true});
  const plot::u32 sig = p.add_y_axis({"signal", {-1.0, 1.0}, true, plot::AxisPlace::Left});
  p.add_trace({&series, plot::Color::hex(0x4FA3FF), 1.5f, x, sig, "sine"});

  plot::Status st;
  return host.run({800, 480, "plot"}, [](plot::Plot&, plot::f64) {}, &st) ? 0 : 1;
}
```

It compiles and links against a built tree (see [docs/getting-started.md](docs/getting-started.md)
for the same program written against `plot::core` directly, with no adapter). The one
non-obvious flag is `-I build/debug/include`: that is where CMake generates
`plot/version.hpp`, which the umbrella pulls in:

```sh
g++ -std=c++20 -I include -I adapters -I build/debug/include readme_main.cpp \
    build/debug/adapters/glfw/libplot_glfw.a build/debug/libplot_core.a \
    $(pkg-config --libs glfw3) -ldl -lpthread -o plot_readme
```

## Documentation

The user guide lives under `docs/`; `docs/superpowers/` is the design record, not user
documentation.

- [Getting started](docs/getting-started.md) — prerequisites, build/install/consume, and a
  minimal GLFW program against `plot::core`.
- [Architecture](docs/architecture.md) — the layers (`core`/`math` → `gl` → `data` →
  `render` → `plot` → `input`), what each owns, and the dependency rules.
- [Embedding into a host](docs/embedding.md) — the four adapters, the `ui_scale`/DPI rule
  per host, and the headless demo invocations.
- [Data and performance](docs/data-and-performance.md) — the sample stores, the
  single-producer/single-consumer contract, the LOD pyramid, and the measured frame times.
- [Interaction](docs/interaction.md) — cursors, regions, the measurement band, the legend,
  the crosshair, the gesture table, and live follow.
- [Styling](docs/styling.md) — every `Style` field with its default and unit, the grid
  classes, and installing a text backend.
- [Building and testing](docs/building-and-testing.md) — presets, `PLOT_BUILD_*` options,
  the suite, the headless demo modes, and the coverage command.
- [Coverage](docs/coverage.md) — the coverage method and the measured per-file table.

## Testing and coverage

```sh
cmake --preset linux-debug
cmake --build build/debug
ctest --test-dir build/debug --output-on-failure   # 396 cases, 0 failed

tools/coverage.sh                                  # configure+build+run+capture+floor check
```

The `linux-debug` suite runs **396 cases**; the `linux-coverage` preset builds **379** of
them, because its adapters are off and 17 cases need an adapter target (11 in
`test_imgui_widget.cpp`, 6 in `test_glfw_host.cpp`). Coverage is enforced by
`tools/coverage.sh` against `tools/coverage_floor.py`: **80%** per file under `src/` and
**90%** aggregate. The measured aggregate and per-file table live in
[docs/coverage.md](docs/coverage.md), which the command regenerates — it is the single
source for those numbers, so this page carries none.

## Licence and third-party provenance

- **This library** is **MIT licensed**: the full text is in [`LICENSE`](LICENSE), and
  every first-party file (C++, Python and shell) carries its SPDX identifier in the file
  header — `// SPDX-License-Identifier: MIT` — so the grant travels with each source file,
  not just the repository root.
- **Adwaita Mono** (the embedded font, `render::EmbeddedMonoFont`) is under **SIL OFL
  1.1**, committed verbatim at [`licences/OFL-1.1.txt`](licences/OFL-1.1.txt). The backend
  class is named neutrally (`EmbeddedMonoFont`, not "Adwaita Mono") because OFL reserves
  the font name for modified redistributions. The baked atlas is generated at authoring
  time by `tools/fonts/gen_atlas.py` and committed as data, so `plot_core` rasterises
  nothing at build or run time.
- **stb_truetype v1.26** (public domain, Sean Barrett / RAD Game Tools) is vendored at
  `third_party/stb_truetype.h` and compiled **only** by the optional `plot_font_ttf`
  target; its include directory is `PRIVATE`, so no consumer and no other target can reach
  it. `PLOT_BUILD_TTF_FONT` defaults on exactly when the vendored header is present.
- **`plot_core` is third-party-free.** It links only `${CMAKE_DL_LIBS}`, and no public
  header under `include/plot/` includes a third-party header. The header self-containment
  and umbrella checks in `tests/CMakeLists.txt` fail the build if either rule breaks.

## Limitations

- **Timings are llvmpipe under Xvfb** (`tools/coverage.sh`, the demo summaries). No
  measurement here used a GPU; there are no hardware numbers.
- **macOS and Windows are untested.** Development and CI are Linux/EGL + X11 only.
- **Fractional-scale compositing and touchpad scroll calibration are unverified** — the
  `ui_scale` sources are correct per host, but no run exercised a real fractional DPI or a
  calibrated scroll device. The new gesture paths (Qt6 and GTK4 pinch, the keyboard and
  wheel paths behind the parity list above) are tested at the toolkit-free seams and
  headless; no run has touched real touch hardware.
- **Figure row rects are one frame stale during a resize.** The hosts cache
  `Figure::layout()`'s rows and refresh them once per frame, so an event arriving mid-resize
  routes against the previous frame's rects (see [docs/embedding.md](docs/embedding.md)).
- **Untrusted font files are out of scope** for the runtime `plot::font_ttf` backend:
  stb_truetype does no range checking, so `from_file()` must only be handed files the host
  trusts.
- **`render` ↔ `plot` is not a strict include chain.** `Renderer` includes `plot/plot.hpp`
  because drawing *is* being handed a `Plot`; the `plot` layer names only `render`'s value
  types (`Style`, `TextBackend`), never `Renderer`. The cycle and its direction are
  documented in [docs/architecture.md](docs/architecture.md).