|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 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 * SDL pen event handling.
|
|
|
26 *
|
|
|
27 * SDL provides an API for pressure-sensitive pen (stylus and/or eraser)
|
|
|
28 * handling, e.g., for input and drawing tablets or suitably equipped mobile /
|
|
|
29 * tablet devices.
|
|
|
30 *
|
|
|
31 * To get started with pens, simply handle pen events:
|
|
|
32 *
|
|
|
33 * - SDL_EVENT_PEN_PROXIMITY_IN, SDL_EVENT_PEN_PROXIMITY_OUT
|
|
|
34 * (SDL_PenProximityEvent)
|
|
|
35 * - SDL_EVENT_PEN_DOWN, SDL_EVENT_PEN_UP (SDL_PenTouchEvent)
|
|
|
36 * - SDL_EVENT_PEN_MOTION (SDL_PenMotionEvent)
|
|
|
37 * - SDL_EVENT_PEN_BUTTON_DOWN, SDL_EVENT_PEN_BUTTON_UP (SDL_PenButtonEvent)
|
|
|
38 * - SDL_EVENT_PEN_AXIS (SDL_PenAxisEvent)
|
|
|
39 *
|
|
|
40 * Pens may provide more than simple touch input; they might have other axes,
|
|
|
41 * such as pressure, tilt, rotation, etc.
|
|
|
42 *
|
|
|
43 * When a pen starts providing input, SDL will assign it a unique SDL_PenID,
|
|
|
44 * which will remain for the life of the process, as long as the pen stays
|
|
|
45 * connected. A pen leaving proximity (being taken far enough away from the
|
|
|
46 * digitizer tablet that it no longer reponds) and then coming back should
|
|
|
47 * fire proximity events, but the SDL_PenID should remain consistent.
|
|
|
48 * Unplugging the digitizer and reconnecting may cause future input to have a
|
|
|
49 * new SDL_PenID, as SDL may not know that this is the same hardware.
|
|
|
50 *
|
|
|
51 * Please note that various platforms vary wildly in how (and how well) they
|
|
|
52 * support pen input. If your pen supports some piece of functionality but SDL
|
|
|
53 * doesn't seem to, it might actually be the operating system's fault. For
|
|
|
54 * example, some platforms can manage multiple devices at the same time, but
|
|
|
55 * others will make any connected pens look like a single logical device, much
|
|
|
56 * how all USB mice connected to a computer will move the same system cursor.
|
|
|
57 * cursor. Other platforms might not support pen buttons, or the distance
|
|
|
58 * axis, etc. Very few platforms can even report _what_ functionality the pen
|
|
|
59 * supports in the first place, so best practices is to either build UI to let
|
|
|
60 * the user configure their pens, or be prepared to handle new functionality
|
|
|
61 * for a pen the first time an event is reported.
|
|
|
62 */
|
|
|
63
|
|
|
64 #ifndef SDL_pen_h_
|
|
|
65 #define SDL_pen_h_
|
|
|
66
|
|
|
67 #include <SDL3/SDL_stdinc.h>
|
|
|
68 #include <SDL3/SDL_mouse.h>
|
|
|
69 #include <SDL3/SDL_touch.h>
|
|
|
70
|
|
|
71 #include <SDL3/SDL_begin_code.h>
|
|
|
72 /* Set up for C function definitions, even when using C++ */
|
|
|
73 #ifdef __cplusplus
|
|
|
74 extern "C" {
|
|
|
75 #endif
|
|
|
76
|
|
|
77 /**
|
|
|
78 * SDL pen instance IDs.
|
|
|
79 *
|
|
|
80 * Zero is used to signify an invalid/null device.
|
|
|
81 *
|
|
|
82 * These show up in pen events when SDL sees input from them. They remain
|
|
|
83 * consistent as long as SDL can recognize a tool to be the same pen; but if a
|
|
|
84 * pen's digitizer table is physically detached from the computer, it might
|
|
|
85 * get a new ID when reconnected, as SDL won't know it's the same device.
|
|
|
86 *
|
|
|
87 * These IDs are only stable within a single run of a program; the next time a
|
|
|
88 * program is run, the pen's ID will likely be different, even if the hardware
|
|
|
89 * hasn't been disconnected, etc.
|
|
|
90 *
|
|
|
91 * \since This datatype is available since SDL 3.2.0.
|
|
|
92 */
|
|
|
93 typedef Uint32 SDL_PenID;
|
|
|
94
|
|
|
95 /**
|
|
|
96 * The SDL_MouseID for mouse events simulated with pen input.
|
|
|
97 *
|
|
|
98 * \since This macro is available since SDL 3.2.0.
|
|
|
99 */
|
|
|
100 #define SDL_PEN_MOUSEID ((SDL_MouseID)-2)
|
|
|
101
|
|
|
102 /**
|
|
|
103 * The SDL_TouchID for touch events simulated with pen input.
|
|
|
104 *
|
|
|
105 * \since This macro is available since SDL 3.2.0.
|
|
|
106 */
|
|
|
107 #define SDL_PEN_TOUCHID ((SDL_TouchID)-2)
|
|
|
108
|
|
|
109 /**
|
|
|
110 * Pen input flags, as reported by various pen events' `pen_state` field.
|
|
|
111 *
|
|
|
112 * \since This datatype is available since SDL 3.2.0.
|
|
|
113 */
|
|
|
114 typedef Uint32 SDL_PenInputFlags;
|
|
|
115
|
|
|
116 #define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */
|
|
|
117 #define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */
|
|
|
118 #define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */
|
|
|
119 #define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */
|
|
|
120 #define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */
|
|
|
121 #define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */
|
|
|
122 #define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */
|
|
|
123 #define SDL_PEN_INPUT_IN_PROXIMITY (1u << 31) /**< pen is in proximity (since SDL 3.4.0) */
|
|
|
124
|
|
|
125 /**
|
|
|
126 * Pen axis indices.
|
|
|
127 *
|
|
|
128 * These are the valid values for the `axis` field in SDL_PenAxisEvent. All
|
|
|
129 * axes are either normalised to 0..1 or report a (positive or negative) angle
|
|
|
130 * in degrees, with 0.0 representing the centre. Not all pens/backends support
|
|
|
131 * all axes: unsupported axes are always zero.
|
|
|
132 *
|
|
|
133 * To convert angles for tilt and rotation into vector representation, use
|
|
|
134 * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
|
|
|
135 *
|
|
|
136 * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`.
|
|
|
137 *
|
|
|
138 * \since This enum is available since SDL 3.2.0.
|
|
|
139 */
|
|
|
140 typedef enum SDL_PenAxis
|
|
|
141 {
|
|
|
142 SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */
|
|
|
143 SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */
|
|
|
144 SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */
|
|
|
145 SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */
|
|
|
146 SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
|
|
|
147 SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */
|
|
|
148 SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */
|
|
|
149 SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */
|
|
|
150 } SDL_PenAxis;
|
|
|
151
|
|
|
152 /**
|
|
|
153 * An enum that describes the type of a pen device.
|
|
|
154 *
|
|
|
155 * A "direct" device is a pen that touches a graphic display (like an Apple
|
|
|
156 * Pencil on an iPad's screen). "Indirect" devices touch an external tablet
|
|
|
157 * surface that is connected to the machine but is not a display (like a
|
|
|
158 * lower-end Wacom tablet connected over USB).
|
|
|
159 *
|
|
|
160 * Apps may use this information to decide if they should draw a cursor; if
|
|
|
161 * the pen is touching the screen directly, a cursor doesn't make sense and
|
|
|
162 * can be in the way, but becomes necessary for indirect devices to know where
|
|
|
163 * on the display they are interacting.
|
|
|
164 *
|
|
|
165 * \since This enum is available since SDL 3.4.0.
|
|
|
166 */
|
|
|
167 typedef enum SDL_PenDeviceType
|
|
|
168 {
|
|
|
169 SDL_PEN_DEVICE_TYPE_INVALID = -1, /**< Not a valid pen device. */
|
|
|
170 SDL_PEN_DEVICE_TYPE_UNKNOWN, /**< Don't know specifics of this pen. */
|
|
|
171 SDL_PEN_DEVICE_TYPE_DIRECT, /**< Pen touches display. */
|
|
|
172 SDL_PEN_DEVICE_TYPE_INDIRECT /**< Pen touches something that isn't the display. */
|
|
|
173 } SDL_PenDeviceType;
|
|
|
174
|
|
|
175 /**
|
|
|
176 * Get the device type of the given pen.
|
|
|
177 *
|
|
|
178 * Many platforms do not supply this information, so an app must always be
|
|
|
179 * prepared to get an SDL_PEN_DEVICE_TYPE_UNKNOWN result.
|
|
|
180 *
|
|
|
181 * \param instance_id the pen instance ID.
|
|
|
182 * \returns the device type of the given pen, or SDL_PEN_DEVICE_TYPE_INVALID
|
|
|
183 * on failure; call SDL_GetError() for more information.
|
|
|
184 *
|
|
|
185 * \threadsafety It is safe to call this function from any thread.
|
|
|
186 *
|
|
|
187 * \since This function is available since SDL 3.4.0.
|
|
|
188 */
|
|
|
189 extern SDL_DECLSPEC SDL_PenDeviceType SDLCALL SDL_GetPenDeviceType(SDL_PenID instance_id);
|
|
|
190
|
|
|
191 /* Ends C function definitions when using C++ */
|
|
|
192 #ifdef __cplusplus
|
|
|
193 }
|
|
|
194 #endif
|
|
|
195 #include <SDL3/SDL_close_code.h>
|
|
|
196
|
|
|
197 #endif /* SDL_pen_h_ */
|
|
|
198
|
