Atlas - SDL_pen.h
Home / ext / SDL / include / SDL3
Lines: 1 | Size: 8297 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1/*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2025 Sam Lantinga <[email protected]>
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
74extern "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 */
93typedef 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 */
114typedef 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 */
140typedef 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 */
167typedef 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 */
189extern 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
199
[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.