From 306489d8add21729d743f18749c6788d616e10cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=BF=A2=E8=BE=B0?= Date: Thu, 15 Oct 2026 14:44:04 +0800 Subject: [PATCH] fix(capture): choose a cursor mode the portal advertises (#25) * fix(capture): choose a cursor mode the portal advertises `uur run` on a Wayland session aborted during capture negotiation: Error: Portal request didn't succeed: Other Error: ZBus Error: org.freedesktop.portal.Error.InvalidArgument: Unavailable cursor mode 2 `negotiate` hardcoded `CursorMode::Embedded` (2). The portal frontend validates that against the backend's `AvailableCursorModes` and rejects anything outside it, so any backend that does not offer Embedded could never start a session. A frontend whose backend property cache is empty reports `AvailableCursorModes = 0` and then rejects every mode, which is what made this fail even on backends that do support Embedded: restarting `xdg-desktop-portal` restored the flags from 0 to 7 and mode 2 was accepted again. `preferred_cursor_mode` now reads the advertised flags and picks Embedded, then Hidden, then Metadata. If none are advertised it fails with an actionable message naming the portal restart, instead of surfacing a raw D-Bus error. Older portals that do not implement the v2 property keep the previous behaviour. The same hardcoded mode in the RemoteDesktop input path is routed through the shared helper. Adds four tests: preference order, subset fallback, the empty-advertisement regression, and source-type mapping. * fix(capture): preserve portal errors and report cursor fallback --------- Co-authored-by: Xuc Pan --- locales/en.yml | 2 + locales/zh-CN.yml | 2 + src/capture.rs | 89 +++++++++++++++++++++++++++++++++++++++++++-- src/input/portal.rs | 4 +- 4 files changed, 92 insertions(+), 5 deletions(-) diff --git a/locales/en.yml b/locales/en.yml index e55c265..41c541e 100644 --- a/locales/en.yml +++ b/locales/en.yml @@ -56,6 +56,8 @@ capture: direct_started: "direct Wayland monitor capture started" session_ready: "portal session ready (video node %{node}); streaming to the private runtime transport" helper_failed: "the capture helper exited with an error" + cursor_unsupported: "the desktop portal advertises no usable cursor mode, so screen capture cannot start. Restart the portal (systemctl --user restart xdg-desktop-portal) and retry; if it persists, check that a ScreenCast backend matching your session is installed." + cursor_not_embedded: "the portal cannot embed the cursor; capture will continue without a cursor in the video frames" session: already_running: "a session is already running - use it, or run `uur stop` first" diff --git a/locales/zh-CN.yml b/locales/zh-CN.yml index a60294c..eaf06b2 100644 --- a/locales/zh-CN.yml +++ b/locales/zh-CN.yml @@ -72,6 +72,8 @@ capture: direct_started: "已启动原生 Wayland 显示器采集" session_ready: "Portal 会话已建立(视频节点 %{node});正在写入私有运行时传输" helper_failed: "捕获助手异常退出" + cursor_unsupported: "桌面 Portal 未声明任何可用的光标模式,无法开始屏幕采集。请重启 Portal(systemctl --user restart xdg-desktop-portal)后重试;若仍失败,请确认已安装与当前会话匹配的 ScreenCast 后端。" + cursor_not_embedded: "Portal 无法将光标嵌入画面;采集将继续,但视频帧中不会包含光标" setup: eula_prompt: "官方 UU 远程客户端将从网易官方渠道下载,并受其最终用户协议约束:%{url}\n使用 --accept-eula 重新运行以继续。" diff --git a/src/capture.rs b/src/capture.rs index 3819592..42f0489 100644 --- a/src/capture.rs +++ b/src/capture.rs @@ -206,6 +206,54 @@ async fn portal_session(config: &mut Config) -> Result<(OwnedFd, u32)> { Err(last_error.unwrap_or_else(|| anyhow!("portal session failed"))) } +/// Choose a cursor mode from the flags the portal advertises. +/// +/// `Embedded` is what the capture path wants (the hook composites the cursor +/// itself on X11, and an embedded cursor is the closest match elsewhere), then +/// `Hidden`, then `Metadata`. `None` means the portal advertised no usable +/// mode at all. +fn choose_cursor_mode( + available: ashpd::enumflags2::BitFlags, +) -> Option { + use ashpd::desktop::screencast::CursorMode; + [ + CursorMode::Embedded, + CursorMode::Hidden, + CursorMode::Metadata, + ] + .into_iter() + .find(|mode| available.contains(*mode)) +} + +/// Pick a cursor mode the portal actually advertises. +/// +/// `SelectSources` rejects a mode outside the portal's `AvailableCursorModes` +/// with `InvalidArgument: Unavailable cursor mode N`. A portal frontend whose +/// backend property cache is empty reports a zeroed set and rejects every +/// mode, so choosing from the advertised flags keeps capture working on +/// backends that offer only a subset and turns the unusable case into an +/// actionable message instead of a raw D-Bus error. +pub(crate) async fn preferred_cursor_mode( + screencast: &ashpd::desktop::screencast::Screencast<'_>, +) -> Result { + use ashpd::desktop::screencast::CursorMode; + + let available = match screencast.available_cursor_modes().await { + Ok(modes) => modes, + // ScreenCast v2 introduced the property; older portals have no + // advertisement to consult, so keep the historical request. + Err(ashpd::Error::RequiresVersion(2, 0..=1)) => return Ok(CursorMode::Embedded), + Err(error) => return Err(error).context("reading ScreenCast cursor modes"), + }; + let mode = choose_cursor_mode(available) + .ok_or_else(|| anyhow!("{}", t!("capture.cursor_unsupported")))?; + if mode != CursorMode::Embedded { + // The helper publishes pixels, not PipeWire cursor metadata. + eprintln!("{}", t!("capture.cursor_not_embedded")); + } + Ok(mode) +} + /// One full portal handshake. Returns the PipeWire fd, the video node id /// and the restore token the portal issued for this selection. async fn negotiate( @@ -213,15 +261,15 @@ async fn negotiate( source: ashpd::desktop::screencast::SourceType, restore_token: Option<&str>, ) -> Result<(OwnedFd, u32, Option)> { - use ashpd::desktop::screencast::CursorMode; use ashpd::desktop::PersistMode; let session = screencast.create_session().await?; + let cursor_mode = preferred_cursor_mode(screencast).await?; screencast .select_sources( &session, - CursorMode::Embedded, + cursor_mode, source.into(), false, restore_token, @@ -288,8 +336,10 @@ fn find_helper(name: &str) -> Result { #[cfg(test)] mod tests { + use super::choose_cursor_mode; use super::source_type; - use ashpd::desktop::screencast::SourceType; + use ashpd::desktop::screencast::{CursorMode, SourceType}; + use ashpd::enumflags2::BitFlags; #[test] fn configured_portal_source_is_mapped() { @@ -297,4 +347,37 @@ mod tests { assert_eq!(source_type("window"), SourceType::Window); assert_eq!(source_type("virtual"), SourceType::Virtual); } + + #[test] + fn embedded_cursor_is_preferred_when_the_portal_offers_it() { + // gnome advertises 7 = Hidden | Embedded | Metadata. + let available = CursorMode::Hidden | CursorMode::Embedded | CursorMode::Metadata; + assert_eq!(choose_cursor_mode(available), Some(CursorMode::Embedded)); + } + + #[test] + fn a_backend_without_embedded_cursor_falls_back_instead_of_failing() { + // wlr advertises 3 = Hidden | Embedded; a metadata-only backend must + // still capture rather than requesting a mode the portal rejects. + assert_eq!( + choose_cursor_mode(CursorMode::Metadata.into()), + Some(CursorMode::Metadata) + ); + assert_eq!( + choose_cursor_mode(CursorMode::Hidden.into()), + Some(CursorMode::Hidden) + ); + assert_eq!( + choose_cursor_mode(CursorMode::Hidden | CursorMode::Metadata), + Some(CursorMode::Hidden) + ); + } + + #[test] + fn an_empty_advertisement_selects_no_mode() { + // Regression: a portal frontend with a zeroed backend property cache + // reported AvailableCursorModes = 0 and rejected every request with + // "InvalidArgument: Unavailable cursor mode 2". + assert_eq!(choose_cursor_mode(BitFlags::empty()), None); + } } diff --git a/src/input/portal.rs b/src/input/portal.rs index 8f3d003..a704e5c 100644 --- a/src/input/portal.rs +++ b/src/input/portal.rs @@ -1,6 +1,6 @@ use anyhow::{anyhow, Context, Result}; use ashpd::desktop::remote_desktop::{Axis, DeviceType, KeyState, RemoteDesktop}; -use ashpd::desktop::screencast::{CursorMode, Screencast}; +use ashpd::desktop::screencast::Screencast; use ashpd::desktop::PersistMode; use std::collections::HashSet; use std::sync::atomic::{AtomicBool, Ordering}; @@ -140,7 +140,7 @@ async fn portal_worker( screencast .select_sources( &session, - CursorMode::Embedded, + crate::capture::preferred_cursor_mode(&screencast).await?, source.into(), false, None,