tools: a remote display script, Xvfb plus x11vnc over an SSH tunnel

Over SSH with X11 forwarding the app does not appear: no usable Vulkan device means GTK cannot
create a swapchain, and `--renderer cairo` fixes that half only -- the plot is a GtkGLArea and asks
for its own GL context, so indirect GLX is the second wall. A virtual X server on the machine that
runs the app sidesteps both, because the GL context then lives next door to the samples.

`tools/udpscope-remote.sh` starts Xvfb on a free display, runs the app there with
`--renderer cairo`, and serves the screen through x11vnc bound to localhost only -- the SSH tunnel
is the authentication, so `-nopw` is deliberate and `-localhost` is what keeps a mistake from being
a remotely reachable screen. It prints the tunnel and viewer commands rather than assuming a
client, mentions the websockify/noVNC route for a browser, and takes the X and VNC servers with it
when the app exits. `--no-vnc` leaves just the virtual display, for another viewer; the preflight
names the install command instead of a bare "command not found".

Verified: the preflight refuses with exit 1 and the install line when x11vnc is absent; with
`--no-vnc` the app runs against the virtual display and reads `buffer allocated: 4 channels` with
no Vulkan warning and no critical, and no Xvfb is left behind when the timeout ends it. That run
also exercises what the earlier log showed by omission: nothing is enabled, so a working app
plots nothing.

The README's Limitations gains the bullet a person actually needs -- the exact warning string, that
both halves need the software preset, the script itself, and that a window which appears but stays
empty usually means no signal is enabled.
This commit is contained in:
Martino Ferrari committed 2026-10-28 16:16:32 +01:00
1 parent fcf268d249
commit f3f8f67a62
2 files changed
+145

No files matched your search

+10
View File
@@ -2893,6 +2893,16 @@ silence timeout and then resumes, which is the EMI case end to end.
## Limitations
- **A remote display needs the software renderer, and the plot is empty until a signal is
enabled.** Over SSH with X11 forwarding there is no usable Vulkan device: GTK cannot create a
swapchain (`vkCreateSwapchainKHR … VK_ERROR_INITIALIZATION_FAILED`) and the window never appears
even though the stream connects and its CONFIG parses. `--renderer cairo` selects the software
preset for **both** halves — GTK's renderer and the plot's own GL context, which is a
`GtkGLArea` and asks for one regardless of what GSK draws with — and
`tools/udpscope-remote.sh` runs the app against a virtual X server with a VNC view carried over
an SSH tunnel, avoiding X11 forwarding altogether. If a window does appear but stays empty, check
that a **signal is enabled**: signals start disabled, so a session with none switched on plots
nothing and prints no `buffer allocated:` line, by design rather than as a fault.
- **Multi-element (vector/matrix) signals are acquired with a zero-order hold.**
`udps_client` decodes exactly one *sample* of `num_rows x num_cols` values per
DATA packet for such a signal, regardless of the publish mode, so it cannot be