Files
hyprland-headless-stream-pl…/src/hhstream/_protocol/wayland/wl_fixes.py
T
Hermenix a7d9357b43 capture: an in-process Wayland backend, and the measurements that justify it
The frame server could only capture by running a program once per frame
(grim). That works, but ~95% of a grim frame is waiting -- fork, connect,
handshake, round trip -- not encoding, and grim makes the compositor import
a *new* shared-memory buffer for every single frame.

This adds `--capture wayland[:OUTPUT]`: one long-lived zwlr-screencopy-v1
client per server, with one shm buffer reused for the whole run, capturing
inside the process. Measured here at 1280x720 (spike capture-speed, 200
frames; live re-check on Virtual-1, 60 frames):

    grim (subprocess)    117.3 ms/frame   8.1 fps   compositor 116.4 ms
    grim-rs (Rust crate) 124.6 ms/frame   7.5 fps   compositor 123.1 ms
    this backend          78.0 ms/frame  13.9 fps   compositor  67.5 ms

    live, PNG both sides: this 128.5 ms/frame against grim's 389.3 ms (3.0x)

Three findings, each of which shaped the code:

* The win is buffer reuse, not language. grim and grim-rs both hand the
  compositor a fresh buffer per frame, which is why their compositor CPU is
  nearly double ours. The per-frame allocate-copy-swizzle that grim-rs pays
  was measured in isolation at 2.4 ms of *client* time; the rest of its
  deficit lands inside the compositor.
* ext-image-copy-capture-v1 is no faster (78.0 vs 77.7 ms) and its
  create_frame path appears in a Hyprland segfault stack, so this keeps the
  deprecated protocol grim uses. The switch is one constant when that crash
  is fixed.
* PNG only, deliberately: PNG is the one encoding this package produces
  without a dependency, so --format jpeg is refused rather than publishing a
  Hello whose MIME type the frames do not have. A PNG frame is ~2.1 MB
  against ~120 KB for JPEG q80, which is why the command backend stays the
  default and why a libjpeg-turbo encoder (1.7 ms/frame, measured) is the
  obvious follow-up.

The timeout is the load-bearing part of the client: pywayland only reads
events from read()/dispatch(block=True), neither of which takes a timeout,
and the server captures in a worker thread where SIGALRM is unavailable. It
therefore polls the display fd itself, so a compositor that stops answering
produces a CaptureError instead of a capture thread that never returns.

The protocol bindings are vendored under src/hhstream/_protocol/ exactly the
way hhstream_pointer already vendors its two, with regenerate.py recording
where each XML came from. No new dependency: pywayland was already required
by the input driver.

Contract: the new server flag and the two new module options are documented
in docs/CONTRACT.md, and docs/ARCHITECTURE.md's prediction that a native
screencopy client would be "a swap rather than a rewrite" is now the record
of what the swap cost.

Unit suite: 977 passed, 2 skipped, 0 failed (nix build -L .#checks.unit).
The live numbers were taken on this VM against the real compositor.
2026-10-11 20:34:33 +00:00

152 lines
5.0 KiB
Python

# This file has been autogenerated by the pywayland scanner
# Copyright © 2008-2011 Kristian Høgsberg
# Copyright © 2010-2011 Intel Corporation
# Copyright © 2012-2013 Collabora, Ltd.
#
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation files
# (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge,
# publish, distribute, sublicense, and/or sell copies of the Software,
# and to permit persons to whom the Software is furnished to do so,
# subject to the following conditions:
#
# The above copyright notice and this permission notice (including the
# next paragraph) shall be included in all copies or substantial
# portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
from __future__ import annotations
import enum
from pywayland.protocol_core import (
Argument,
ArgumentType,
Global,
Interface,
Proxy,
Resource,
)
from .wl_registry import WlRegistry
class WlFixes(Interface):
"""Wayland protocol fixes
This global fixes problems with other core-protocol interfaces that cannot
be fixed in these interfaces themselves.
"""
name = "wl_fixes"
version = 2
class error(enum.IntEnum):
invalid_ack_remove = 0
class WlFixesProxy(Proxy[WlFixes]):
interface = WlFixes
@WlFixes.request()
def destroy(self) -> None:
"""Destroys this object
"""
self._marshal(0)
self._destroy()
@WlFixes.request(
Argument(ArgumentType.Object, interface=WlRegistry),
)
def destroy_registry(self, registry: WlRegistry) -> None:
"""Destroy a :class:`~pywayland.protocol.wayland.WlRegistry`
This request destroys a :class:`~pywayland.protocol.wayland.WlRegistry`
object.
The client should no longer use the
:class:`~pywayland.protocol.wayland.WlRegistry` after making this
request.
The compositor will emit a :func:`WlDisplay.delete_id()
<pywayland.protocol.wayland.WlDisplay.delete_id>` event with the object
ID of the registry and will no longer emit any events on the registry.
The client should re-use the object ID once it receives the
:func:`WlDisplay.delete_id()
<pywayland.protocol.wayland.WlDisplay.delete_id>` event.
:param registry:
the registry to destroy
:type registry:
:class:`~pywayland.protocol.wayland.WlRegistry`
"""
self._marshal(1, registry)
@WlFixes.request(
Argument(ArgumentType.Object, interface=WlRegistry),
Argument(ArgumentType.Uint),
version=2,
)
def ack_global_remove(self, registry: WlRegistry, name: int) -> None:
"""Acknowledge global removal
Acknowledge the removal of the specified global.
If no global with the specified name exists or the global is not
removed, the :func:`WlFixes.invalid_ack_remove()` protocol error will
be posted.
Due to the Wayland protocol being asynchronous, the wl_global objects
cannot be destroyed immediately. For example, if a wl_global is removed
and a client attempts to bind that global around same time, it can
result in a protocol error due to an unknown global name in the bind
request.
In order to avoid crashing clients, the compositor should remove the
wl_global once it is guaranteed that no more bind requests will come.
The :func:`WlFixes.ack_global_remove()()` request is used to signal to
the compositor that the client will not bind the given global anymore.
After all clients acknowledge the removal of the global, the compositor
can safely destroy it.
The client must call the :func:`WlFixes.ack_global_remove()()` request
in response to a :func:`WlRegistry.global_remove()()
<pywayland.protocol.wayland.WlRegistry.global_remove()>` event even if
it did not bind the corresponding global.
:param registry:
the registry object
:type registry:
:class:`~pywayland.protocol.wayland.WlRegistry`
:param name:
unique name of the global
:type name:
`ArgumentType.Uint`
"""
self._marshal(2, registry, name)
class WlFixesResource(Resource):
interface = WlFixes
class WlFixesGlobal(Global):
interface = WlFixes
WlFixes._gen_c()
WlFixes.proxy_class = WlFixesProxy
WlFixes.resource_class = WlFixesResource
WlFixes.global_class = WlFixesGlobal