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 <[email protected]>
This commit is contained in:
迢辰andXuc Pan authored and GitHub committed 2026-10-15 14:44:04 +08:00
1 parent bfecaa5c69
commit 306489d8ad
4 files changed
+92 -5

No files matched your search

+2
View File
@@ -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"
+2
View File
@@ -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 重新运行以继续。"
+86 -3
View File
@@ -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<ashpd::desktop::screencast::CursorMode>,
) -> Option<ashpd::desktop::screencast::CursorMode> {
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<ashpd::desktop::screencast::CursorMode> {
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<String>)> {
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<PathBuf> {
#[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);
}
}
+2 -2
View File
@@ -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,