0 Fork 0

Files

T

Martino Ferrari 6a6915e64e feat: a plot can carry a phosphor density, one image for every acquisition

`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.

2026-10-16 17:25:39 +02:00

8.0 KiB

Raw Blame History

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

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).

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

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, 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).

8.0 KiB Raw Blame History