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(windows)]
45mod windows;
46#[cfg(all(unix, not(target_os = "macos")))]
47mod x11;
48
49/// Commands the daemon may queue before the backend catches up.
50const COMMAND_CAPACITY: usize = 16;
51
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub enum Command {
54    Edge {
55        display: Bounds,
56        edge: Edge,
57        progress: u16,
58    },
59    Clear,
60    Landing {
61        x: i32,
62        y: i32,
63    },
64    Tick,
65}
66
67/// Handle to a running feedback backend.
68#[derive(Debug, Clone)]
69pub struct Feedback {
70    commands: mpsc::Sender<Command>,
71}
72
73impl Feedback {
74    /// Queues a command. A full or closed queue drops it: the input path must
75    /// never wait for the UI.
76    pub fn send(&self, command: Command) {
77        let _ = self.commands.try_send(command);
78    }
79}
80
81/// A feedback handle and the receiver its backend thread reads.
82#[must_use]
83pub fn channel() -> (Feedback, mpsc::Receiver<Command>) {
84    let (commands, receiver) = mpsc::channel(COMMAND_CAPACITY);
85    (Feedback { commands }, receiver)
86}
87
88/// Whether this session can show feedback: Windows, macOS and X11.
89#[must_use]
90pub fn supported() -> bool {
91    #[cfg(any(windows, target_os = "macos"))]
92    {
93        true
94    }
95    #[cfg(all(unix, not(target_os = "macos")))]
96    {
97        crate::input::detect_backend() == crate::input::Backend::X11
98    }
99    #[cfg(not(any(windows, unix)))]
100    {
101        false
102    }
103}
104
105/// Starts the backend, or returns `None` when this session has none.
106#[must_use]
107pub fn start() -> Option<Feedback> {
108    supported().then(platform_start).flatten()
109}
110
111/// Whether this OS can play haptic ticks.
112#[must_use]
113pub const fn haptics_supported() -> bool {
114    cfg!(target_os = "macos")
115}
116
117#[cfg(target_os = "macos")]
118use macos::start as platform_start;
119#[cfg(windows)]
120use windows::start as platform_start;
121#[cfg(all(unix, not(target_os = "macos")))]
122use x11::start as platform_start;
123#[cfg(not(any(windows, unix)))]
124fn platform_start() -> Option<Feedback> {
125    None
126}
a7n_platform/feedback.rs

a7n_platform/
feedback.rs
