SDL 3.0
SDL_pen.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2023 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 "SDL_error.h"
49#include "SDL_guid.h"
50#include "SDL_stdinc.h"
51
52/* Set up for C function definitions, even when using C++ */
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */
58
59#define SDL_PEN_INVALID ((Uint32)0) /**< Reserved invalid ::SDL_PenID is valid */
60
61#define SDL_PEN_MOUSEID ((Uint32)-2) /**< Device ID for mouse events triggered by pen events */
62
63#define SDL_PEN_INFO_UNKNOWN (-1) /**< Marks unknown information when querying the pen */
64
65/**
66 * Pen axis indices
67 *
68 * Below are the valid indices to the "axis" array from ::SDL_PenMotionEvent and ::SDL_PenButtonEvent.
69 * The axis indices form a contiguous range of ints from 0 to ::SDL_PEN_AXIS_LAST, inclusive.
70 * All "axis[]" entries are either normalised to 0..1 or report a (positive or negative)
71 * angle in degrees, with 0.0 representing the centre.
72 * Not all pens/backends support all axes: unsupported entries are always "0.0f".
73 *
74 * To convert angles for tilt and rotation into vector representation, use
75 * SDL_sinf on the XTILT, YTILT, or ROTATION component, e.g., "SDL_sinf(xtilt * SDL_PI_F / 180.0)".
76 */
77typedef enum
78{
79 SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */
80 SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right).
81 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
82 SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down).
83 The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
84 SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0..1.0 */
85 SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
86 SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0 */
87 SDL_PEN_NUM_AXES, /**< Last valid axis index */
88 SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
90
91/* Pen flags. These share a bitmask space with ::SDL_BUTTON_LEFT and friends. */
92#define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */
93#define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */
94#define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */
95#define SDL_PEN_FLAG_AXIS_BIT_OFFSET 16 /* Bit for storing has-axis-0 property */
96
97#define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit))
98#define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)
99
100/**
101 * Pen tips
102 * @{
103 */
104#define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */
105#define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */
106/** @} */
107
108
109/**
110 * \defgroup SDL_PEN_CAPABILITIES Pen capabilities
111 * Pen capabilities reported by ::SDL_GetPenCapabilities
112 * @{
113 */
114#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */
115#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 . */
116#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) */
117#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis ::SDL_PEN_AXIS_PRESSURE */
118#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 */
119#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 */
120#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 */
121#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 */
122#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 */
123
124#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
125/**< Masks for all axes that may be bidirectional */
126/** @} */
127
128/**
129 * Pen types
130 *
131 * Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
132 *
133 */
134typedef enum
135{
136 SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
137 SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */
138 SDL_PEN_TYPE_PENCIL, /**< Pencil */
139 SDL_PEN_TYPE_BRUSH, /**< Brush-like device */
140 SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */
141 SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */
143
144
145/* Function prototypes */
146
147/**
148 * Retrieves all pens that are connected to the system.
149 *
150 * Yields an array of ::SDL_PenID values. These identify and track pens
151 * throughout a session. To track pens across sessions (program restart), use
152 * ::SDL_GUID .
153 *
154 * \param count The number of pens in the array (number of array elements
155 * minus 1, i.e., not counting the terminator 0).
156 * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
157 * array must be freed with ::SDL_free(). On a NULL return,
158 * ::SDL_GetError() is set.
159 *
160 * \since This function is available since SDL 3.0.0
161 */
162extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
163
164/**
165 * Retrieves the pen's current status.
166 *
167 * If the pen is detached (cf. ::SDL_PenConnected), this operation may return
168 * default values.
169 *
170 * \param instance_id The pen to query.
171 * \param x Out-mode parameter for pen x coordinate. May be NULL.
172 * \param y Out-mode parameter for pen y coordinate. May be NULL.
173 * \param axes Out-mode parameter for axis information. May be null. The axes
174 * are in the same order as ::SDL_PenAxis.
175 * \param num_axes Maximum number of axes to write to "axes".
176 * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
177 * etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
178 * ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
179 * ::SDL_GetError()).
180 *
181 * \since This function is available since SDL 3.0.0
182 */
183extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);
184
185/**
186 * Retrieves an ::SDL_PenID for the given ::SDL_GUID.
187 *
188 * \param guid A pen GUID.
189 * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
190 * SDL_PenID.
191 *
192 * \since This function is available since SDL 3.0.0
193 *
194 * \sa SDL_GUID
195 */
196extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
197
198/**
199 * Retrieves the ::SDL_GUID for a given ::SDL_PenID.
200 *
201 * \param instance_id The pen to query.
202 * \returns The corresponding pen GUID; persistent across multiple sessions.
203 * If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
204 *
205 * \since This function is available since SDL 3.0.0
206 *
207 * \sa SDL_PenForID
208 */
209extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
210
211/**
212 * Checks whether a pen is still attached.
213 *
214 * If a pen is detached, it will not show up for ::SDL_GetPens(). Other
215 * operations will still be available but may return default values.
216 *
217 * \param instance_id A pen ID.
218 * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
219 * attached, or SDL_FALSE otherwise.
220 *
221 * \since This function is available since SDL 3.0.0
222 */
223extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
224
225/**
226 * Retrieves a human-readable description for a ::SDL_PenID.
227 *
228 * \param instance_id The pen to query.
229 * \returns A string that contains the name of the pen, intended for human
230 * consumption. The string might or might not be localised, depending
231 * on platform settings. It is not guaranteed to be unique; use
232 * ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
233 * pointer is managed by the SDL pen subsystem and must not be
234 * deallocated. The pointer remains valid until SDL is shut down.
235 * Returns NULL on error (cf. ::SDL_GetError())
236 *
237 * \since This function is available since SDL 3.0.0
238 */
239extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);
240
241/**
242 * Pen capabilities, as reported by ::SDL_GetPenCapabilities()
243 */
245{
246 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. */
247 Uint32 wacom_id; /**< For Wacom devices: wacom tool type ID, otherwise 0 (useful e.g. with libwacom) */
248 Sint8 num_buttons; /**< Number of pen buttons (not counting the pen tip), or SDL_PEN_INFO_UNKNOWN */
250
251/**
252 * Retrieves capability flags for a given ::SDL_PenID.
253 *
254 * \param instance_id The pen to query.
255 * \param capabilities Detail information about pen capabilities, such as the
256 * number of buttons
257 * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES
258 *
259 * \since This function is available since SDL 3.0.0
260 */
261extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);
262
263/**
264 * Retrieves the pen type for a given ::SDL_PenID.
265 *
266 * \param instance_id The pen to query.
267 * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
268 * Note that the pen type does not dictate whether the pen tip is
269 * ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
270 * pen is being used for drawing or in eraser mode, check either the
271 * pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
272 * in the pen state.
273 *
274 * \since This function is available since SDL 3.0.0
275 */
276extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);
277
278/* Ends C function definitions when using C++ */
279#ifdef __cplusplus
280}
281#endif
282
283#endif /* SDL_pen_h_ */
284
285/* vi: set ts=4 sw=4 expandtab: */
SDL_bool SDL_PenConnected(SDL_PenID instance_id)
Uint32 SDL_PenID
Definition SDL_pen.h:57
SDL_PenAxis
Definition SDL_pen.h:78
@ SDL_PEN_AXIS_PRESSURE
Definition SDL_pen.h:79
@ SDL_PEN_AXIS_XTILT
Definition SDL_pen.h:80
@ SDL_PEN_AXIS_SLIDER
Definition SDL_pen.h:86
@ SDL_PEN_AXIS_DISTANCE
Definition SDL_pen.h:84
@ SDL_PEN_NUM_AXES
Definition SDL_pen.h:87
@ SDL_PEN_AXIS_YTILT
Definition SDL_pen.h:82
@ SDL_PEN_AXIS_LAST
Definition SDL_pen.h:88
@ SDL_PEN_AXIS_ROTATION
Definition SDL_pen.h:85
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:135
@ SDL_PEN_TYPE_BRUSH
Definition SDL_pen.h:139
@ SDL_PEN_TYPE_LAST
Definition SDL_pen.h:141
@ SDL_PEN_TYPE_PEN
Definition SDL_pen.h:137
@ SDL_PEN_TYPE_ERASER
Definition SDL_pen.h:136
@ SDL_PEN_TYPE_PENCIL
Definition SDL_pen.h:138
@ SDL_PEN_TYPE_AIRBRUSH
Definition SDL_pen.h:140
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:143
unsigned int SDL_bool
Definition SDL_stdinc.h:136
uint32_t Uint32
Definition SDL_stdinc.h:173