SDL 3.0
SDL_pen.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryPen
24 *
25 * Include file for SDL pen event handling.
26 *
27 * This file describes operations for pressure-sensitive pen (stylus and/or
28 * eraser) handling, e.g., for input and drawing tablets or suitably equipped
29 * mobile / tablet devices.
30 *
31 * To get started with pens:
32 *
33 * - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
34 * - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent
35 * and SDL_MouseButtonEvent whenever `which` == SDL_PEN_MOUSEID.
36 *
37 * We primarily identify pens by SDL_PenID. The implementation makes a best
38 * effort to relate each SDL_PenID to the same physical device during a
39 * session. Formerly valid SDL_PenID values remain valid even if a device
40 * disappears.
41 *
42 * For identifying pens across sessions, the API provides the type SDL_GUID .
43 */
44
45#ifndef SDL_pen_h_
46#define SDL_pen_h_
47
48#include <SDL3/SDL_error.h>
49#include <SDL3/SDL_guid.h>
50#include <SDL3/SDL_mouse.h>
51#include <SDL3/SDL_stdinc.h>
52
53/* Set up for C function definitions, even when using C++ */
54#ifdef __cplusplus
55extern "C" {
56#endif
57
58typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */
59
60#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid SDL_PenID is valid */
61
62#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) /**< Device ID for mouse events triggered by pen events */
63
64#define SDL_PEN_INFO_UNKNOWN (-1) /**< Marks unknown information when querying the pen */
65
66/**
67 * Pen axis indices
68 *
69 * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and
70 * SDL_PenButtonEvent. The axis indices form a contiguous range of ints from 0
71 * to SDL_PEN_AXIS_LAST, inclusive. All "axis[]" entries are either normalised
72 * to 0..1 or report a (positive or negative) angle in degrees, with 0.0
73 * representing the centre. Not all pens/backends support all axes:
74 * unsupported entries are always "0.0f".
75 *
76 * To convert angles for tilt and rotation into vector representation, use
77 * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
78 *
79 * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`.
80 *
81 * \since This enum is available since SDL 3.0.0
82 */
83typedef enum SDL_PenAxis
84{
85 SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */
86 SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right).
87 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
88 SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down).
89 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
90 SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0..1.0 */
91 SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
92 SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0 */
93 SDL_PEN_NUM_AXES, /**< Last valid axis index */
94 SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
96
97/* Pen flags. These share a bitmask space with SDL_BUTTON_LEFT and friends. */
98#define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */
99#define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */
100#define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */
101#define SDL_PEN_FLAG_AXIS_BIT_OFFSET 16 /* Bit for storing has-axis-0 property */
102
103#define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit))
104#define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)
105
106/* Pen tips */
107#define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */
108#define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */
109
110/**
111 * Pen capabilities reported by SDL_GetPenCapabilities.
112 *
113 * \since This datatype is available since SDL 3.0.0.
114 */
116
117#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */
118#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (SDL_GetPenCapabilities). For events (SDL_PenButtonEvent, SDL_PenMotionEvent, SDL_GetPenStatus) this flag is mutually exclusive with SDL_PEN_ERASER_MASK . */
119#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (SDL_GetPenCapabilities) or is being used as eraser (SDL_PenButtonEvent , SDL_PenMotionEvent , SDL_GetPenStatus) */
120#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */
121#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis SDL_PEN_AXIS_XTILT */
122#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis SDL_PEN_AXIS_YTILT */
123#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in SDL_PEN_AXIS_DISTANCE */
124#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis SDL_PEN_AXIS_ROTATION */
125#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis SDL_PEN_AXIS_SLIDER */
126#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
127
128/**
129 * Pen types
130 *
131 * Some pens identify as a particular type of drawing device (e.g., an
132 * airbrush or a pencil).
133 *
134 * \since This enum is available since SDL 3.0.0
135 */
136typedef enum SDL_PenSubtype
137{
139 SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
140 SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */
141 SDL_PEN_TYPE_PENCIL, /**< Pencil */
142 SDL_PEN_TYPE_BRUSH, /**< Brush-like device */
143 SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */
144 SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */
146
147
148/* Function prototypes */
149
150/**
151 * Retrieves all pens that are connected to the system.
152 *
153 * Yields an array of SDL_PenID values. These identify and track pens
154 * throughout a session. To track pens across sessions (program restart), use
155 * SDL_GUID .
156 *
157 * \param count the number of pens in the array (number of array elements
158 * minus 1, i.e., not counting the terminator 0).
159 * \returns a 0 terminated array of SDL_PenID values, or NULL on failure. The
160 * array must be freed with SDL_free(). On a NULL return,
161 * SDL_GetError() is set.
162 *
163 * \since This function is available since SDL 3.0.0.
164 */
165extern SDL_DECLSPEC SDL_PenID * SDLCALL SDL_GetPens(int *count);
166
167/**
168 * Retrieves the pen's current status.
169 *
170 * If the pen is detached (cf. SDL_PenConnected), this operation may return
171 * default values.
172 *
173 * \param instance_id the pen to query.
174 * \param x out-mode parameter for pen x coordinate. May be NULL.
175 * \param y out-mode parameter for pen y coordinate. May be NULL.
176 * \param axes out-mode parameter for axis information. May be null. The axes
177 * are in the same order as SDL_PenAxis.
178 * \param num_axes maximum number of axes to write to "axes".
179 * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
180 * etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
181 * SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
182 * SDL_GetError()).
183 *
184 * \since This function is available since SDL 3.0.0.
185 */
186extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);
187
188/**
189 * Retrieves an SDL_PenID for the given SDL_GUID.
190 *
191 * \param guid a pen GUID.
192 * \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
193 * SDL_PenID.
194 *
195 * \since This function is available since SDL 3.0.0.
196 */
197extern SDL_DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
198
199/**
200 * Retrieves the SDL_GUID for a given SDL_PenID.
201 *
202 * \param instance_id the pen to query.
203 * \returns the corresponding pen GUID; persistent across multiple sessions.
204 * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
205 *
206 * \since This function is available since SDL 3.0.0.
207 */
208extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
209
210/**
211 * Checks whether a pen is still attached.
212 *
213 * If a pen is detached, it will not show up for SDL_GetPens(). Other
214 * operations will still be available but may return default values.
215 *
216 * \param instance_id a pen ID.
217 * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
218 * attached, or SDL_FALSE otherwise.
219 *
220 * \since This function is available since SDL 3.0.0.
221 */
222extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
223
224/**
225 * Retrieves a human-readable description for a SDL_PenID.
226 *
227 * \param instance_id the pen to query.
228 * \returns a string that contains the name of the pen, intended for human
229 * consumption. The string might or might not be localised, depending
230 * on platform settings. It is not guaranteed to be unique; use
231 * SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
232 * is managed by the SDL pen subsystem and must not be deallocated.
233 * The pointer remains valid until SDL is shut down. Returns NULL on
234 * error (cf. SDL_GetError()).
235 *
236 * \since This function is available since SDL 3.0.0.
237 */
238extern SDL_DECLSPEC const char * SDLCALL SDL_GetPenName(SDL_PenID instance_id);
239
240/**
241 * Pen capabilities, as reported by SDL_GetPenCapabilities()
242 *
243 * \since This struct is available since SDL 3.0.0.
244 */
246{
247 float max_tilt; /**< Physical maximum tilt angle, for XTILT and YTILT, or SDL_PEN_INFO_UNKNOWN . Pens cannot typically tilt all the way to 90 degrees, so this value is usually less than 90.0. */
248 Uint32 wacom_id; /**< For Wacom devices: wacom tool type ID, otherwise 0 (useful e.g. with libwacom) */
249 Sint8 num_buttons; /**< Number of pen buttons (not counting the pen tip), or SDL_PEN_INFO_UNKNOWN */
251
252/**
253 * Retrieves capability flags for a given SDL_PenID.
254 *
255 * \param instance_id the pen to query.
256 * \param capabilities detail information about pen capabilities, such as the
257 * number of buttons.
258 * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES.
259 *
260 * \since This function is available since SDL 3.0.0.
261 */
262extern SDL_DECLSPEC SDL_PenCapabilityFlags SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);
263
264/**
265 * Retrieves the pen type for a given SDL_PenID.
266 *
267 * \param instance_id the pen to query.
268 * \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
269 * Note that the pen type does not dictate whether the pen tip is
270 * SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen
271 * is being used for drawing or in eraser mode, check either the pen
272 * tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK in the
273 * pen state.
274 *
275 * \since This function is available since SDL 3.0.0.
276 */
277extern SDL_DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);
278
279/* Ends C function definitions when using C++ */
280#ifdef __cplusplus
281}
282#endif
283
284#endif /* SDL_pen_h_ */
285
286/* vi: set ts=4 sw=4 expandtab: */
SDL_bool SDL_PenConnected(SDL_PenID instance_id)
Uint32 SDL_PenID
Definition SDL_pen.h:58
SDL_PenCapabilityFlags SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities)
SDL_PenAxis
Definition SDL_pen.h:84
@ SDL_PEN_AXIS_PRESSURE
Definition SDL_pen.h:85
@ SDL_PEN_AXIS_XTILT
Definition SDL_pen.h:86
@ SDL_PEN_AXIS_SLIDER
Definition SDL_pen.h:92
@ SDL_PEN_AXIS_DISTANCE
Definition SDL_pen.h:90
@ SDL_PEN_NUM_AXES
Definition SDL_pen.h:93
@ SDL_PEN_AXIS_YTILT
Definition SDL_pen.h:88
@ SDL_PEN_AXIS_LAST
Definition SDL_pen.h:94
@ SDL_PEN_AXIS_ROTATION
Definition SDL_pen.h:91
SDL_PenID SDL_GetPenFromGUID(SDL_GUID guid)
Uint32 SDL_PenCapabilityFlags
Definition SDL_pen.h:115
Uint32 SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes)
SDL_PenID * SDL_GetPens(int *count)
SDL_PenSubtype SDL_GetPenType(SDL_PenID instance_id)
SDL_GUID SDL_GetPenGUID(SDL_PenID instance_id)
SDL_PenSubtype
Definition SDL_pen.h:137
@ SDL_PEN_TYPE_BRUSH
Definition SDL_pen.h:142
@ SDL_PEN_TYPE_LAST
Definition SDL_pen.h:144
@ SDL_PEN_TYPE_UNKNOWN
Definition SDL_pen.h:138
@ SDL_PEN_TYPE_PEN
Definition SDL_pen.h:140
@ SDL_PEN_TYPE_ERASER
Definition SDL_pen.h:139
@ SDL_PEN_TYPE_PENCIL
Definition SDL_pen.h:141
@ SDL_PEN_TYPE_AIRBRUSH
Definition SDL_pen.h:143
const char * SDL_GetPenName(SDL_PenID instance_id)
int8_t Sint8
Definition SDL_stdinc.h:220
int SDL_bool
Definition SDL_stdinc.h:213
uint32_t Uint32
Definition SDL_stdinc.h:265