Compare commits

..
Author SHA1 Message Date
Hermenix 15d96e7cda spike: grim-rs capture producer for the frozen harness
Long-lived zwlr-screencopy client (grim-rs 0.2.0, shm only) that prints
the contract JSON. Rust stays in a spike-local shell, not the repo flake.
2026-10-11 14:42:44 +00:00
ari f3ac9ada27 Merge pull request 'Keyboard input for sessions: typing on the compositor's one seat' (#1) from feat/keyboard-input into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/1
2026-10-11 05:10:29 +00:00
6 changed files with 2382 additions and 0 deletions

No files matched your search

@@ -0,0 +1 @@
/target
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,16 @@
[package]
name = "grimrs-capture"
version = "0.1.0"
edition = "2021"
publish = false
description = "Long-lived grim-rs capture producer for the frozen HARNESS.md contract"
[[bin]]
name = "grimrs-capture"
path = "src/main.rs"
[dependencies]
# Exact: the raw-mode stop point depends on what 0.2.0 does inside capture_*.
grim-rs = "=0.2.0"
libc = "0.2"
serde_json = { version = "1", features = ["preserve_order"] }
+53
View File
@@ -0,0 +1,53 @@
#!/bin/sh
# Eight measured cells, still screen, two runs each.
# Stdout of each cell is one JSON line. Progress goes to runs/progress.log.
# Does not set XDG_RUNTIME_DIR. The caller must export WAYLAND_DISPLAY to the
# absolute socket path.
set -u
cd "$(dirname "$0")"
if [ "${WAYLAND_DISPLAY:-}" != "/run/hypr-stream/wayland-1" ]; then
echo "WAYLAND_DISPLAY must be /run/hypr-stream/wayland-1" >&2
exit 2
fi
if [ "${XDG_RUNTIME_DIR:-}" = "/run/hypr-stream" ]; then
echo "refusing XDG_RUNTIME_DIR=/run/hypr-stream" >&2
exit 2
fi
OUTPUT=${1:?usage: run-cells.sh OUTPUT_NAME}
BIN=./target/release/grimrs-capture
if [ ! -x "$BIN" ]; then
echo "missing $BIN; build with nix-shell --run 'cargo build --release'" >&2
exit 2
fi
mkdir -p runs
LOG=runs/progress.log
: > "$LOG"
# The frame server is a system unit. Do not stop it. Record that it was
# capturing during the run so the numbers are not read as an idle compositor.
ps -eo pid,user,cmd > runs/ps-at-start.txt
echo "BEGIN runner $(date -Is) WAYLAND_DISPLAY=$WAYLAND_DISPLAY XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR-}" >> "$LOG"
fail=0
run() {
name=$1
shift
echo "BEGIN $name $(date -Is)" >> "$LOG"
start=$(date +%s)
"$BIN" "$@" > "runs/$name.stdout" 2> "runs/$name.stderr"
rc=$?
end=$(date +%s)
echo "END $name rc=$rc elapsed=$((end - start)) $(date -Is)" >> "$LOG"
if [ "$rc" -ne 0 ]; then
echo "CELL_FAIL $name rc=$rc" >> "$LOG"
fail=1
fi
}
run output-raw-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-raw-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-jpeg-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run output-jpeg-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run all-raw-1 --all --frames 300 --warmup 10 --mode raw --json
run all-raw-2 --all --frames 300 --warmup 10 --mode raw --json
run all-jpeg-1 --all --frames 300 --warmup 10 --mode jpeg --json
run all-jpeg-2 --all --frames 300 --warmup 10 --mode jpeg --json
echo "ALL_DONE fail=$fail $(date -Is)" >> "$LOG"
exit "$fail"
@@ -0,0 +1,13 @@
# Spike-local toolchain for route 001a. Rust stays out of the repository flake
# on purpose: this shell is the only place this spike gets rustc and cargo.
#
# Do not set WAYLAND_DISPLAY or XDG_RUNTIME_DIR here. The run commands in
# README.md set WAYLAND_DISPLAY to the absolute socket path. Pointing
# XDG_RUNTIME_DIR at /run/hypr-stream makes libwayland reject the runtime dir.
{ pkgs ? import <nixpkgs> { } }:
pkgs.mkShell {
packages = with pkgs; [
rustc # 1.98 from the machine's nixpkgs
cargo
];
}
@@ -0,0 +1,641 @@
//! Long-lived capture producer for the frozen measurement contract.
//!
//! One Wayland connection (`Grim::new_wlr`, so the crate cannot pick
//! `ext-image-copy-capture-v1`), then warmup frames, then N measured frames.
//! Stdout is exactly one JSON object, on the last line. Everything else goes
//! to stderr.
use std::env;
use std::io::{self, Write};
use std::process::ExitCode;
use std::time::Instant;
use grim_rs::Grim;
const ROUTE: &str = "grim-rs";
const JPEG_QUALITY: u8 = 80;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Mode {
Raw,
Jpeg,
}
impl Mode {
fn as_str(self) -> &'static str {
match self {
Mode::Raw => "raw",
Mode::Jpeg => "jpeg",
}
}
}
#[derive(Clone, Debug)]
enum Target {
Output(String),
All,
}
impl Target {
fn label(&self) -> &str {
match self {
Target::Output(name) => name,
Target::All => "all",
}
}
}
struct Args {
target: Target,
frames: u32,
warmup: u32,
mode: Mode,
}
struct Held {
width: u32,
height: u32,
/// JPEG byte length. `None` in raw mode.
jpeg_len: Option<usize>,
/// Pixel or JPEG bytes. Kept alive until the caller drops it, so the
/// frame timer can stop when the bytes are complete and not when they
/// are freed.
bytes: Vec<u8>,
}
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(err) => {
eprintln!("grimrs-capture: {err}");
ExitCode::from(1)
}
}
}
fn run() -> Result<(), String> {
let args = parse_args(env::args().skip(1))?;
// Absolute WAYLAND_DISPLAY is required. Leaving XDG_RUNTIME_DIR alone is
// also required: this process does not own /run/hypr-stream.
match env::var("WAYLAND_DISPLAY") {
Ok(value) if !value.is_empty() => {}
_ => {
return Err(
"WAYLAND_DISPLAY is empty. Set it to the absolute socket \
path /run/hypr-stream/wayland-1 and do not set \
XDG_RUNTIME_DIR=/run/hypr-stream"
.to_string(),
);
}
}
if env::var("XDG_RUNTIME_DIR").ok().as_deref() == Some("/run/hypr-stream") {
return Err(
"XDG_RUNTIME_DIR=/run/hypr-stream is set. Unset it; libwayland \
refuses a runtime dir the caller does not own"
.to_string(),
);
}
// Force zwlr-screencopy. Grim::new() prefers ext-image-copy-capture-v1,
// which is the dma-buf-capable path this machine must not take.
let mut grim = Grim::new_wlr().map_err(|err| {
format!(
"Grim::new_wlr failed ({err}). Refusing to fall back to \
ext-image-copy-capture-v1"
)
})?;
let outputs = grim.get_outputs().map_err(|err| err.to_string())?;
if outputs.is_empty() {
return Err("compositor advertised no outputs".to_string());
}
let layout = describe_outputs(&outputs);
if let Target::Output(name) = &args.target {
if !outputs.iter().any(|output| output.name() == name) {
return Err(format!(
"output {name:?} not found. Outputs: {layout}"
));
}
}
eprintln!(
"grimrs-capture: route {ROUTE} protocol zwlr-screencopy-v1 \
mode {} target {} warmup {} frames {}",
args.mode.as_str(),
args.target.label(),
args.warmup,
args.frames
);
eprintln!("grimrs-capture: outputs {layout}");
let mut last_warmup_nonzero: Option<u64> = None;
let mut last_warmup_jpeg_ok = true;
for i in 0..args.warmup {
let held = grab(&mut grim, &args.target, args.mode)?;
if args.mode == Mode::Jpeg && !held.bytes.starts_with(&[0xFF, 0xD8]) {
last_warmup_jpeg_ok = false;
}
last_warmup_nonzero = Some(count_nonzero(&held.bytes));
eprintln!(
"grimrs-capture: warmup {}/{} {}x{} bytes {} nonzero {}",
i + 1,
args.warmup,
held.width,
held.height,
held.bytes.len(),
last_warmup_nonzero.unwrap_or(0)
);
}
if args.mode == Mode::Jpeg && !last_warmup_jpeg_ok {
return Err(
"warmup JPEG did not start with FF D8; refusing to measure"
.to_string(),
);
}
let cpu_before = process_cpu_ms()?;
let wall_start = Instant::now();
let mut samples_ms: Vec<f64> = Vec::with_capacity(args.frames as usize);
let mut jpeg_sizes: Vec<u64> = Vec::new();
let mut geometry: Option<(u32, u32)> = None;
for _ in 0..args.frames {
let tick = Instant::now();
let held = grab(&mut grim, &args.target, args.mode)?;
// Touch the length so the buffer is complete before the clock stops.
// Do not read pixels: the contract puts stride and checksum outside
// the measurement.
std::hint::black_box(held.bytes.len());
let ms = tick.elapsed().as_secs_f64() * 1000.0;
match geometry {
None => geometry = Some((held.width, held.height)),
Some((w, h)) if w != held.width || h != held.height => {
return Err(format!(
"geometry changed during the run: {w}x{h} then {}x{}",
held.width, held.height
));
}
Some(_) => {}
}
if let Some(len) = held.jpeg_len {
jpeg_sizes.push(len as u64);
}
samples_ms.push(ms);
// Free between frames, outside the frame timer. wall_ms includes it.
drop(held);
}
let wall_ms = wall_start.elapsed().as_secs_f64() * 1000.0;
let cpu_after = process_cpu_ms()?;
let (width, height) = geometry.ok_or("no measured frames")?;
let cpu_ms_per_frame = match (cpu_before, cpu_after) {
(Some(before), Some(after)) if after >= before => {
Some((after - before) / f64::from(args.frames))
}
_ => None,
};
let mut notes = format!(
"grim-rs 0.2.0 via Grim::new_wlr(); copy target is a wl_shm buffer \
created inside each capture_* call, not a dma-buf the producer \
imports. Cursor not overlaid (the frozen argv has no cursor flag; \
hhstream-live's grim command passes -c). JPEG is Grim::to_jpeg, \
quality {JPEG_QUALITY}, the crate default and the live-stream \
setting. Raw timer stops when capture_* returns, which is after \
the crate copies the mapping into a Vec and swizzles XRGB/ARGB to \
RGBA (and applies any output transform or y-invert). The public \
API does not expose the mapped buffer before that, so raw includes \
work the contract says to leave outside the timer. Percentiles are \
linear interpolation on the sorted samples. cpu_ms_per_frame is \
getrusage(RUSAGE_SELF) utime+stime over the measured loop only, \
divided by frames. Frame buffers are freed between frames; that \
free is inside wall_ms and outside frame_ms. Outputs: {layout}. \
No GPU on this machine; dma-buf was not used and is not claimed. \
This process does not move the pointer and does not start or stop \
a session; the pixels are whatever the compositor is already \
showing."
);
if let Some(nonzero) = last_warmup_nonzero {
notes.push_str(&format!(
" Last warmup frame nonzero bytes: {nonzero}."
));
if nonzero == 0 {
notes.push_str(" WARNING: last warmup frame was all zeros.");
}
}
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: args.target.label().to_string(),
geometry: [width, height],
mode: args.mode.as_str(),
warmup: args.warmup,
frames: args.frames,
frame_ms: summarize(&samples_ms),
fps_sustained: sustained_fps(&samples_ms),
wall_ms,
cpu_ms_per_frame,
bytes_p50: if args.mode == Mode::Jpeg {
Some(percentile_u64(&jpeg_sizes, 0.50))
} else {
None
},
persistent: true,
notes,
};
let line = serde_json::to_string(&report.to_json())
.map_err(|err| err.to_string())?;
let mut stdout = io::stdout().lock();
writeln!(stdout, "{line}").map_err(|err| err.to_string())?;
stdout.flush().map_err(|err| err.to_string())?;
Ok(())
}
fn grab(grim: &mut Grim, target: &Target, mode: Mode) -> Result<Held, String> {
let captured = match target {
Target::Output(name) => grim.capture_output(name),
Target::All => grim.capture_all(),
}
.map_err(|err| err.to_string())?;
let width = captured.width();
let height = captured.height();
if width == 0 || height == 0 {
return Err(format!("capture returned {width}x{height}"));
}
match mode {
Mode::Raw => Ok(Held {
width,
height,
jpeg_len: None,
bytes: captured.into_data(),
}),
Mode::Jpeg => {
let jpeg = grim
.to_jpeg_with_quality(captured.data(), width, height, JPEG_QUALITY)
.map_err(|err| err.to_string())?;
let jpeg_len = jpeg.len();
Ok(Held {
width,
height,
jpeg_len: Some(jpeg_len),
bytes: jpeg,
})
}
}
}
fn describe_outputs(outputs: &[grim_rs::Output]) -> String {
let mut ordered: Vec<_> = outputs.iter().collect();
ordered.sort_by(|a, b| {
let ag = a.geometry();
let bg = b.geometry();
ag.x()
.cmp(&bg.x())
.then(ag.y().cmp(&bg.y()))
.then(a.name().cmp(b.name()))
});
ordered
.into_iter()
.map(|output| {
let geometry = output.geometry();
format!(
"{}@{},{} {}x{} scale {}",
output.name(),
geometry.x(),
geometry.y(),
geometry.width(),
geometry.height(),
output.scale()
)
})
.collect::<Vec<_>>()
.join("; ")
}
fn count_nonzero(bytes: &[u8]) -> u64 {
bytes.iter().filter(|byte| **byte != 0).count() as u64
}
fn process_cpu_ms() -> Result<Option<f64>, String> {
let mut usage: libc::rusage = unsafe { std::mem::zeroed() };
let rc = unsafe { libc::getrusage(libc::RUSAGE_SELF, &mut usage) };
if rc != 0 {
return Ok(None);
}
Ok(Some(timeval_ms(usage.ru_utime) + timeval_ms(usage.ru_stime)))
}
fn timeval_ms(value: libc::timeval) -> f64 {
value.tv_sec as f64 * 1000.0 + value.tv_usec as f64 / 1000.0
}
struct Summary {
min: f64,
p50: f64,
mean: f64,
p95: f64,
max: f64,
}
fn summarize(samples: &[f64]) -> Summary {
let mut sorted = samples.to_vec();
sorted.sort_by(|a, b| a.total_cmp(b));
let sum: f64 = sorted.iter().sum();
Summary {
min: sorted[0],
p50: percentile_linear(&sorted, 0.50),
mean: sum / sorted.len() as f64,
p95: percentile_linear(&sorted, 0.95),
max: *sorted.last().expect("at least one sample"),
}
}
fn sustained_fps(samples: &[f64]) -> f64 {
let sum = samples.iter().sum::<f64>();
if sum <= 0.0 {
return 0.0;
}
samples.len() as f64 / (sum / 1000.0)
}
/// Linear interpolation between closest ranks. `samples` must be sorted and
/// non-empty. This is the same definition as numpy's default percentile.
fn percentile_linear(sorted: &[f64], p: f64) -> f64 {
if sorted.len() == 1 {
return sorted[0];
}
let rank = p * (sorted.len() - 1) as f64;
let lo = rank.floor() as usize;
let hi = rank.ceil() as usize;
let frac = rank - lo as f64;
sorted[lo] * (1.0 - frac) + sorted[hi] * frac
}
fn percentile_u64(samples: &[u64], p: f64) -> f64 {
let as_f64: Vec<f64> = samples.iter().map(|value| *value as f64).collect();
let mut sorted = as_f64;
sorted.sort_by(|a, b| a.total_cmp(b));
percentile_linear(&sorted, p)
}
struct Report {
route: &'static str,
language: &'static str,
protocol: &'static str,
output: String,
geometry: [u32; 2],
mode: &'static str,
warmup: u32,
frames: u32,
frame_ms: Summary,
fps_sustained: f64,
wall_ms: f64,
cpu_ms_per_frame: Option<f64>,
bytes_p50: Option<f64>,
persistent: bool,
notes: String,
}
impl Report {
fn to_json(&self) -> serde_json::Value {
serde_json::json!({
"route": self.route,
"language": self.language,
"protocol": self.protocol,
"output": self.output,
"geometry": self.geometry,
"mode": self.mode,
"warmup": self.warmup,
"frames": self.frames,
"frame_ms": {
"min": round3(self.frame_ms.min),
"p50": round3(self.frame_ms.p50),
"mean": round3(self.frame_ms.mean),
"p95": round3(self.frame_ms.p95),
"max": round3(self.frame_ms.max),
},
"fps_sustained": round3(self.fps_sustained),
"wall_ms": round3(self.wall_ms),
"cpu_ms_per_frame": self.cpu_ms_per_frame.map(round3),
"bytes_p50": self.bytes_p50.map(round3),
"persistent": self.persistent,
"notes": self.notes,
})
}
}
fn round3(value: f64) -> f64 {
(value * 1000.0).round() / 1000.0
}
fn parse_args(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
let args: Vec<String> = args.into_iter().collect();
let mut output: Option<String> = None;
let mut all = false;
let mut frames: Option<u32> = None;
let mut warmup: Option<u32> = None;
let mut mode: Option<Mode> = None;
let mut json = false;
let mut index = 0;
while index < args.len() {
let arg = &args[index];
match arg.as_str() {
"--json" => {
if json {
return Err("repeated --json".to_string());
}
json = true;
}
"--all" => {
if all {
return Err("repeated --all".to_string());
}
all = true;
}
"--output" => {
output = Some(need_value(&args, &mut index, "--output")?);
}
"--frames" => {
frames = Some(parse_u32(&need_value(&args, &mut index, "--frames")?, "--frames")?);
}
"--warmup" => {
warmup = Some(parse_u32(&need_value(&args, &mut index, "--warmup")?, "--warmup")?);
}
"--mode" => {
let value = need_value(&args, &mut index, "--mode")?;
mode = Some(match value.as_str() {
"raw" => Mode::Raw,
"jpeg" => Mode::Jpeg,
other => {
return Err(format!(
"--mode must be raw or jpeg, got {other:?}"
))
}
});
}
"--help" | "-h" => {
return Err(usage());
}
other => {
return Err(format!("unknown argument {other}. {}", usage()));
}
}
index += 1;
}
if !json {
return Err(format!("--json is required. {}", usage()));
}
if all && output.is_some() {
return Err("--all and --output are mutually exclusive".to_string());
}
let target = if all {
Target::All
} else if let Some(name) = output {
if name.is_empty() {
return Err("--output name is empty".to_string());
}
Target::Output(name)
} else {
return Err(format!("one of --output or --all is required. {}", usage()));
};
let frames = frames.ok_or_else(|| format!("--frames is required. {}", usage()))?;
if frames == 0 {
return Err("--frames must be at least 1".to_string());
}
let warmup = warmup.ok_or_else(|| format!("--warmup is required. {}", usage()))?;
let mode = mode.ok_or_else(|| format!("--mode is required. {}", usage()))?;
Ok(Args {
target,
frames,
warmup,
mode,
})
}
fn need_value(args: &[String], index: &mut usize, flag: &str) -> Result<String, String> {
let next = index.checked_add(1).and_then(|i| args.get(i));
match next {
Some(value) if !value.starts_with("--") => {
*index += 1;
Ok(value.clone())
}
_ => Err(format!("{flag} needs a value")),
}
}
fn parse_u32(value: &str, flag: &str) -> Result<u32, String> {
value
.parse::<u32>()
.map_err(|_| format!("{flag} must be a non-negative integer, got {value:?}"))
}
fn usage() -> String {
"usage: grimrs-capture (--output NAME | --all) --frames N --warmup W \
--mode raw|jpeg --json"
.to_string()
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(line: &str) -> Result<Args, String> {
parse_args(line.split_whitespace().map(str::to_string))
}
#[test]
fn accepts_the_contract_forms() {
let output = parse(
"--output hh-chromium-yrfadn --frames 300 --warmup 10 --mode raw --json",
)
.unwrap();
assert!(matches!(output.target, Target::Output(name) if name == "hh-chromium-yrfadn"));
assert_eq!(output.frames, 300);
assert_eq!(output.warmup, 10);
assert_eq!(output.mode, Mode::Raw);
let all = parse("--all --frames 300 --warmup 10 --mode jpeg --json").unwrap();
assert!(matches!(all.target, Target::All));
assert_eq!(all.mode, Mode::Jpeg);
}
#[test]
fn rejects_mixed_targets_and_missing_json() {
assert!(parse("--all --output x --frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode raw").is_err());
assert!(parse("--output x --frames 0 --warmup 0 --mode raw --json").is_err());
assert!(parse("--frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode png --json").is_err());
}
#[test]
fn percentile_matches_linear_interpolation() {
let samples = [1.0, 2.0, 3.0, 4.0];
assert_eq!(percentile_linear(&samples, 0.50), 2.5);
assert_eq!(percentile_linear(&samples, 0.0), 1.0);
assert_eq!(percentile_linear(&samples, 1.0), 4.0);
// rank = 0.95 * 3 = 2.85 -> 3.0 * 0.15 + 4.0 * 0.85
let p95 = percentile_linear(&samples, 0.95);
assert!((p95 - 3.85).abs() < 1e-9);
}
#[test]
fn sustained_fps_uses_the_sum_of_frame_times() {
// Two frames of 100 ms -> 2 / 0.2 = 10 fps.
let fps = sustained_fps(&[100.0, 100.0]);
assert!((fps - 10.0).abs() < 1e-9);
}
#[test]
fn json_object_has_the_contract_keys() {
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: "hh-chromium-yrfadn".to_string(),
geometry: [1280, 720],
mode: "jpeg",
warmup: 10,
frames: 300,
frame_ms: Summary {
min: 1.0,
p50: 2.0,
mean: 3.0,
p95: 4.0,
max: 5.0,
},
fps_sustained: 10.0,
wall_ms: 20.0,
cpu_ms_per_frame: None,
bytes_p50: Some(100.5),
persistent: true,
notes: "n".to_string(),
};
let value = report.to_json();
for key in [
"route",
"language",
"protocol",
"output",
"geometry",
"mode",
"warmup",
"frames",
"frame_ms",
"fps_sustained",
"wall_ms",
"cpu_ms_per_frame",
"bytes_p50",
"persistent",
"notes",
] {
assert!(value.get(key).is_some(), "missing {key}");
}
assert!(value["cpu_ms_per_frame"].is_null());
assert_eq!(value["bytes_p50"], 100.5);
assert_eq!(value["persistent"], true);
assert_eq!(value["geometry"][0], 1280);
}
}