SDL_pen.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_mouse.h>`
`#include <SDL3/SDL_touch.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_pen.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define | SDL_PEN_MOUSEID ((SDL_MouseID)-2)
#define | SDL_PEN_TOUCHID ((SDL_TouchID)-2)
#define | SDL_PEN_INPUT_DOWN (1u << 0)
#define | SDL_PEN_INPUT_BUTTON_1 (1u << 1)
#define | SDL_PEN_INPUT_BUTTON_2 (1u << 2)
#define | SDL_PEN_INPUT_BUTTON_3 (1u << 3)
#define | SDL_PEN_INPUT_BUTTON_4 (1u << 4)
#define | SDL_PEN_INPUT_BUTTON_5 (1u << 5)
#define | SDL_PEN_INPUT_ERASER_TIP (1u << 30)
#define | SDL_PEN_INPUT_IN_PROXIMITY (1u << 31)

## Typedefs

typedef Uint32 | SDL_PenID
typedef Uint32 | SDL_PenInputFlags

## Enumerations

enum | SDL_PenAxis { SDL_PEN_AXIS_PRESSURE , SDL_PEN_AXIS_XTILT , SDL_PEN_AXIS_YTILT , SDL_PEN_AXIS_DISTANCE , SDL_PEN_AXIS_ROTATION , SDL_PEN_AXIS_SLIDER , SDL_PEN_AXIS_TANGENTIAL_PRESSURE , SDL_PEN_AXIS_COUNT }
enum | SDL_PenDeviceType { SDL_PEN_DEVICE_TYPE_INVALID = -1 , SDL_PEN_DEVICE_TYPE_UNKNOWN , SDL_PEN_DEVICE_TYPE_DIRECT , SDL_PEN_DEVICE_TYPE_INDIRECT }

## Functions

SDL_PenDeviceType | SDL_GetPenDeviceType (SDL_PenID instance_id)

## Macro Definition Documentation

## SDL_PEN_INPUT_BUTTON_1

#define SDL_PEN_INPUT_BUTTON_1 (1u << 1)

button 1 is pressed

Definition at line 117 of file SDL_pen.h.

## SDL_PEN_INPUT_BUTTON_2

#define SDL_PEN_INPUT_BUTTON_2 (1u << 2)

button 2 is pressed

Definition at line 118 of file SDL_pen.h.

## SDL_PEN_INPUT_BUTTON_3

#define SDL_PEN_INPUT_BUTTON_3 (1u << 3)

button 3 is pressed

Definition at line 119 of file SDL_pen.h.

## SDL_PEN_INPUT_BUTTON_4

#define SDL_PEN_INPUT_BUTTON_4 (1u << 4)

button 4 is pressed

Definition at line 120 of file SDL_pen.h.

## SDL_PEN_INPUT_BUTTON_5

#define SDL_PEN_INPUT_BUTTON_5 (1u << 5)

button 5 is pressed

Definition at line 121 of file SDL_pen.h.

## SDL_PEN_INPUT_DOWN

#define SDL_PEN_INPUT_DOWN (1u << 0)

pen is pressed down

Definition at line 116 of file SDL_pen.h.

## SDL_PEN_INPUT_ERASER_TIP

#define SDL_PEN_INPUT_ERASER_TIP (1u << 30)

eraser tip is used

Definition at line 122 of file SDL_pen.h.

## SDL_PEN_INPUT_IN_PROXIMITY

#define SDL_PEN_INPUT_IN_PROXIMITY (1u << 31)

pen is in proximity (since SDL 3.4.0)

Definition at line 123 of file SDL_pen.h.

## SDL_PEN_MOUSEID

#define SDL_PEN_MOUSEID ((SDL_MouseID)-2)

The SDL_MouseID for mouse events simulated with pen input.

Since
  This macro is available since SDL 3.2.0.

Definition at line 100 of file SDL_pen.h.

## SDL_PEN_TOUCHID

#define SDL_PEN_TOUCHID ((SDL_TouchID)-2)

The SDL_TouchID for touch events simulated with pen input.

Since
  This macro is available since SDL 3.2.0.

Definition at line 107 of file SDL_pen.h.

## Typedef Documentation

## SDL_PenID

typedef Uint32 SDL_PenID

# CategoryPen

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. 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.

Since
  This datatype is available since SDL 3.2.0.

Definition at line 93 of file SDL_pen.h.

## SDL_PenInputFlags

typedef Uint32 SDL_PenInputFlags

Pen input flags, as reported by various pen events' pen_state field.

Since
  This datatype is available since SDL 3.2.0.

Definition at line 114 of file SDL_pen.h.

## Enumeration Type Documentation

## SDL_PenAxis

enum SDL_PenAxis

Pen axis indices.

These are the valid values for the axis field in SDL_PenAxisEvent. All axes are either normalised to 0..1 or report a (positive or negative) angle in degrees, with 0.0 representing the centre. Not all pens/backends support all axes: unsupported axes are always zero.

To convert angles for tilt and rotation into vector representation, use SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:

SDL_sinf(xtilt * SDL_PI_F / 180.0).

Since
  This enum is available since SDL 3.2.0.

Enumerator
SDL_PEN_AXIS_PRESSURE | Pen pressure. Unidirectional: 0 to 1.0
SDL_PEN_AXIS_XTILT | Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right).
SDL_PEN_AXIS_YTILT | Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down).
SDL_PEN_AXIS_DISTANCE | Pen distance to drawing surface. Unidirectional: 0.0 to 1.0
SDL_PEN_AXIS_ROTATION | Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down).
SDL_PEN_AXIS_SLIDER | Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0
SDL_PEN_AXIS_TANGENTIAL_PRESSURE | Pressure from squeezing the pen ("barrel pressure").
SDL_PEN_AXIS_COUNT | Total known pen axis types in this version of SDL. This number may grow in future releases!

Definition at line 140 of file SDL_pen.h.

{
SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */
SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */
SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */
SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */
SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */
SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */
SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */
} SDL_PenAxis;
SDL_PenAxis
SDL_PenAxis
Definition SDL_pen.h:141
SDL_PEN_AXIS_PRESSURE
@ SDL_PEN_AXIS_PRESSURE
Definition SDL_pen.h:142
SDL_PEN_AXIS_XTILT
@ SDL_PEN_AXIS_XTILT
Definition SDL_pen.h:143
SDL_PEN_AXIS_SLIDER
@ SDL_PEN_AXIS_SLIDER
Definition SDL_pen.h:147
SDL_PEN_AXIS_DISTANCE
@ SDL_PEN_AXIS_DISTANCE
Definition SDL_pen.h:145
SDL_PEN_AXIS_YTILT
@ SDL_PEN_AXIS_YTILT
Definition SDL_pen.h:144
SDL_PEN_AXIS_ROTATION
@ SDL_PEN_AXIS_ROTATION
Definition SDL_pen.h:146
SDL_PEN_AXIS_TANGENTIAL_PRESSURE
@ SDL_PEN_AXIS_TANGENTIAL_PRESSURE
Definition SDL_pen.h:148
SDL_PEN_AXIS_COUNT
@ SDL_PEN_AXIS_COUNT
Definition SDL_pen.h:149

## SDL_PenDeviceType

enum SDL_PenDeviceType

An enum that describes the type of a pen device.

A "direct" device is a pen that touches a graphic display (like an Apple Pencil on an iPad's screen). "Indirect" devices touch an external tablet surface that is connected to the machine but is not a display (like a lower-end Wacom tablet connected over USB).

Apps may use this information to decide if they should draw a cursor; if the pen is touching the screen directly, a cursor doesn't make sense and can be in the way, but becomes necessary for indirect devices to know where on the display they are interacting.

Since
  This enum is available since SDL 3.4.0.

Enumerator
SDL_PEN_DEVICE_TYPE_INVALID | Not a valid pen device.
SDL_PEN_DEVICE_TYPE_UNKNOWN | Don't know specifics of this pen.
SDL_PEN_DEVICE_TYPE_DIRECT | Pen touches display.
SDL_PEN_DEVICE_TYPE_INDIRECT | Pen touches something that isn't the display.

Definition at line 167 of file SDL_pen.h.

{
SDL_PEN_DEVICE_TYPE_INVALID = -1, /**< Not a valid pen device. */
SDL_PEN_DEVICE_TYPE_UNKNOWN, /**< Don't know specifics of this pen. */
SDL_PEN_DEVICE_TYPE_DIRECT, /**< Pen touches display. */
SDL_PEN_DEVICE_TYPE_INDIRECT /**< Pen touches something that isn't the display. */
} SDL_PenDeviceType;
SDL_PenDeviceType
SDL_PenDeviceType
Definition SDL_pen.h:168
SDL_PEN_DEVICE_TYPE_INVALID
@ SDL_PEN_DEVICE_TYPE_INVALID
Definition SDL_pen.h:169
SDL_PEN_DEVICE_TYPE_UNKNOWN
@ SDL_PEN_DEVICE_TYPE_UNKNOWN
Definition SDL_pen.h:170
SDL_PEN_DEVICE_TYPE_DIRECT
@ SDL_PEN_DEVICE_TYPE_DIRECT
Definition SDL_pen.h:171
SDL_PEN_DEVICE_TYPE_INDIRECT
@ SDL_PEN_DEVICE_TYPE_INDIRECT
Definition SDL_pen.h:172

## Function Documentation

## SDL_GetPenDeviceType()

SDL_PenDeviceType SDL_GetPenDeviceType | ( | SDL_PenID | instance_id | ) |

extern

Get the device type of the given pen.

Many platforms do not supply this information, so an app must always be prepared to get an SDL_PEN_DEVICE_TYPE_UNKNOWN result.

Parameters

  instance_id | the pen instance ID.

Returns
  the device type of the given pen, or SDL_PEN_DEVICE_TYPE_INVALID on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.4.0.