Files
hyprland-headless-stream-pl…/tests/unit/test_png.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

122 lines
4.6 KiB
Python

"""`hhstream.png`: the hand-rolled PNG encoder, checked against zlib itself.
There is no image library in the unit environment (the whole point of this
encoder is that it needs none), so the decoder below is written from the PNG
spec too. That is not a weakness of the test: it re-derives the scanlines from
the file the encoder produced and compares them with the pixels that went in,
which is exactly the property that matters -- a wrong stride, a wrong colour
type or a byte order slip all show up as a mismatch rather than as a file that
merely starts with the right eight bytes.
"""
from __future__ import annotations
import struct
import zlib
import pytest
from hhstream.png import encode_rgb
SIGNATURE = b"\x89PNG\r\n\x1a\n"
def decode(png: bytes) -> tuple[int, int, bytes]:
"""Return (width, height, rgb scanlines) for a PNG this encoder can produce."""
assert png.startswith(SIGNATURE), "missing PNG signature"
offset = len(SIGNATURE)
width = height = None
idat = b""
while offset < len(png):
(length,) = struct.unpack(">I", png[offset:offset + 4])
kind = png[offset + 4:offset + 8]
payload = png[offset + 8:offset + 8 + length]
crc = png[offset + 8 + length:offset + 12 + length]
assert struct.unpack(">I", crc)[0] == zlib.crc32(kind + payload) & 0xFFFFFFFF, (
f"bad CRC on {kind!r} chunk -- the file is corrupt"
)
if kind == b"IHDR":
width, height, depth, color, comp, filt, interlace = struct.unpack(">IIBBBBB", payload)
assert (depth, color, comp, filt, interlace) == (8, 2, 0, 0, 0)
elif kind == b"IDAT":
idat += payload
offset += 12 + length
assert width is not None and height is not None, "no IHDR chunk in the file"
raw = zlib.decompress(idat)
stride = width * 3
assert len(raw) == height * (1 + stride), "the scanline payload is the wrong length"
out = bytearray()
for row in range(height):
start = row * (1 + stride)
assert raw[start] == 0, "every scanline should be written unfiltered"
out += raw[start + 1:start + 1 + stride]
return width, height, bytes(out)
def bgrx(width: int, height: int, stride: int | None = None) -> bytes:
"""A frame in the compositor's memory order: B, G, R, X per pixel."""
stride = stride if stride is not None else width * 4
out = bytearray()
for y in range(height):
row = bytearray()
for x in range(width):
row += bytes(((x * 3) % 256, (y * 5) % 256, (x + y) % 256, 0x00))
row += b"\xee" * (stride - width * 4) # row padding, if any
out += row
return bytes(out)
def test_pixels_round_trip_in_the_right_channel_order():
frame = bgrx(4, 2)
width, height, rgb = decode(encode_rgb(4, 2, 16, frame))
assert (width, height) == (4, 2)
# Pixel (x, y) went in as B,G,R,X; it must come out as R,G,B.
for y in range(2):
for x in range(4):
b, g, r, _ = frame[(y * 4 + x) * 4:(y * 4 + x) * 4 + 4]
assert rgb[(y * 4 + x) * 3:(y * 4 + x) * 3 + 3] == bytes((r, g, b)), (
f"channel order is wrong at ({x}, {y})"
)
def test_a_padded_stride_is_honoured_rather_than_assumed():
"""`stride` is the compositor's row pitch, not `width * 4`.
Assuming it would shear the image, which is the bug grim 1.5 shipped -- so
the padding bytes below are deliberately not black: if they leak into the
output the comparison fails.
"""
width, height, stride = 3, 2, 20 # 12 meaningful bytes, 8 bytes of padding
frame = bgrx(width, height, stride)
_, _, rgb = decode(encode_rgb(width, height, stride, frame))
assert rgb == b"".join(
bytes(reversed(frame[(y * stride + x * 4):(y * stride + x * 4) + 3]))
for y in range(height)
for x in range(width)
)
def test_a_memoryview_of_a_mapping_is_accepted():
"""The caller passes `memoryview(shm_map)`, not `bytes`."""
frame = bgrx(2, 2)
assert encode_rgb(2, 2, 8, memoryview(frame)) == encode_rgb(2, 2, 8, frame)
@pytest.mark.parametrize(
"kwargs, message",
[
(dict(width=0, height=4, stride=0), "positive size"),
(dict(width=4, height=0, stride=16), "positive size"),
(dict(width=4, height=4, stride=8), "too small"),
],
)
def test_bad_geometry_is_rejected_before_anything_is_encoded(kwargs, message):
with pytest.raises(ValueError, match=message):
encode_rgb(pixels=b"\x00" * 64, **kwargs)
def test_a_short_buffer_is_rejected_rather_than_encoding_garbage():
with pytest.raises(ValueError, match="needs"):
encode_rgb(4, 4, 16, b"\x00" * 63)