Files
hyprland-headless-stream-pl…/docs/TODO/cursor-visibility-in-captures.md
T
Hermenix 4b5cb5197a docs+examples: log the cursor marker as open, and film each desk on its own
The marker is now written up as the *open* item rather than a research note: it
is not implemented, the video went out without it, and everything else about the
pointer is exact and readable.

proof-video.py is rewritten for desks, one command, no arguments. It films the
session's own output with `record --output` instead of the published socket --
with desks, the socket carries every output stitched together, so a viewer would
watch two thirds wallpaper. The scrolling beats are real pointer axis events,
down twice and back up once, so the movement cannot be mistaken for a page that
merely loaded a different part of itself.
2026-10-03 19:54:08 +00:00

64 lines
3.8 KiB
Markdown

# The compositor draws no cursor for a virtual pointer
## What is open
**The overlay marker is not implemented.** The acceptance video was recorded
without it, so the frames show the pointer's *effects* — a page that scrolled,
a tab that opened — and never the pointer itself. Implement it by stamping
`hyprctl cursorpos` into each frame, mapped into the stitched layout, and label
it as an overlay wherever the frame is published. Nothing else about the pointer
is blocked: position, clicks and scrolling are all exact and all readable.
## The issue — answered, and it is not a capture setting
The pointer moves exactly where it is told, and **nothing is drawn**. Every
plausible cause was eliminated by test rather than by argument:
| candidate | test | result |
| --- | --- | --- |
| `grim` not asking for the cursor | Hyprland's `Screencopy.cpp` takes an `overlayCursor` argument, so `-c` was added to the capture command | no change at the pointer |
| hardware cursor plane | `cursor:no_hardware_cursors` | already `true` |
| no cursor theme installed | installed `adwaita-icon-theme`, present at `/run/current-system/sw/share/icons/Adwaita` (63 cursor files) | no change |
| theme not reaching the cursor manager | `hyprctl setcursor Adwaita 24` at runtime | no change — and note `env = XCURSOR_THEME` in the compositor's own config sets variables for **launched programs**, not for the compositor, which is where my first attempt put it |
| hyprcursor rather than X11 themes | `cursor:enable_hyprcursor` | already `false`: the X11 path |
The decisive measurement: park the pointer at two points that both miss the
browser's toolbar, capture each, diff them — **zero differing pixels**. The only
differences that ever appear are in the URL bar, which is a blinking text caret.
The cause is the protocol. `zwlr_virtual_pointer_v1` has no request to set a
cursor image, and Hyprland renders a cursor only for a pointer that has an image
to draw. A virtual pointer warps the position and has no surface behind it, so
the compositor has nothing to composite: every capture is faithful, and the
cursor is simply not in it.
## Ideas
1. **Stamp the position into the frames, labelled as an overlay.** *(recommended)*
The frame server can ask `hyprctl cursorpos` — this machine answers it exactly
— map it into the stitched frame, and draw a marker there. It is not fiction:
it is the compositor's own answer, drawn where the compositor says the pointer
is, precisely because the compositor draws nothing. It has to be *named* as an
overlay in the code and in anything published from it.
2. **Leave the pixels alone and prove motion by readout.** `hyprctl cursorpos` is
exact: 0.8 across a 1280-wide desk came back as 3584 with the desk starting at
2560. Gates can assert position with no image at all — cheaper and stronger
than a pixel check.
3. **Ask upstream, or try a newer compositor.** Whatever makes a cursor appear
for a virtual pointer is the real fix. Not attempted.
4. **A synthetic pointer client.** Impossible for a plain client (it cannot draw
over another window); it would need a layer-shell surface, which is more
machinery than (1) for the same result.
## Why it matters
Everything about the pointer is verifiable except the part a person can see. That
a click landed *here* is provable by readout and by what changed, but a viewer
cannot tell **where** it happened — and a click on the wrong element and a click
on the right one both produce a screen that changed.
Worth recording: this took three wrong answers (`-c`, the theme, the compositor
setting) before the right one, and two of those came from reasoning rather than
measurement. What settled it was boring — capture the same screen twice with the
pointer in two places and diff them. That should have been the first move.