|
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 * # CategoryTouch
|
|
|
24 *
|
|
|
25 * SDL offers touch input, on platforms that support it. It can manage
|
|
|
26 * multiple touch devices and track multiple fingers on those devices.
|
|
|
27 *
|
|
|
28 * Touches are mostly dealt with through the event system, in the
|
|
|
29 * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP
|
|
|
30 * events, but there are also functions to query for hardware details, etc.
|
|
|
31 *
|
|
|
32 * The touch system, by default, will also send virtual mouse events; this can
|
|
|
33 * be useful for making a some desktop apps work on a phone without
|
|
|
34 * significant changes. For apps that care about mouse and touch input
|
|
|
35 * separately, they should ignore mouse events that have a `which` field of
|
|
|
36 * SDL_TOUCH_MOUSEID.
|
|
|
37 */
|
|
|
38
|
|
|
39 #ifndef SDL_touch_h_
|
|
|
40 #define SDL_touch_h_
|
|
|
41
|
|
|
42 #include <SDL3/SDL_stdinc.h>
|
|
|
43 #include <SDL3/SDL_error.h>
|
|
|
44 #include <SDL3/SDL_mouse.h>
|
|
|
45
|
|
|
46 #include <SDL3/SDL_begin_code.h>
|
|
|
47 /* Set up for C function definitions, even when using C++ */
|
|
|
48 #ifdef __cplusplus
|
|
|
49 extern "C" {
|
|
|
50 #endif
|
|
|
51
|
|
|
52 /**
|
|
|
53 * A unique ID for a touch device.
|
|
|
54 *
|
|
|
55 * This ID is valid for the time the device is connected to the system, and is
|
|
|
56 * never reused for the lifetime of the application.
|
|
|
57 *
|
|
|
58 * The value 0 is an invalid ID.
|
|
|
59 *
|
|
|
60 * \since This datatype is available since SDL 3.2.0.
|
|
|
61 */
|
|
|
62 typedef Uint64 SDL_TouchID;
|
|
|
63
|
|
|
64 /**
|
|
|
65 * A unique ID for a single finger on a touch device.
|
|
|
66 *
|
|
|
67 * This ID is valid for the time the finger (stylus, etc) is touching and will
|
|
|
68 * be unique for all fingers currently in contact, so this ID tracks the
|
|
|
69 * lifetime of a single continuous touch. This value may represent an index, a
|
|
|
70 * pointer, or some other unique ID, depending on the platform.
|
|
|
71 *
|
|
|
72 * The value 0 is an invalid ID.
|
|
|
73 *
|
|
|
74 * \since This datatype is available since SDL 3.2.0.
|
|
|
75 */
|
|
|
76 typedef Uint64 SDL_FingerID;
|
|
|
77
|
|
|
78 /**
|
|
|
79 * An enum that describes the type of a touch device.
|
|
|
80 *
|
|
|
81 * \since This enum is available since SDL 3.2.0.
|
|
|
82 */
|
|
|
83 typedef enum SDL_TouchDeviceType
|
|
|
84 {
|
|
|
85 SDL_TOUCH_DEVICE_INVALID = -1,
|
|
|
86 SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */
|
|
|
87 SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */
|
|
|
88 SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */
|
|
|
89 } SDL_TouchDeviceType;
|
|
|
90
|
|
|
91 /**
|
|
|
92 * Data about a single finger in a multitouch event.
|
|
|
93 *
|
|
|
94 * Each touch event is a collection of fingers that are simultaneously in
|
|
|
95 * contact with the touch device (so a "touch" can be a "multitouch," in
|
|
|
96 * reality), and this struct reports details of the specific fingers.
|
|
|
97 *
|
|
|
98 * \since This struct is available since SDL 3.2.0.
|
|
|
99 *
|
|
|
100 * \sa SDL_GetTouchFingers
|
|
|
101 */
|
|
|
102 typedef struct SDL_Finger
|
|
|
103 {
|
|
|
104 SDL_FingerID id; /**< the finger ID */
|
|
|
105 float x; /**< the x-axis location of the touch event, normalized (0...1) */
|
|
|
106 float y; /**< the y-axis location of the touch event, normalized (0...1) */
|
|
|
107 float pressure; /**< the quantity of pressure applied, normalized (0...1) */
|
|
|
108 } SDL_Finger;
|
|
|
109
|
|
|
110 /**
|
|
|
111 * The SDL_MouseID for mouse events simulated with touch input.
|
|
|
112 *
|
|
|
113 * \since This macro is available since SDL 3.2.0.
|
|
|
114 */
|
|
|
115 #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1)
|
|
|
116
|
|
|
117 /**
|
|
|
118 * The SDL_TouchID for touch events simulated with mouse input.
|
|
|
119 *
|
|
|
120 * \since This macro is available since SDL 3.2.0.
|
|
|
121 */
|
|
|
122 #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1)
|
|
|
123
|
|
|
124
|
|
|
125 /**
|
|
|
126 * Get a list of registered touch devices.
|
|
|
127 *
|
|
|
128 * On some platforms SDL first sees the touch device if it was actually used.
|
|
|
129 * Therefore the returned list might be empty, although devices are available.
|
|
|
130 * After using all devices at least once the number will be correct.
|
|
|
131 *
|
|
|
132 * \param count a pointer filled in with the number of devices returned, may
|
|
|
133 * be NULL.
|
|
|
134 * \returns a 0 terminated array of touch device IDs or NULL on failure; call
|
|
|
135 * SDL_GetError() for more information. This should be freed with
|
|
|
136 * SDL_free() when it is no longer needed.
|
|
|
137 *
|
|
|
138 * \since This function is available since SDL 3.2.0.
|
|
|
139 */
|
|
|
140 extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count);
|
|
|
141
|
|
|
142 /**
|
|
|
143 * Get the touch device name as reported from the driver.
|
|
|
144 *
|
|
|
145 * \param touchID the touch device instance ID.
|
|
|
146 * \returns touch device name, or NULL on failure; call SDL_GetError() for
|
|
|
147 * more information.
|
|
|
148 *
|
|
|
149 * \since This function is available since SDL 3.2.0.
|
|
|
150 */
|
|
|
151 extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID);
|
|
|
152
|
|
|
153 /**
|
|
|
154 * Get the type of the given touch device.
|
|
|
155 *
|
|
|
156 * \param touchID the ID of a touch device.
|
|
|
157 * \returns touch device type.
|
|
|
158 *
|
|
|
159 * \since This function is available since SDL 3.2.0.
|
|
|
160 */
|
|
|
161 extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
|
|
|
162
|
|
|
163 /**
|
|
|
164 * Get a list of active fingers for a given touch device.
|
|
|
165 *
|
|
|
166 * \param touchID the ID of a touch device.
|
|
|
167 * \param count a pointer filled in with the number of fingers returned, can
|
|
|
168 * be NULL.
|
|
|
169 * \returns a NULL terminated array of SDL_Finger pointers or NULL on failure;
|
|
|
170 * call SDL_GetError() for more information. This is a single
|
|
|
171 * allocation that should be freed with SDL_free() when it is no
|
|
|
172 * longer needed.
|
|
|
173 *
|
|
|
174 * \since This function is available since SDL 3.2.0.
|
|
|
175 */
|
|
|
176 extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count);
|
|
|
177
|
|
|
178 /* Ends C function definitions when using C++ */
|
|
|
179 #ifdef __cplusplus
|
|
|
180 }
|
|
|
181 #endif
|
|
|
182 #include <SDL3/SDL_close_code.h>
|
|
|
183
|
|
|
184 #endif /* SDL_touch_h_ */
|
