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

3.8 KiB

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.