Files
photocraft/crates/tablet/src/lib.rs
T
RickiNano 265fedc687 Merge remote-tracking branch 'origin/main' into fix/windows-pen-eraser-end-2285
# Conflicts:
#	apps/photocraft/src/tablet.rs
#	crates/tablet/Cargo.toml
#	crates/tablet/src/lib.rs
#	crates/tablet/src/windows.rs
#	crates/ui-egui/src/lib.rs
#	crates/ui-egui/src/services.rs
#	docs/hardware-parity.md
2026-11-06 19:53:07 +01:00

145 lines
6.6 KiB
Rust

//! Pen tablet input that the windowing layer (winit 0.30) drops: pressure, tilt, barrel rotation
//! and which end of the pen is down (tip or eraser).
//!
//! - **macOS** ([`macos::Monitor`]): an AppKit local event monitor reads the tablet fields of
//! each `NSEvent` (`pressure`, `tilt`, `rotation`, `subtype`, and `pointingDeviceType` from
//! proximity events) before winit sees the event, so every pointer event the UI handles already
//! has its pen sample.
//! - **Windows** ([`windows::Monitor`]): thread-local message hooks inspect `WM_POINTER*`
//! messages on the UI thread to read `PEN_FLAG_BARREL` and the eraser end (`PEN_FLAG_INVERTED`)
//! from `GetPointerPenInfo`, which winit 0.30 drops by mapping pen inputs to touch events.
//! - **Windows WinTab** ([`wintab`]): with Windows Ink disabled for the tablet, a WinTab 1.4
//! system context on PhotoCraft's window supplies pressure, tilt, rotation and the eraser end.
//! The vendor driver still moves the cursor; [`wintab::poll`] is called once per frame.
//! AppKit's monitor API and Windows' thread hooks need OS interop, so `macos.rs` and `windows.rs`
//! allow `unsafe` (an isolated, tested helper crate with `SAFETY:`
//! comments on every block).
//! - **Linux X11** ([`x11::spawn`]): a second, pure-Rust X connection (x11rb) selects XInput2
//! raw events on the root window and maps the tablet device's valuators ("Abs Pressure",
//! "Abs Tilt X/Y", "Abs Rotary Z") to samples. Raw events reach every client that asks, also
//! while winit holds the pointer grab of a drag. No `unsafe`.
//! - **Wayland**: not covered. The `zwp_tablet_v2` protocol has to be bound on winit's own
//! `wl_display` connection (the tablet events name winit's `wl_surface`), which needs
//! `unsafe` foreign-display interop, and binding it makes compositors stop emulating the
//! pointer for the pen, so pen motion would have to be re-injected into egui as well. Without
//! it, compositors give the window no pen input at all, so the desktop app opens its window
//! through Xwayland when a pen is attached, and the X11 reader applies.
//!
//! The platform glue only reads raw values and hands them to the pure mapping in [`appkit`] and
//! [`xi`], which normalise, clamp and track pen state and are tested on every platform.
//!
//! A sample is reported through a callback: `Some(sample)` while a pen is in use (hovering or
//! touching), `None` when the pointer is a mouse again.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod appkit;
pub mod xi;
#[cfg(target_os = "macos")]
pub mod macos;
#[cfg(target_os = "windows")]
pub mod windows;
#[cfg(target_os = "windows")]
pub mod wintab;
#[cfg(target_os = "linux")]
pub mod x11;
/// One pen reading. Tilt is in degrees (-90..90, W3C Pointer Events convention: +x tilts to the
/// right, +y towards the user), rotation in degrees 0..360 (clockwise).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Sample {
/// Tip (or eraser) pressure 0..1; 0 while hovering.
pub pressure: f32,
pub tilt_x: f32,
pub tilt_y: f32,
pub rotation: f32,
/// The eraser end of the pen is in use.
pub eraser: bool,
}
impl Default for Sample {
fn default() -> Self {
Self { pressure: 1.0, tilt_x: 0.0, tilt_y: 0.0, rotation: 0.0, eraser: false }
}
}
impl Sample {
/// Clamp to the documented ranges and replace non-finite values (a NaN pressure reads as
/// full pressure, like a mouse; NaN tilt and rotation as 0).
pub fn sanitized(self) -> Self {
let f = |v: f32, lo: f32, hi: f32, d: f32| if v.is_finite() { v.clamp(lo, hi) } else { d };
let rotation = if self.rotation.is_finite() { self.rotation.rem_euclid(360.0) } else { 0.0 };
Self {
pressure: f(self.pressure, 0.0, 1.0, 1.0),
tilt_x: f(self.tilt_x, -90.0, 90.0, 0.0),
tilt_y: f(self.tilt_y, -90.0, 90.0, 0.0),
// `rem_euclid` can round up to exactly 360 for tiny negative inputs.
rotation: if rotation >= 360.0 { 0.0 } else { rotation },
eraser: self.eraser,
}
}
}
/// What a raw platform event means for the current pen sample.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Update {
/// Nothing to report (an event this module doesn't map).
Keep,
/// The new sample: `Some` for a pen, `None` for a mouse.
Set(Option<Sample>),
}
/// Why tablet input could not be started.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Error {
/// Must be called on the main thread (AppKit).
NotMainThread,
/// The platform or display server doesn't offer what this needs.
Unsupported(String),
/// The platform call failed.
Platform(String),
}
impl std::fmt::Display for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Error::NotMainThread => write!(f, "tablet input must be started on the main thread"),
Error::Unsupported(why) => write!(f, "tablet input unsupported: {why}"),
Error::Platform(why) => write!(f, "tablet input failed: {why}"),
}
}
}
impl std::error::Error for Error {}
/// Sanitize a sample and run a user callback with it, without letting a panic unwind into the platform's event loop (an unwind
/// through an Objective-C block or a detached thread would abort or silently stop input).
pub fn deliver(callback: &dyn Fn(Option<Sample>), sample: Option<Sample>) {
let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| callback(sample.map(Sample::sanitized))));
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sanitized_clamps_and_replaces_non_finite() {
let s = Sample { pressure: 1.7, tilt_x: -120.0, tilt_y: f32::NAN, rotation: -90.0, eraser: true }.sanitized();
assert_eq!(s, Sample { pressure: 1.0, tilt_x: -90.0, tilt_y: 0.0, rotation: 270.0, eraser: true });
let s = Sample { pressure: f32::NAN, tilt_x: f32::INFINITY, tilt_y: f32::NEG_INFINITY, rotation: f32::INFINITY, eraser: false }.sanitized();
assert_eq!(s, Sample::default());
let s = Sample { pressure: -0.5, rotation: -1e-9, ..Default::default() }.sanitized();
assert_eq!((s.pressure, s.rotation), (0.0, 0.0));
assert!(Sample { rotation: 725.0, ..Default::default() }.sanitized().rotation == 5.0);
}
#[test]
fn deliver_contains_a_panicking_callback() {
let seen = std::cell::Cell::new(None);
deliver(&|s| seen.set(s), Some(Sample { pressure: 3.0, ..Default::default() }));
assert_eq!(seen.get().map(|s| s.pressure), Some(1.0), "sanitized on the way out");
deliver(&|_| panic!("boom"), None);
}
}