Skip to content

feat: add --freeze-only for use as a screen freeze - #170

Closed
SeraphimKa wants to merge 2 commits into
hyprwm:mainfrom
SeraphimKa:freeze-only
Closed

SeraphimKa wants to merge 2 commits into
hyprwm:mainfrom
SeraphimKa:freeze-only

Conversation

@SeraphimKa

Copy link
Copy Markdown

Adds -F / --freeze-only: freeze the screen, take no input, exit only on a signal.

(Builds on #169 — the button_state fix — since both touch the same handler. Happy to rebase if that lands first or gets dropped.)

Why this belongs in hyprpicker

hyprpicker -r -z is already the de-facto screen freeze for Wayland screenshot tooling. grimblast, in hyprwm's own contrib repo, does exactly this in freezescreen() and kills it with pkill hyprpicker; Hyprshot, hyprsnap, omarchy and HyDE all do the same thing.

This is already treated as abuse rather than a feature — #152 says it outright: "if you (ab)use Hyprpicker to freeze the screen and then kill the process". That framing is the problem this PR tries to close: the abuse is not going to stop while hyprwm's own tool depends on it, so it is better supported than tolerated.

The obvious objection is "use wayfreeze". In practice projects have moved the other way — omarchy migrated from wayfreeze to hyprpicker — so the pattern is not going away, and today it is silently broken for everyone using it.

Broken how: in that role hyprpicker is still a picker. It asks for EXCLUSIVE keyboard interactivity and sets no input region, so it competes for input with the selection tool layered above it, and its pointer handler exits the process on a button event. The freeze dies on the first click of the selection it exists to support, and the user finishes the drag against a live screen believing it is frozen.

basecamp/omarchy#5468 is the same collision in a worse form — Escape never reaches slurp and input is stuck until the user switches to a TTY. Their proposed response (#5603, open, unmerged) is to disable the freeze by default rather than fix it. Gustash/Hyprshot#114 reports the same lockup.

What it does

  • set_keyboard_interactivity(0) and an empty input region, so the compositor routes it no input and the surface above keeps both pointer and keyboard.
  • Every pointer and keyboard handler returns immediately — a backstop for compositors that deliver input to a layer surface regardless of its input region.
  • Reuses the existing render-inactive branch rather than adding one: that branch is gated on m_bCoordsInitialized, which only the pointer enter handler sets, so it now also accepts m_bFreezeOnly. Without that the surface maps fully transparent — no error, no log, screen simply not frozen. This gating is also what Screen does not freeze until the mouse is moved #119 ran into ("Screen does not freeze until the mouse is moved"), where the workaround was to move the mouse between starting hyprpicker and starting slurp. Worth knowing if you touch this path.
  • SIGINT and SIGHUP are now handled alongside SIGTERM, completing Temporary files fill up /run if hyprpicker doesn't exit cleanly #152 (closed by a SIGTERM-only fix; the other two still strand files — I measured 24 MB per Ctrl-C on one 1080p output). They previously bypassed finish(), so ~SPoolBuffer never unlinked the shm files and every interrupted run stranded one per monitor in XDG_RUNTIME_DIR (8 MB each at 1080p — the Temporary files fill up /run if hyprpicker doesn't exit cleanly #152 failure mode). Ctrl-C on a foreground freeze is the natural way to stop one, so --freeze-only makes that path matter.
  • Signal exit in freeze-only reports 0, not 1. A freeze has no color to report and a signal is its normal end; exiting non-zero made every wrapper script see failure.

Notes

  • -F implies -r (its branch precedes the forceInactive check, so all outputs freeze). Documented in the man page.
  • -F makes the output-related flags (-a -n -f -o -b -l -N -s -u -z -d) no-ops, since nothing is ever picked. Not diagnosed as an error, matching how the existing -N ... (requires -a) dependency is handled.
  • CPU is unchanged from the existing architecture — the frame callback re-arms at 60 Hz. Measured 8.9% of a core for -F versus 21.1% for stock -r, i.e. -F is already cheaper than what these tools run today. Not re-arming in freeze mode is an obvious follow-up but touches the render loop, so I left it out.

Testing

Hyprland 0.56.2, single 1080p output.

-F stock -r
set_keyboard_interactivity 0 1
set_input_region empty region not sent
wl_pointer enter/motion/button received 0 / 0 / 0 3 / 133 / yes
wl_keyboard.enter received 0 yes

Screen genuinely frozen (two grim captures 2.5 s apart byte-identical, against a control that differs), with and without -r.

Also exercised on a second output added with hyprctl output create headless, set to fractional scale 1.25 and transform,1 (90 deg): one layer surface per output, both frozen, the rotated head captured at the correct 1080x1920 with real content on both. Removing that output mid-freeze leaves the process alive, drops its layer surface, keeps the remaining head frozen, and still exits 0 with nothing stranded. A 12 s soak held RSS flat at 35936 kB and fds at 4. Two concurrent -F instances coexist and tear down cleanly. All flag combinations tested start, freeze, and exit cleanly with no stray processes, layers or temp files. SIGTERM/SIGINT/SIGHUP all exit 0 leaving nothing behind. Behaviour without -F is unchanged. clang-format and the man page render clean.

The pointer button handler took button_state and never read it, so it
picked on whichever edge arrived first.

A press edge is the intended trigger and is self-limiting: outputColor()
ends in finish(), which exits, so the release that follows is never
dispatched. A release edge on its own is not. If a button is already
held when hyprpicker maps -- launched from a mouse-bound keybind, or
started while the user is mid-drag -- the first pointer event it sees is
the release, and it picks a color the user never aimed at.
hyprpicker is widely used as a screen freeze underneath a region
selection tool rather than as a picker. grimblast -- in hyprwm's own
contrib repo -- does exactly this in freezescreen(), and Hyprshot,
hyprsnap, omarchy and HyDE all spawn `hyprpicker -r -z &`, run slurp,
then kill it.

In that role hyprpicker is still a picker, and two things make it
unsuitable. It asks for EXCLUSIVE keyboard interactivity and sets no
input region, so it competes for input with the surface layered above
it; and its pointer handler exits the process on a button event. The
freeze therefore dies on the first click of the selection it exists to
support, and the user finishes the drag against a live screen believing
it is frozen. omacom/omarchy#5468 is the same collision in a worse
form, where Escape never reaches slurp and input is stuck until the user
switches to a TTY.

--freeze-only makes that role explicit and safe:

  * keyboard interactivity NONE and an empty input region, so the
    compositor routes it no input and the surface above keeps both
    pointer and keyboard;
  * every pointer and keyboard handler returns immediately, as a
    backstop on compositors that deliver input to a layer surface
    regardless of its input region;
  * the render path is reused rather than duplicated: the existing
    render-inactive branch is gated on m_bCoordsInitialized, which only
    the pointer enter handler sets, so it additionally accepts
    m_bFreezeOnly. Without that the surface maps fully transparent and
    nothing appears frozen at all.

SIGINT and SIGHUP are now handled alongside SIGTERM. They previously
killed the process before finish() ran, so ~SPoolBuffer never unlinked
the shm files and each interrupted run stranded one per monitor in
XDG_RUNTIME_DIR (8 MB each at 1080p). Ctrl-C on a foreground freeze is
the obvious way to stop one, so --freeze-only makes that path matter.
Exiting via a signal in freeze-only now reports 0 rather than 1: a
freeze has no color to report and a signal is its normal end, so a
non-zero status would make every script wrapping it see failure.

Verified on Hyprland 0.56.2 with WAYLAND_DEBUG: with -F the client
receives no wl_pointer.enter/motion/button and no wl_keyboard.enter,
where without it receives all of them. The screen is genuinely frozen
(two captures 2.5s apart are byte-identical, against a control that is
not), with and without -r. Behaviour without -F is unchanged.
@vaxerski

Copy link
Copy Markdown
Member

what's the point of passing through input events? I can understand the keyboard grab, but why be transparent to pointer events?

@SeraphimKa

Copy link
Copy Markdown
Author

You're right, and more than I'd credited. I went to measure it and the measurement says the keyboard grab is doing most of this on Hyprland.

Stock hyprpicker and slurp both request set_keyboard_interactivity(1), so both land in m_exclusiveLSes (LayerSurface.cpp:188), and layerSurfaceAt walks that list in reverse (ViewHitTester.cpp:330). Whichever exclusive layer mapped last takes pointer focus, over the top of actual stacking. WAYLAND_DEBUG on both clients, no clicks, merged on one clock:

14:24:22.196634  slurp       wl_surface.enter(output)     <- slurp maps
14:24:22.196640  slurp       wl_pointer.enter
14:24:22.210526  slurp       wl_pointer.leave
14:24:22.210550  hyprpicker  wl_surface.enter(output)     <- hyprpicker maps, 14ms later
14:24:22.210556  hyprpicker  wl_pointer.enter (723.72, 749.24)
14:24:22.210990  hyprpicker  motion x73, for the remaining 470ms

hyprpicker's enter coordinates are identical to slurp's last motion, so the pointer never left slurp's region. Focus moved because hyprpicker mapped, not because the cursor did. Setting interactivity to 0 keeps it out of that list, so on Hyprland today the keyboard change alone would fix the failure I set out to fix.

Interactivity alone isn't enough though. ViewHitTester.cpp:355 skips a surface whose input region is empty and not infinite, and without that hyprpicker stays a hit-test candidate. Starting slurp first so the picker maps last, 3.5s, no clicks:

interactivity 0, no input region     wl_pointer.enter 1, motion 2
interactivity 0 + empty input region wl_pointer.enter 0, motion 0
stock (interactivity 1)              wl_pointer.enter 1, motion 3362, keyboard.enter 1

Dropping interactivity stops it stealing the keyboard and stops the motion firehose, but it still takes pointer focus and pulls events off the surface above. Only the empty region gets it to zero.

The ordering matters because a caller can't rely on it. In the capture above hyprpicker mapped 14ms after slurp despite being launched first and waited for, since hyprctl layers reports a layer surface before it maps, so the usual "start hyprpicker, poll, then start slurp" sequence races.

One tradeoff: used standalone with nothing above it, -F means clicks land on whatever sits under the frozen image, which they can't see.

If you'd rather the flag only changed interactivity, I'll drop the input region. That does cost something: if hyprpicker maps last, it takes pointer focus and the guards swallow motion as well as buttons, so the selection above it stops working entirely rather than just losing a click.

@vaxerski

Copy link
Copy Markdown
Member

it's clear that this is all ai-generated including the descriptions. Please read the AI policy, I do not wish to be talking to a claude agent via github MRs.

@vaxerski vaxerski closed this Aug 30, 2026
@SeraphimKa
SeraphimKa deleted the freeze-only branch August 31, 2026 20:25
@SeraphimKa

Copy link
Copy Markdown
Author

Sorry about that, my bad for not reading the rules.

I think the code did fix something, since hyprpicker is used for its screen freezing (e.g to take a screenshot). I myself have been using it with a script running grim and slurp for that purpose, and it sometimes gave me a double fullscreen overlay which wouldn't allow me to take the screenshot unless I closed the first one by clicking or pressing escape and this code seemed to fix it.

Thanks for all the work you're doing man

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants