Martino Ferrari
6a6915e64e
`Plot::set_density()` gives a plot a **phosphor density**: a screen-sized intensity image behind its traces, into which each acquisition is deposited and which fades by a time constant or by a per-acquisition factor. It is the library's and not a host's because the library is the side that knows a trace's device geometry -- a host would be re-rasterising traces the renderer has already staged, at a second derivation of the same mapping. It is an **image and not a set of retained traces**, and that is the whole of its cost: one `f32` cell per device pixel of the axes rect (`DensityGrid`), a cell's value a *number of sweeps*, so a display of a thousand acquisitions costs what one costs and there is no depth to get wrong. Measured on a 640x360 viewport's axes: **573x313 = 179 349 cells, 717 396 bytes** of grid, and one byte per cell uploaded on the frame the grid moved. - `Plot::accumulate_density()` deposits the acquisition on screen: every visible trace's window is mapped to sample indices and gathered exactly as `Renderer::draw_traces()` maps it, then walked column by column -- so the deposit is bounded by the axes' columns and not by the samples behind them -- and a cell takes **1.0 once per trace per sweep**, however many of that trace's own samples crossed it. Counting the hits instead put a single dense sweep at the ceiling of the brightness scale and hid the sweeps behind it, and it made a cell mean "how much the beam moved here" rather than "how many acquisitions were here"; the dedupe is a stamp per grid *row* (one `u64`, keyed by trace and column) so two sweeps agreeing on a cell still count twice. Dwell is a different question the library already answers (`Style::intensity_grading`). - `decay_density(dt_s)` fades by the clock, `clear_density()` and switching the density off drop the image at once. `DensityConfig` carries `full_scale` and `gamma`, applied on the CPU when the grid changed: the value a host reads back through `ink()`/`peak()` and the picture it sees are one derivation, and a frame whose grid did not move skips the conversion and the upload entirely (`FrameStats::density_cells`/`density_upload_bytes`, the latter the *frame's* total over every row, which one row's assignment used to overwrite). - The renderer draws it as one attribute-less quad over the axes rect (`kDensityVS`/`kDensityFS`, `DensityProgram`), over the grid and the invalid-span bands and **under the traces**, inside the axes' clip: it reserves no layout space and nothing on it can be picked, exactly as `Plot::set_invalid_spans()` does. `Style::density` is its tint. - The two fades are the two questions a persistence display can be asked -- "still visible a second later" and "the N-th back is gone" -- so the choice is the caller's. Six cases, all in the suite: four plot-level ones (the grid's resolution and memory, the per-acquisition schedule **584 -> 876 -> 1022** ink with `peak_steady=2.000`, `exp(-dt/tau)` off the ink, and the deposit's own geometry including a NaN as a gap) and one on the real driver (`a_phosphor_density_is_drawn_under_the_traces`: `cells=179349 uploaded=179349` on the moved frame and `uploaded=0` on the identical one after it, with the trace's stroke keeping its own colour over the ink). The suite is **396 cases, 0 failed** and all four ctest entries pass.
135 lines
8.0 KiB
Markdown
135 lines
8.0 KiB
Markdown
# Building and testing
|
|
|
|
## Presets and options
|
|
|
|
Four configure/build presets live in `CMakePresets.json`:
|
|
|
|
| preset | binaryDir | what it builds |
|
|
|---|---|---|
|
|
| `linux-debug` | `build/debug` | Debug; tests, examples and all four adapters |
|
|
| `linux-release` | `build/release` | Release; `PLOT_BUILD_TESTS=OFF` (so the installed `libplot_core.a` carries none of the test-only counter instrumentation); examples and all four adapters |
|
|
| `linux-asan` | `build/asan` | Debug with `PLOT_SANITIZE=address`; tests and all four adapters |
|
|
| `linux-coverage` | `build/cov` | the instrumented tree behind `tools/coverage.sh`: `--coverage -O0 -g`, `PLOT_COVERAGE=ON`, tests on, adapters and examples off |
|
|
|
|
The options (`cmake/plot_options.cmake`) and their defaults:
|
|
|
|
| option | default | meaning |
|
|
|---|---|---|
|
|
| `PLOT_BUILD_TESTS` | `ON` | build the test suite (needs EGL) |
|
|
| `PLOT_BUILD_EXAMPLES` | `OFF` | build the demos |
|
|
| `PLOT_BUILD_GLFW` | `OFF` | build the GLFW adapter and its demo |
|
|
| `PLOT_BUILD_IMGUI` | `OFF` | build the Dear ImGui adapter and its demo (ImGui is fetched at configure time) |
|
|
| `PLOT_BUILD_QT6` | `OFF` | build the Qt6 adapter and its demo |
|
|
| `PLOT_BUILD_GTK4` | `OFF` | build the GTK4 adapter and its demo |
|
|
| `PLOT_BUILD_TTF_FONT` | on iff `third_party/stb_truetype.h` exists | build the optional `plot::text::TrueTypeFont` backend |
|
|
| `PLOT_INSTALL` | `ON` | generate install/export rules for `find_package(plot)` |
|
|
| `PLOT_SANITIZE` | `""` | sanitizer list for `-fsanitize=` (e.g. `address`) |
|
|
| `PLOT_COVERAGE` | `OFF` | add the `coverage` target (requires an instrumented tree) |
|
|
|
|
Adapters and examples are off by default, so the core library and its tests build on a bare
|
|
toolchain. Each example is guarded by the adapter target it needs, so
|
|
`-DPLOT_BUILD_EXAMPLES=ON` without the matching adapter is a no-op rather than a configure
|
|
error.
|
|
|
|
## Running the suite
|
|
|
|
```sh
|
|
cmake --preset linux-debug
|
|
cmake --build build/debug
|
|
ctest --test-dir build/debug --output-on-failure
|
|
```
|
|
|
|
ctest registers four tests: `plot_tests` (the test binary), the two header/umbrella build
|
|
checks (`plot_headers_self_contained`, `plot_umbrella_covers_public_headers`) and
|
|
`plot_umbrella_check`. The `plot_tests` binary itself runs **396 cases** in the `linux-debug`
|
|
preset; its harness prints one line per case and a final `396 cases, 0 failed` summary line.
|
|
The case counts per file are the `PLOT_TEST(...)` declarations under `tests/` — recount them
|
|
(`grep -c '^PLOT_TEST(' tests/test_*.cpp`) after adding or removing cases.
|
|
|
|
`PLOT_TEST_FILTER=<substring>` runs only the cases whose name contains that substring, and
|
|
is for working *on* a case rather than for checking the library: most of the render cases
|
|
create their own EGL context and read pixels back, so the whole binary is far slower than
|
|
the one case being edited and its one line of measured output scrolls past 376 others. The
|
|
summary line still counts the whole suite, so a filtered run says `396 cases, 0 failed`
|
|
having run one — it is never evidence that the suite passes. Unset, every case runs.
|
|
|
|
## Install layout
|
|
|
|
`cmake --install` follows `GNUInstallDirs`, so every path honours the standard cache
|
|
variables (`CMAKE_INSTALL_LIBDIR`, `CMAKE_INSTALL_INCLUDEDIR`, …) and their distribution
|
|
defaults — plain `lib`, `include` and `share` unless a packager overrides them:
|
|
|
|
| prefix-relative path | what |
|
|
|---|---|
|
|
| `lib/` | the `plot_core` archive (and `libplot_core.so` with its version and SONAME symlinks when built with `BUILD_SHARED_LIBS=ON`) |
|
|
| `include/plot/` | every public header, including the generated `plot/version.hpp` (`plot::version::major/minor/patch/string` and the `PLOT_VERSION_*` macros) |
|
|
| `lib/cmake/plot/` | the CMake package: `plotConfig.cmake`, `plotConfigVersion.cmake` (Compatibility **SameMinorVersion**, so `find_package(plot 0.1 …)` accepts 0.1.x only), `plotTargets.cmake` |
|
|
| `lib/pkgconfig/plot.pc` | pkg-config metadata for consumers whose build is not CMake |
|
|
| `share/licenses/plot/` | `LICENSE` (MIT) and `licences/OFL-1.1.txt` (the embedded font) |
|
|
|
|
Adapters that were built and exported install themselves alongside the core (their headers
|
|
under `include/<adapter>/`, their targets in the same package).
|
|
|
|
## Headless demo modes
|
|
|
|
Each demo supports two environment variables, implemented once and reused:
|
|
|
|
- `PLOT_DEMO_EXIT_AFTER_MS=<n>` — stop the loop after `n` milliseconds and return. Unset,
|
|
unparsable or not positive means "run until the window is closed". A run with a deadline
|
|
creates its window hidden, so an automated run never flashes a window on a real display,
|
|
and its frame times are not throttled by a vblank.
|
|
- `PLOT_DEMO_SCREENSHOT=<path>` — on that final frame, write it as a binary PPM before the
|
|
swap. The GLFW host writes the framebuffer with `Renderer::dump_frame_ppm()`; the ImGui
|
|
demo writes the whole framebuffer, while Qt and GTK write their widget's/area's own
|
|
framebuffer (their toolkits' chrome lives outside it).
|
|
|
|
That pair is what lets CI run the GUI demos under `xvfb-run` with no display access and no
|
|
screen capture (the invocations are in [embedding.md](embedding.md)).
|
|
|
|
Three demos add env-gated **self-checking** modes. These are verification affordances for
|
|
the project's own testing, driven through the real host and its own controllers — they are
|
|
not a second implementation of anything, and they exit non-zero if a measured property fails:
|
|
|
|
| variable | demo | what it drives |
|
|
|---|---|---|
|
|
| `PLOT_DEMO_FOLLOW=1` | `plot_glfw_demo` | the live-follow sequence: three wheel notches and a pan on a `XFollow::Live` axis, printing the range width, the distance behind the newest sample and the follow state at each step |
|
|
| `PLOT_DEMO_REGIONS` (`=hot` to hover a bound) | `plot_glfw_demo` | the direct-manipulation sequence: freeze the view, place a region, pan 100 px with the press outside it, and check the region came along with its width untouched |
|
|
| `PLOT_DEMO_SYNC=1` | `plot_multiplot_demo` | the synced-follow check: the three rows hold one range and its right edge keeps tracking the newest sample through a zoom and a pan on different rows |
|
|
| `PLOT_DEMO_CROSSHAIR=<row>` | `plot_multiplot_demo` | parks the pointer in a row each frame so a headless screenshot shows the one horizontal line the hovered row draws |
|
|
|
|
(`plot_glfw_demo` also accepts `PLOT_DEMO_CROSSHAIR=1`, which parks the pointer at the centre
|
|
of the data area so the two-line crosshair has ink to measure.)
|
|
|
|
## Coverage
|
|
|
|
```sh
|
|
tools/coverage.sh # from the repository root
|
|
cmake --build build/cov --target coverage # the same thing, through CMake
|
|
```
|
|
|
|
The script configures `build/cov` from the `linux-coverage` preset, builds it, clears the
|
|
`.gcda` counters, runs the whole suite, captures `src/**` with `lcov`, renders an HTML report
|
|
to `build/cov/html/index.html`, prints the per-file table, and **exits non-zero when a floor
|
|
is violated**. It needs `cmake`, `ninja`, `ctest`, `lcov`, `genhtml` and `python3`, and exits
|
|
`2` with a message when one is missing.
|
|
|
|
The floors are enforced by `tools/coverage_floor.py`:
|
|
|
|
| scope | floor |
|
|
|---|---|
|
|
| every file under `src/` | **80%** of its instrumented lines |
|
|
| `src/` as a whole | **90%** of instrumented lines |
|
|
|
|
Branch coverage is deliberately off. This page carries no measured totals — a number written
|
|
here would be stale the moment `src/` moved, and the report is reproducible: the method, the
|
|
per-file table and the floor verdict live in [docs/coverage.md](coverage.md), which
|
|
`tools/coverage.sh` rewrites from the very run that measured them. Re-run the command for the
|
|
live numbers.
|
|
|
|
**One thing to know about the coverage preset:** it builds **379 of the 396 cases**. The 17
|
|
that are missing are the adapter cases that need an adapter target to exist — 11 in
|
|
`test_imgui_widget.cpp` and 6 in `test_glfw_host.cpp` — and the coverage preset turns the
|
|
adapters off. The toolkit-free adapter seams still run there: `test_qt_pointer.cpp` (5 cases)
|
|
and `test_gtk_input.cpp` (11 cases) compile without Qt or GTK. So the coverage number measures
|
|
the library plus its unit suite, not the adapter bodies (which the headless demo runs cover).
|