Files
hyprland-headless-stream-pl…/docs/TODO/cursor-visibility-in-captures.md
T
Hermenix cbf58f6443 docs: two TODO items closed, and the cursor question answered
Closed: containers-do-not-bind and pointer-needs-a-container-or-a-screen. Both
were the same defect seen from two sides, and both are fixed by assigning
windows by pid -- two sessions now hold two outputs with a real browser on each,
and the pointer aims at a desk that has something in it.

The cursor item is rewritten with the answer rather than the speculation: the
compositor draws no cursor image for a virtual pointer, so no capture setting
can make one appear. The evidence is in the file, including the three wrong
answers that came before it and the boring measurement that settled it.

New item: killing a session left two browsers alive, found by counting windows
rather than sessions.
2026-10-03 19:45:42 +00:00

3.3 KiB

The compositor draws no cursor for a virtual pointer

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.