API for pressure-sensitive pens + XInput2/Wayland

This patch adds an API for querying pressure-
sensitive pens, cf. SDL_pen.h:
- Enumerate all pens
- Get pen capabilities, names, GUIDs
- Distinguishes pens and erasers
- Distinguish attached and detached pens
- Pressure and tilt support
- Rotation, distance, throttle wheel support
  (throttle wheel untested)
- Pen type and meta-information reporting
  (partially tested)

Pen event reporting:
- Three new event structures: PenTip, PenMotion, and
  PenButton
- Report location with sub-pixel precision
- Include axis and button status, is-eraser flag

Internal pen tracker, intended to be independent
of platform APIs, cf. SDL_pen_c.h:
- Track known pens
- Handle pen hotplugging

Automatic test:
- testautomation_pen.c

Other features:
- XInput2 implementation, incl. hotplugging
- Wayland implementation, incl. hotplugging
- Backward compatibility: pen events default to
  emulating pens with mouse ID SDL_PEN_MOUSEID
- Can be toggled via SDL_HINT_PEN_NOT_MOUSE
- Test/demo program (testpen)
- Wacom pen feature identification by pen ID

Acknowledgements:
- Ping Cheng (Wacom) provided extensive feedback
  on Wacom pen features and detection so that
  hopefully untested Wacom devices have a
  realistic chance of working out of the box.
This commit is contained in:
Christoph Reichenbach
2023-08-27 06:20:29 +00:00
committed by Sam Lantinga
parent d3e43668d0
commit 7c80ac6df7
36 changed files with 5843 additions and 241 deletions

View File

@@ -1220,6 +1220,40 @@ extern "C" {
*/
#define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE"
/**
* Treat pen movement as separate from mouse movement
*
* By default, pens report both ::SDL_MouseMotionEvent and ::SDL_PenMotionEvent updates
* (analogously for button presses). This hint allows decoupling mouse and pen updates.
*
* This variable toggles between the following behaviour:
* "0" - (Default) Pen acts as a mouse with mouse ID ::SDL_PEN_MOUSEID.
* Use case: client application is not pen aware, user wants to
* use pen instead of mouse to interact.
* "1" - Pen reports mouse clicks and movement events but does not update
* SDL-internal mouse state (buttons pressed, current mouse location).
* Use case: client application is not pen aware, user frequently
* alternates between pen and "real" mouse.
* "2" - Pen reports no mouse events.
* Use case: pen-aware client application uses this hint to allow user to
* toggle between pen+mouse mode ("2") and pen-only mode ("1" or "0").
*/
#define SDL_HINT_PEN_NOT_MOUSE "SDL_HINT_PEN_NOT_MOUSE"
/**
* Pen mouse button emulation triggers only when the pen touches the tablet surface
*
* "0" - The pen reports mouse button press/release immediately when the pen
* button is pressed/released, and the pen tip touching the surface counts
* as left mouse button press.
* "1" - (Default) Mouse button presses are sent when the pen first touches
* the tablet (analogously for releases). Not pressing a pen button
* simulates mouse button 1, pressing the first pen button simulates
* mouse button 2 etc.; it is not possible to report multiple buttons
* as pressed at the same time.
*/
#define SDL_HINT_PEN_DELAY_MOUSE_BUTTON "SDL_HINT_PEN_DELAY_MOUSE_BUTTON"
/**
* Tell SDL not to catch the SIGINT or SIGTERM signals.
*