GitCorner

Code

ossartcraftvectorcraft🌐
2bc41aeb8602
//! Pen pressure, tilt and barrel rotation that the host reads from the system itself (#764).
//!
//! winit 0.30 hands a pen's pressure to egui only on Windows, as the force of a touch event; the
//! web build makes the same touch events from the browser's Pointer Events. No platform gets the
//! pen's tilt or rotation through winit. On Linux under X11 (XWayland included), winit reports a
//! pen as a mouse, so the desktop app reads the pressure, tilt and rotation from XInput2 on a
//! connection of its own and writes them into a [`StylusFeed`] ([`crate::Services::stylus`]). On
//! macOS, where winit reports none of them either, the app reads each event's pressure, tilt and
//! rotation from AppKit before the window handles it, and also keeps them for that event's pointer
//! move ([`StylusFeed::set_move`]), so the moves of a fast stroke each get their own. On Windows,
//! where winit drops which end of the pen is down, the app reads the pressure and the end from
//! each pointer message of a pen before winit handles it. The canvas uses the pressure when a
//! frame's events carry no touch force, and the tilt and rotation for each press, drag and release.
//! An airbrush pen's finger wheel comes with the tilt and rotation ([`PenPose::wheel`]) where the
//! host reads it: from XInput2 on X11 and from AppKit on macOS. The app does not read it on
//! Windows, whose pointer messages have no field for it, or in the web build.
//!
//! The feed also says which end of the pen moved. Turning the pen to its eraser end selects the
//! Eraser tool, and turning it back to the tip selects the tool used before
//! ([`sync_eraser_tool`]), as the reference app's help describes under "Erase parts of a path
//! using a stylus pen":
//! <https://helpx.adobe.com/illustrator/desktop/draw-shapes-and-paths/modify-paths/erase-parts-of-a-path.html>
//!
//! The web build writes the pen's end into a feed as well. Pointer Events report the eraser end
//! only as a press of the pen's eraser button (`button` 5), so in a browser the end changes when
//! the pen presses: a press of the eraser end selects the Eraser before that press, and a press of
//! the tip selects the tool used before.

use std::collections::VecDeque;
use std::sync::{Arc, Condvar, Mutex, MutexGuard, OnceLock};
use std::time::Duration;

pub use vectorcraft_tools::PenPose;

use crate::VectorcraftApp;

/// The tool the pen's eraser end selects.
const ERASER: &str = "eraser";

/// How long a press waits for the touch of a pen that hovers ([`StylusFeed::press`]).
const PRESS_WAIT: Duration = Duration::from_millis(5);

/// The pressures of pointer moves kept for the UI ([`StylusFeed::set_move`]); a frame replays 64
/// moves at most.
const MAX_MOVES: usize = 256;

/// What a pen reports as it moves.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct PenSample {
    /// 0..1; 0 while the pen hovers.
    pub pressure: f32,
    /// The pen is turned to its eraser end.
    pub eraser: bool,
    /// The tilt, rotation and finger wheel the pen read, if any.
    pub pose: PenPose,
}

/// What the feed holds.
#[derive(Clone, Debug, Default)]
struct Pen {
    /// The pressure of the pen when a pen was the last pointer to move.
    latest: Option<f32>,
    /// The pen that moved last is turned to its eraser end.
    eraser: bool,
    /// The highest pressure set since the UI last read the feed, counted from the latest sample
    /// whose pressure rose above 0.
    peak: Option<f32>,
    /// The last pressure above 0 set since a pen was the last pointer to move, with the same end
    /// (0 when that end has not touched).
    touched: f32,
    /// The pressure, tilt and rotation of each pointer move set since the UI last took them,
    /// oldest first.
    moves: VecDeque<(f32, PenPose)>,
    /// The pen's latest tilt and rotation (none when a mouse moved last).
    pose: PenPose,
}

impl Pen {
    /// A pen hovers, and no touch has been set since the UI last read the feed.
    fn hovering(&self) -> bool {
        self.latest == Some(0.0) && self.peak.is_none()
    }
}

#[derive(Default)]
struct Shared {
    pen: Mutex<Pen>,
    /// Wake the canvas for a pen that turns without a new window pointer event.
    repaint: OnceLock<egui::Context>,
    /// Signaled on every [`StylusFeed::set_sample`] ([`StylusFeed::set`] included).
    set: Condvar,
    /// Written on the UI thread itself ([`StylusFeed::on_ui_thread`]): a press never waits.
    ui_thread: bool,
}

/// The pen pressure, pen end, tilt and rotation the host last read, written from any thread and
/// read on the UI thread. Cheap to clone; the clones share the value.
#[derive(Clone, Default)]
pub struct StylusFeed(Arc<Shared>);

impl StylusFeed {
    /// A feed the host writes on the UI thread, before the UI handles the event it read (macOS):
    /// a press has its touch already, and waiting for one would only stall the thread.
    pub fn on_ui_thread() -> Self {
        Self(Arc::new(Shared { ui_thread: true, ..Shared::default() }))
    }

    fn lock(&self) -> MutexGuard<'_, Pen> {
        self.0.pen.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
    }

    pub(crate) fn bind_repaint(&self, ctx: &egui::Context) {
        self.0.repaint.get_or_init(|| ctx.clone());
    }

    /// A pen turned to its tip moved with `pressure`, or `None`: another pointer moved
    /// ([`Self::set_sample`]).
    pub fn set(&self, pressure: Option<f32>) {
        self.set_sample(pressure.map(|pressure| PenSample { pressure, ..PenSample::default() }));
    }

    /// A pen moved with `sample`'s pressure (0..1; 0 while it hovers), end, tilt and rotation, or
    /// `None`: another pointer, such as a mouse, moved. A pressure outside 0..1 is clamped, and one
    /// that is not a number is a mouse's, 1. The tilt and rotation are kept within their ranges by
    /// [`PenPose::sanitized`]. A sample of the other end starts afresh: the touches of the end
    /// before it don't count for its presses.
    pub fn set_sample(&self, sample: Option<PenSample>) {
        let pressure = sample.map(|s| if s.pressure.is_finite() { s.pressure.clamp(0.0, 1.0) } else { 1.0 });
        let eraser = sample.is_some_and(|s| s.eraser);
        let mut pen = self.lock();
        let before_pose = pen.pose;
        if eraser != pen.eraser {
            *pen = Pen::default();
        }
        pen.eraser = eraser;
        pen.pose = sample.map_or(PenPose::default(), |s| s.pose.sanitized());
        match pressure {
            Some(p) if p > 0.0 => {
                let touching = pen.latest.is_some_and(|l| l > 0.0);
                pen.peak = Some(if touching { pen.peak.map_or(p, |q| q.max(p)) } else { p });
                pen.touched = p;
            }
            Some(_) => {}
            None => {
                pen.peak = None;
                pen.touched = 0.0;
                pen.moves.clear();
            }
        }
        pen.latest = pressure;
        let pose_changed = pen.pose != before_pose;
        drop(pen);
        self.0.set.notify_all();
        if pose_changed && let Some(ctx) = self.0.repaint.get() {
            ctx.request_repaint();
        }
    }

    /// Like [`Self::set_sample`], for a pen sample that comes with one pointer move of the window,
    /// read before the window handles the move (macOS): its pressure, tilt and rotation are also
    /// kept for that move ([`Self::take_moves`]).
    pub fn set_move(&self, sample: PenSample) {
        self.set_sample(Some(sample));
        let mut pen = self.lock();
        if pen.moves.len() >= MAX_MOVES {
            pen.moves.pop_front();
        }
        let pressure = pen.latest.unwrap_or(1.0);
        let pose = pen.pose;
        pen.moves.push_back((pressure, pose));
    }

    /// The pressures, tilts and rotations of the pointer moves set with [`Self::set_move`] since
    /// the last call, oldest first (256 at most): the last one is the latest move's.
    pub fn take_moves(&self) -> Vec<(f32, PenPose)> {
        self.lock().moves.drain(..).collect()
    }

    /// The pressure of a press the UI holds (a drag and its release) when a pen was the last
    /// pointer to move, otherwise `None`: the latest pressure, or, when the pen has lifted (0), the
    /// last pressure it touched with. The lift can reach the feed before the UI handles the last
    /// moves and the release of the press, which then keep the pen's pressure, not the lift's 0.
    /// The pressures set so far count as read for [`Self::press`].
    pub fn held(&self) -> Option<f32> {
        let mut pen = self.lock();
        pen.peak = None;
        let touched = pen.touched;
        pen.latest.map(|l| if l > 0.0 { l } else { touched })
    }

    /// The pressure of a press when a pen was the last pointer to move, otherwise `None`: the
    /// highest pressure set since the last read, counted from the latest touch, or else the latest
    /// pressure. A quick tap can touch and lift before the frame that handles its press, which
    /// then gets the tap's pressure, not the lift's 0. The host's reader can also set the touch
    /// just after the UI handles the press: when the pen still hovers, the press waits up to 5 ms
    /// for it, and gets 0 if none comes.
    pub fn press(&self) -> Option<f32> {
        self.press_within(PRESS_WAIT)
    }

    /// The tilt (in screen axes) and rotation of the pen when a pen was the last pointer to move
    /// and it read either, otherwise `None`.
    pub fn pose(&self) -> Option<PenPose> {
        let pen = self.lock();
        pen.latest.map(|_| pen.pose).filter(|q| *q != PenPose::default())
    }

    fn press_within(&self, wait: Duration) -> Option<f32> {
        let mut pen = self.lock();
        if pen.hovering() && !self.0.ui_thread {
            pen = self.wait_for_touch(pen, wait);
        }
        let peak = pen.peak.take();
        pen.latest.map(|l| peak.unwrap_or(l))
    }

    /// Whether the pen is turned to its eraser end when a pen was the last pointer to move,
    /// otherwise `None`.
    pub fn eraser(&self) -> Option<bool> {
        let pen = self.lock();
        pen.latest.map(|_| pen.eraser)
    }

    #[cfg(not(target_arch = "wasm32"))]
    fn wait_for_touch<'a>(&'a self, pen: MutexGuard<'a, Pen>, wait: Duration) -> MutexGuard<'a, Pen> {
        match self.0.set.wait_timeout_while(pen, wait, |p| p.hovering()) {
            Ok((pen, _)) => pen,
            Err(e) => e.into_inner().0,
        }
    }

    /// The browser's main thread can't wait, and the web build writes its feed on that thread.
    #[cfg(target_arch = "wasm32")]
    fn wait_for_touch<'a>(&'a self, pen: MutexGuard<'a, Pen>, _wait: Duration) -> MutexGuard<'a, Pen> {
        pen
    }
}

/// The end of the pen the canvas saw last, and the tool the eraser end stands in for
/// ([`sync_eraser_tool`]).
#[derive(Clone, Debug, Default)]
pub(crate) struct PenEnd {
    /// `Some(true)`: the eraser end; `Some(false)`: the tip; `None`: no pen seen yet.
    end: Option<bool>,
    /// The tool that was active when the eraser end selected the Eraser.
    before: Option<&'static str>,
}

impl PenEnd {
    /// A tool was chosen (the toolbar, a shortcut, a menu, `tool.select`): the tip no longer
    /// brings back the tool from before the eraser end.
    pub(crate) fn forget_tool(&mut self) {
        self.before = None;
    }

    /// The end the pen turned to since the last call (`Some(true)`: the eraser end), or `None`
    /// when it has not turned, or when another pointer moved last. Each turn is reported once.
    fn take_flip(&mut self, feed: Option<&StylusFeed>) -> Option<bool> {
        let eraser = feed?.eraser()?;
        let flipped = self.end.map_or(eraser, |e| e != eraser);
        self.end = Some(eraser);
        flipped.then_some(eraser)
    }
}

/// Select the Eraser tool when the pen turns to its eraser end, and select the tool active before
/// it when the pen turns back to its tip while the Eraser is still active. The Eraser chosen
/// before the eraser end came in stays when the tip comes back. Returns whether the tool changed.
///
/// The canvas calls this once a frame while no press is held and the pointer is in the window, so
/// a turn during a press takes effect after the release, and a turn over another window takes
/// effect when the pointer comes in.
pub(crate) fn sync_eraser_tool(app: &mut VectorcraftApp) -> bool {
    let Some(eraser) = app.pen_end.take_flip(app.services.stylus.as_ref()) else { return false };
    let tool = app.session.tool_id();
    if eraser {
        if tool == ERASER {
            return false;
        }
        app.select_tool(ERASER);
        // After `select_tool`, which forgets the tool before.
        let selected = app.session.tool_id() == ERASER;
        app.pen_end.before = selected.then_some(tool);
        selected
    } else {
        match app.pen_end.before.take() {
            Some(before) if tool == ERASER => {
                app.return_to_tool(before);
                app.session.tool_id() == before
            }
            _ => false,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};

    #[test]
    fn changing_a_still_pens_pose_wakes_the_canvas() {
        let feed = StylusFeed::default();
        let ctx = egui::Context::default();
        let repaints = Arc::new(AtomicUsize::new(0));
        let count = repaints.clone();
        ctx.set_repaint_observer(move |_| {
            count.fetch_add(1, Ordering::Relaxed);
        });
        feed.bind_repaint(&ctx);
        let pose = PenPose { rotation: Some(0.0), ..Default::default() };
        let sample = PenSample { pressure: 0.0, pose, ..Default::default() };
        let writer = feed.clone();
        std::thread::spawn(move || writer.set_sample(Some(sample))).join().unwrap();
        assert_eq!(repaints.load(Ordering::Relaxed), 1);
        feed.set_sample(Some(sample));
        assert_eq!(repaints.load(Ordering::Relaxed), 1, "an unchanged pose needs no new frame");
        feed.set_sample(Some(PenSample { pose: PenPose { rotation: Some(90.0), ..pose }, ..sample }));
        assert_eq!(repaints.load(Ordering::Relaxed), 2);
        feed.set_sample(None);
        assert_eq!(repaints.load(Ordering::Relaxed), 3, "mouse input clears the tip");
    }

    #[test]
    fn the_feed_keeps_the_last_pressure_within_0_to_1() {
        let feed = StylusFeed::default();
        assert_eq!(feed.held(), None, "no pen until one moves");
        let shared = feed.clone();
        shared.set(Some(0.25));
        assert_eq!(feed.held(), Some(0.25), "the clones share the value");
        feed.set(Some(1.5));
        assert_eq!(feed.held(), Some(1.0));
        feed.set(Some(f32::NAN));
        assert_eq!(feed.held(), Some(1.0), "a pressure that is not a number is a mouse's");
        feed.set(None);
        feed.set(Some(-0.5));
        assert_eq!(feed.press_within(Duration::ZERO), Some(0.0));
        feed.set(None);
        assert_eq!((feed.held(), feed.press()), (None, None), "a mouse moved");
    }

    /// The tilt and rotation a pen read, kept within their ranges, until a mouse moves.
    #[test]
    fn the_feed_keeps_the_pens_tilt_and_rotation_within_their_ranges() {
        let feed = StylusFeed::default();
        assert_eq!(feed.pose(), None);
        let pen = |pose| Some(PenSample { pressure: 0.4, pose, ..PenSample::default() });
        let leaning = PenPose { tilt: Some([-120.0, 30.0]), rotation: Some(-90.0), wheel: None };
        feed.set_sample(pen(leaning));
        assert_eq!(feed.pose(), Some(PenPose { tilt: Some([-90.0, 30.0]), rotation: Some(270.0), wheel: None }));
        assert_eq!(feed.held(), Some(0.4), "the pressure as before");
        // Not a number: left out. A tiny negative rotation is 0, not 360.
        feed.set_sample(pen(PenPose { tilt: Some([f32::NAN, 0.0]), rotation: Some(-1e-9), wheel: None }));
        assert_eq!(feed.pose(), Some(PenPose { rotation: Some(0.0), ..PenPose::default() }));
        feed.set_sample(pen(PenPose { rotation: Some(f32::INFINITY), wheel: Some(f32::NAN), ..PenPose::default() }));
        assert_eq!(feed.pose(), None, "a pen that reads none of them");
        assert!(PenPose { rotation: Some(725.0), ..Default::default() }.sanitized().rotation == Some(5.0));
        // An airbrush pen's finger wheel, clamped to 0..1.
        feed.set_sample(pen(PenPose { wheel: Some(1.25), ..PenPose::default() }));
        assert_eq!(feed.pose(), Some(PenPose { wheel: Some(1.0), ..PenPose::default() }));
        // The eraser end reads them too.
        feed.set_sample(Some(PenSample { pressure: 0.4, eraser: true, pose: leaning }));
        assert_eq!((feed.eraser(), feed.pose()), (Some(true), Some(PenPose { tilt: Some([-90.0, 30.0]), rotation: Some(270.0), wheel: None })));
        // A pen that reads no tilt (`set`), or a mouse: none.
        feed.set_sample(pen(leaning));
        feed.set(Some(0.5));
        assert_eq!(feed.pose(), None);
        feed.set_sample(pen(leaning));
        feed.set_sample(None);
        assert_eq!((feed.pose(), feed.held()), (None, None));
    }

    #[test]
    fn the_feed_keeps_the_eraser_end() {
        let feed = StylusFeed::default();
        assert_eq!(feed.eraser(), None, "no pen until one moves");
        feed.set_sample(Some(PenSample { pressure: 1.5, eraser: true, ..PenSample::default() }));
        assert_eq!((feed.eraser(), feed.held()), (Some(true), Some(1.0)), "clamped, and the eraser end kept");
        feed.set_sample(Some(PenSample { pressure: f32::NAN, eraser: true, ..PenSample::default() }));
        assert_eq!((feed.eraser(), feed.held()), (Some(true), Some(1.0)));
        feed.set(Some(0.25));
        assert_eq!((feed.eraser(), feed.held()), (Some(false), Some(0.25)), "the tip");
        feed.set_sample(Some(PenSample { pressure: 0.0, eraser: true, ..PenSample::default() }));
        assert_eq!(feed.eraser(), Some(true), "the eraser end hovering");
        feed.set_sample(None);
        assert_eq!(feed.eraser(), None, "a mouse moved");
    }

    #[test]
    fn the_feed_keeps_the_pressure_of_each_move() {
        let feed = StylusFeed::default();
        let leaning = PenPose { tilt: Some([20.0, -10.0]), rotation: Some(400.0), wheel: Some(0.75) };
        for (p, pose) in [(0.2, PenPose::default()), (1.5, leaning), (0.4, PenPose::default())] {
            feed.set_move(PenSample { pressure: p, pose, ..PenSample::default() });
        }
        feed.set(Some(0.9));
        let turned = PenPose { rotation: Some(40.0), ..leaning };
        let unread = PenPose::default();
        assert_eq!(
            feed.take_moves(),
            [(0.2, unread), (1.0, turned), (0.4, unread)],
            "clamped, each move with its own pose; a sample without a move keeps none"
        );
        assert_eq!((feed.take_moves(), feed.held()), (vec![], Some(0.9)), "taken once");
        for _ in 0..MAX_MOVES + 10 {
            feed.set_move(PenSample { pressure: 0.5, ..PenSample::default() });
        }
        assert_eq!(feed.take_moves().len(), MAX_MOVES, "bounded");
        feed.set_move(PenSample { pressure: 0.5, ..PenSample::default() });
        feed.set(None);
        assert!(feed.take_moves().is_empty(), "a mouse moved");
    }

    #[test]
    fn a_held_press_keeps_the_last_touch_when_the_lift_comes_first() {
        let feed = StylusFeed::default();
        feed.set(Some(0.0));
        assert_eq!(feed.held(), Some(0.0), "a pen that has not touched");
        // The pen moves and lifts before the UI handles the last move and the release.
        for p in [0.5, 0.6, 0.0] {
            feed.set(Some(p));
        }
        assert_eq!(feed.held(), Some(0.6));
        feed.set(Some(0.3));
        assert_eq!(feed.held(), Some(0.3), "a touch again: its own pressure");
        feed.set(None);
        assert_eq!(feed.held(), None, "a mouse moved");
        feed.set(Some(0.0));
        assert_eq!(feed.held(), Some(0.0), "the pen's touch before the mouse doesn't count");
    }

    #[test]
    fn a_turned_pen_presses_without_the_touches_of_the_other_end() {
        let feed = StylusFeed::default();
        // The tip touches and lifts where the UI holds no press, so the UI does not read the feed.
        for p in [0.0, 0.8, 0.0] {
            feed.set(Some(p));
        }
        feed.set_sample(Some(PenSample { pressure: 0.0, eraser: true, ..PenSample::default() }));
        assert_eq!(feed.held(), Some(0.0), "the eraser end has not touched");
        assert_eq!(feed.press_within(Duration::ZERO), Some(0.0), "nor pressed");
        feed.set_sample(Some(PenSample { pressure: 0.4, eraser: true, ..PenSample::default() }));
        feed.set_sample(Some(PenSample { pressure: 0.0, eraser: true, ..PenSample::default() }));
        feed.set(Some(0.0));
        assert_eq!((feed.held(), feed.press_within(Duration::ZERO)), (Some(0.0), Some(0.0)), "back to the tip");
    }

    #[test]
    fn a_press_takes_the_highest_pressure_since_the_last_read() {
        let feed = StylusFeed::default();
        feed.set(Some(0.0));
        assert_eq!(feed.press(), Some(0.0), "a hovering pen");
        // A tap: it touches, presses harder, and lifts before the frame that handles the press.
        for p in [0.4, 0.7, 0.3, 0.0] {
            feed.set(Some(p));
        }
        assert_eq!(feed.press(), Some(0.7));
        assert_eq!(feed.press(), Some(0.0), "the press read the tap: the latest pressure");
        // A new touch counts from its own pressure, not the touch before it.
        for p in [0.9, 0.0, 0.2, 0.5, 0.3] {
            feed.set(Some(p));
        }
        assert_eq!(feed.press(), Some(0.5));
        // Pressures the UI has read do not count for the next press.
        feed.set(Some(0.8));
        assert_eq!(feed.held(), Some(0.8));
        feed.set(Some(0.4));
        assert_eq!(feed.press(), Some(0.4));
        feed.set(None);
        assert_eq!(feed.press(), None, "a mouse presses with no pen pressure");
    }

    #[test]
    fn a_press_waits_for_the_touch_of_a_hovering_pen() {
        let feed = StylusFeed::default();
        feed.set(Some(0.0));
        let reader = feed.clone();
        let late = std::thread::spawn(move || {
            std::thread::sleep(Duration::from_millis(20));
            reader.set(Some(0.6));
        });
        assert_eq!(feed.press_within(Duration::from_secs(10)), Some(0.6), "the touch set while the press waited");
        late.join().unwrap();
        // No touch comes: the hover's 0 once the wait ends.
        feed.set(Some(0.0));
        let start = std::time::Instant::now();
        assert_eq!(feed.press_within(Duration::from_millis(30)), Some(0.0));
        assert!(start.elapsed() >= Duration::from_millis(30));
        // A pen that touched, or a mouse, does not wait.
        feed.set(Some(0.3));
        let start = std::time::Instant::now();
        assert_eq!(feed.press_within(Duration::from_secs(10)), Some(0.3));
        feed.set(None);
        assert_eq!(feed.press_within(Duration::from_secs(10)), None);
        assert!(start.elapsed() < Duration::from_secs(5));
    }

    /// A feed written on the UI thread (macOS) has nothing to wait for: a hovering pen's press
    /// gets its 0 at once rather than stalling the thread.
    #[test]
    fn a_feed_written_on_the_ui_thread_never_waits() {
        let feed = StylusFeed::on_ui_thread();
        feed.set(Some(0.0));
        let start = std::time::Instant::now();
        assert_eq!(feed.press_within(Duration::from_secs(10)), Some(0.0));
        assert!(start.elapsed() < Duration::from_secs(5));
    }
}