a7n_platform/
feedback.rs

1// SPDX-License-Identifier: GPL-3.0-or-later
2
3//! Visual and haptic feedback while the pointer pushes against a screen edge
4//! and after it lands on this machine.
5//!
6//! # Backend contract
7//!
8//! - [`start`] runs once at daemon startup on a tokio thread. A backend creates
9//!   its channel with [`channel`], moves the receiver to its own OS UI thread
10//!   and returns the [`Feedback`]. It returns `None` when it cannot start;
11//!   it logs nothing and never panics.
12//! - The UI thread owns every window or OS object. Commands arrive on a
13//!   bounded channel (read it with `blocking_recv`). The sender never blocks
14//!   and drops commands when the thread is behind, so the backend must treat
15//!   every command as absolute state, never as a delta.
16//! - Never steal focus, never take input, and make every window click-through
17//!   and invisible to screen capture where the OS allows it. Nothing may
18//!   appear in the task bar, dock or window switcher.
19//! - Honouring the OS reduce-motion setting is the backend's job: with it on,
20//!   show the same state without animation (for example a static edge strip
21//!   and a landing marker that does not pulse).
22//! - Never log positions or progress.
23//! - Commands:
24//!   - [`Command::Edge`]: draw the push glow along `edge` of the display
25//!     `display` (desktop coordinates; the daemon sends the bounds of the
26//!     whole local desktop it captures or injects in, so a backend that knows
27//!     per-monitor bounds clamps the glow to the monitor containing the
28//!     pointer). `progress` runs 0..=1000 per-mille of the resistance that
29//!     is built up; the glow grows with it. Repeated commands update it.
30//!   - [`Command::Clear`]: remove the glow at once (push ended, crossing,
31//!     pause, focus moved or the setting turned off).
32//!   - [`Command::Landing`]: briefly mark the desktop point `(x, y)` where the
33//!     pointer landed, then fade out on its own.
34//!   - [`Command::Tick`]: one trackpad haptic tick. The daemon only sends it
35//!     when the user enabled haptics; backends without haptics ignore it.
36
37use a7n_proto::v1::Edge;
38use tokio::sync::mpsc;
39
40use crate::input::Bounds;
41
42#[cfg(target_os = "macos")]
43mod macos;
44#[cfg(any(target_os = "macos", test))]
45mod macos_geometry;
46#[cfg(windows)]
47mod windows;
48#[cfg(all(test, not(windows)))]
49#[path = "feedback/windows/geometry.rs"]
50mod windows_geometry;
51#[cfg(all(unix, not(target_os = "macos")))]
52mod x11;
53
54/// Commands the daemon may queue before the backend catches up.
55const COMMAND_CAPACITY: usize = 16;
56
57#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub enum Command {
59    Edge {
60        display: Bounds,
61        edge: Edge,
62        progress: u16,
63    },
64    Clear,
65    Landing {
66        x: i32,
67        y: i32,
68    },
69    Tick,
70}
71
72/// Handle to a running feedback backend.
73#[derive(Debug, Clone)]
74pub struct Feedback {
75    commands: mpsc::Sender<Command>,
76}
77
78impl Feedback {
79    /// Queues a command. A full or closed queue drops it: the input path must
80    /// never wait for the UI.
81    pub fn send(&self, command: Command) {
82        let _ = self.commands.try_send(command);
83    }
84}
85
86/// A feedback handle and the receiver its backend thread reads.
87#[must_use]
88pub fn channel() -> (Feedback, mpsc::Receiver<Command>) {
89    let (commands, receiver) = mpsc::channel(COMMAND_CAPACITY);
90    (Feedback { commands }, receiver)
91}
92
93/// Whether this session can show feedback: Windows, macOS and X11.
94#[must_use]
95pub fn supported() -> bool {
96    #[cfg(any(windows, target_os = "macos"))]
97    {
98        true
99    }
100    #[cfg(all(unix, not(target_os = "macos")))]
101    {
102        crate::input::detect_backend() == crate::input::Backend::X11
103    }
104    #[cfg(not(any(windows, unix)))]
105    {
106        false
107    }
108}
109
110/// Starts the backend, or returns `None` when this session has none.
111#[must_use]
112pub fn start() -> Option<Feedback> {
113    supported().then(platform_start).flatten()
114}
115
116/// Whether this OS can play haptic ticks.
117#[must_use]
118pub const fn haptics_supported() -> bool {
119    cfg!(target_os = "macos")
120}
121
122#[cfg(target_os = "macos")]
123use macos::start as platform_start;
124#[cfg(windows)]
125use windows::start as platform_start;
126#[cfg(all(unix, not(target_os = "macos")))]
127use x11::start as platform_start;
128#[cfg(not(any(windows, unix)))]
129fn platform_start() -> Option<Feedback> {
130    None
131}
a7n_platform/feedback.rs

a7n_platform/
feedback.rs
