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 * \file SDL_pen.h
24 *
25 * Include file for SDL pen event handling.
26 *
27 * This file describes operations for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input
28 * and drawing tablets or suitably equipped mobile / tablet devices.
29 *
30 * To get started with pens:
31 * - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
32 * - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent and SDL_MouseButtonEvent
33 * whenever "which" == SDL_PEN_MOUSEID.
34 *
35 * This header file describes advanced functionality that can be useful for managing user configuration
36 * and understanding the capabilities of the attached pens.
37 *
38 * We primarily identify pens by SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID
39 * to the same physical device during a session. Formerly valid SDL_PenID values remain valid
40 * even if a device 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/* Pen capabilities reported by SDL_GetPenCapabilities */
111#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */
112#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 . */
113#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) */
114#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */
115#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 */
116#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 */
117#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 */
118#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 */
119#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 */
120
121#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
122
123/**
124 * Pen types
125 *
126 * Some pens identify as a particular type of drawing device (e.g., an
127 * airbrush or a pencil).
128 *
129 * \since This enum is available since SDL 3.0.0
130 */
131typedef enum SDL_PenSubtype
132{
134 SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
135 SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */
136 SDL_PEN_TYPE_PENCIL, /**< Pencil */
137 SDL_PEN_TYPE_BRUSH, /**< Brush-like device */
138 SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */
139 SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */
141
142
143/* Function prototypes */
144
145/**
146 * Retrieves all pens that are connected to the system.
147 *
148 * Yields an array of SDL_PenID values. These identify and track pens
149 * throughout a session. To track pens across sessions (program restart), use
150 * SDL_GUID .
151 *
152 * \param count The number of pens in the array (number of array elements
153 * minus 1, i.e., not counting the terminator 0).
154 * \returns A 0 terminated array of SDL_PenID values, or NULL on error. The
155 * array must be freed with SDL_free(). On a NULL return,
156 * SDL_GetError() is set.
157 *
158 * \since This function is available since SDL 3.0.0.
159 */
160extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
161
162/**
163 * Retrieves the pen's current status.
164 *
165 * If the pen is detached (cf. SDL_PenConnected), this operation may return
166 * default values.
167 *
168 * \param instance_id The pen to query.
169 * \param x Out-mode parameter for pen x coordinate. May be NULL.
170 * \param y Out-mode parameter for pen y coordinate. May be NULL.
171 * \param axes Out-mode parameter for axis information. May be null. The axes
172 * are in the same order as SDL_PenAxis.
173 * \param num_axes Maximum number of axes to write to "axes".
174 * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
175 * etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
176 * SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
177 * SDL_GetError()).
178 *
179 * \since This function is available since SDL 3.0.0.
180 */
181extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);
182
183/**
184 * Retrieves an SDL_PenID for the given SDL_GUID.
185 *
186 * \param guid A pen GUID.
187 * \returns A valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
188 * SDL_PenID.
189 *
190 * \since This function is available since SDL 3.0.0.
191 */
192extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
193
194/**
195 * Retrieves the SDL_GUID for a given SDL_PenID.
196 *
197 * \param instance_id The pen to query.
198 * \returns The corresponding pen GUID; persistent across multiple sessions.
199 * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
200 *
201 * \since This function is available since SDL 3.0.0.
202 */
203extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
204
205/**
206 * Checks whether a pen is still attached.
207 *
208 * If a pen is detached, it will not show up for SDL_GetPens(). Other
209 * operations will still be available but may return default values.
210 *
211 * \param instance_id A pen ID.
212 * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
213 * attached, or SDL_FALSE otherwise.
214 *
215 * \since This function is available since SDL 3.0.0.
216 */
217extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
218
219/**
220 * Retrieves a human-readable description for a SDL_PenID.
221 *
222 * \param instance_id The pen to query.
223 * \returns A string that contains the name of the pen, intended for human
224 * consumption. The string might or might not be localised, depending
225 * on platform settings. It is not guaranteed to be unique; use
226 * SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
227 * is managed by the SDL pen subsystem and must not be deallocated.
228 * The pointer remains valid until SDL is shut down. Returns NULL on
229 * error (cf. SDL_GetError())
230 *
231 * \since This function is available since SDL 3.0.0.
232 */
233extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);
234
235/**
236 * Pen capabilities, as reported by SDL_GetPenCapabilities()
237 *
238 * \since This struct is available since SDL 3.0.0.
239 */
241{
242 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. */
243 Uint32 wacom_id; /**< For Wacom devices: wacom tool type ID, otherwise 0 (useful e.g. with libwacom) */
244 Sint8 num_buttons; /**< Number of pen buttons (not counting the pen tip), or SDL_PEN_INFO_UNKNOWN */
246
247/**
248 * Retrieves capability flags for a given SDL_PenID.
249 *
250 * \param instance_id The pen to query.
251 * \param capabilities Detail information about pen capabilities, such as the
252 * number of buttons
253 * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES
254 *
255 * \since This function is available since SDL 3.0.0.
256 */
257extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);
258
259/**
260 * Retrieves the pen type for a given SDL_PenID.
261 *
262 * \param instance_id The pen to query.
263 * \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
264 * Note that the pen type does not dictate whether the pen tip is
265 * SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen
266 * is being used for drawing or in eraser mode, check either the pen
267 * tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK in the
268 * pen state.
269 *
270 * \since This function is available since SDL 3.0.0.
271 */
272extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);
273
274/* Ends C function definitions when using C++ */
275#ifdef __cplusplus
276}
277#endif
278
279#endif /* SDL_pen_h_ */
280
281/* vi: set ts=4 sw=4 expandtab: */
SDL_bool SDL_PenConnected(SDL_PenID instance_id)
Uint32 SDL_PenID
Definition SDL_pen.h:58
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_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:132
@ SDL_PEN_TYPE_BRUSH
Definition SDL_pen.h:137
@ SDL_PEN_TYPE_LAST
Definition SDL_pen.h:139
@ SDL_PEN_TYPE_UNKNOWN
Definition SDL_pen.h:133
@ SDL_PEN_TYPE_PEN
Definition SDL_pen.h:135
@ SDL_PEN_TYPE_ERASER
Definition SDL_pen.h:134
@ SDL_PEN_TYPE_PENCIL
Definition SDL_pen.h:136
@ SDL_PEN_TYPE_AIRBRUSH
Definition SDL_pen.h:138
Uint32 SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities)
const char * SDL_GetPenName(SDL_PenID instance_id)
int8_t Sint8
Definition SDL_stdinc.h:179
int SDL_bool
Definition SDL_stdinc.h:170
uint32_t Uint32
Definition SDL_stdinc.h:224