SDL pen event handling.

SDL provides an API for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input and drawing tablets or suitably equipped mobile / tablet devices.

To get started with pens, simply handle pen events:

• SDL_EVENT_PEN_PROXIMITY_IN, SDL_EVENT_PEN_PROXIMITY_OUT (SDL_PenProximityEvent)
• SDL_EVENT_PEN_DOWN, SDL_EVENT_PEN_UP (SDL_PenTouchEvent)
• SDL_EVENT_PEN_MOTION (SDL_PenMotionEvent)
• SDL_EVENT_PEN_BUTTON_DOWN, SDL_EVENT_PEN_BUTTON_UP (SDL_PenButtonEvent)
• SDL_EVENT_PEN_AXIS (SDL_PenAxisEvent)

Pens may provide more than simple touch input; they might have other axes, such as pressure, tilt, rotation, etc.

When a pen starts providing input, SDL will assign it a unique SDL_PenID, which will remain for the life of the process, as long as the pen stays connected. A pen leaving proximity (being taken far enough away from the digitizer tablet that it no longer reponds) and then coming back should fire proximity events, but the SDL_PenID should remain consistent. Unplugging the digitizer and reconnecting may cause future input to have a new SDL_PenID, as SDL may not know that this is the same hardware.

Please note that various platforms vary wildly in how (and how well) they support pen input. If your pen supports some piece of functionality but SDL doesn't seem to, it might actually be the operating system's fault. For example, some platforms can manage multiple devices at the same time, but others will make any connected pens look like a single logical device, much how all USB mice connected to a computer will move the same system cursor. Other platforms might not support pen buttons, or the distance axis, etc. Very few platforms can even report what functionality the pen supports in the first place, so best practices is to either build UI to let the user configure their pens, or be prepared to handle new functionality for a pen the first time an event is reported. SDL pen instance IDs.

Zero is used to signify an invalid/null device.

These show up in pen events when SDL sees input from them. They remain consistent as long as SDL can recognize a tool to be the same pen; but if a pen's digitizer table is physically detached from the computer, it might get a new ID when reconnected, as SDL won't know it's the same device.

These IDs are only stable within a single run of a program; the next time a program is run, the pen's ID will likely be different, even if the hardware hasn't been disconnected, etc.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Pen.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Since: 3.2.0