sdl.touch source code

1 /*
2     DSDL
3     Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay>
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     Simple DirectMedia Layer
24     Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
25 
26     This software is provided 'as-is', without any express or implied
27     warranty.  In no event will the authors be held liable for any damages
28     arising from the use of this software.
29 
30     Permission is granted to anyone to use this software for any purpose,
31     including commercial applications, and to alter it and redistribute it
32     freely, subject to the following restrictions:
33 
34     1. The origin of this software must not be misrepresented; you must not
35         claim that you wrote the original software. If you use this software
36         in a product, an acknowledgment in the product documentation would be
37         appreciated but is not required.
38     2. Altered source versions must be plainly marked as such, and must not be
39         misrepresented as being the original software.
40     3. This notice may not be removed or altered from any source distribution.
41 */
42 
43 /**
44     SDL Touch Handling
45 
46     See_Also:
47         $(LINK2 https://wiki.libsdl.org/SDL3/CategoryTouch, SDL3 Touch Documentation)
48     
49     Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga
50     License: Subject to the terms of the Zlib License, as written in the LICENSE file.
51     Authors: 
52         Luna Nielsen
53 */
54 module sdl.touch;
55 import sdl.stdc;
56 import sdl.mouse;
57 
58 extern(C) nothrow @nogc:
59 
60 
61 /**
62     A unique ID for a touch device.
63 
64     This ID is valid for the time the device is connected to the system, and is
65     never reused for the lifetime of the application.
66 
67     The value 0 is an invalid ID.
68 */
69 alias SDL_TouchID = Uint64;
70 
71 /**
72     A unique ID for a single finger on a touch device.
73     
74     This ID is valid for the time the finger (stylus, etc) is touching and will
75     be unique for all fingers currently in contact, so this ID tracks the
76     lifetime of a single continuous touch. This value may represent an index, a
77     pointer, or some other unique ID, depending on the platform.
78     
79     The value 0 is an invalid ID.
80 */
81 alias SDL_FingerID = Uint64;
82 
83 
84 /**
85     An enum that describes the type of a touch device.
86 */
87 enum SDL_TouchDeviceType {
88 
89     /**
90         Invalid
91     */
92     SDL_TOUCH_DEVICE_INVALID = -1,
93 
94     /**
95         Touch screen with window-relative coordinates
96     */
97     SDL_TOUCH_DEVICE_DIRECT,
98 
99     /**
100         Trackpad with absolute device coordinates
101     */
102     SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE,
103 
104     /**
105         Trackpad with screen cursor-relative coordinates
106     */
107     SDL_TOUCH_DEVICE_INDIRECT_RELATIVE
108 }
109 
110 /**
111     Data about a single finger in a multitouch event.
112 
113     Each touch event is a collection of fingers that are simultaneously in
114     contact with the touch device (so a "touch" can be a "multitouch," in
115     reality), and this struct reports details of the specific fingers.
116 
117     See_Also:
118         $(D SDL_GetTouchFingers)
119 */
120 struct SDL_Finger {
121     
122     /**
123         The finger ID
124     */
125     SDL_FingerID id;
126     
127     /**
128         The x-axis location of the touch event, normalized (0...1)
129     */
130     float x;
131     
132     /**
133         The y-axis location of the touch event, normalized (0...1)
134     */
135     float y;
136     
137     /**
138         The quantity of pressure applied, normalized (0...1)
139     */
140     float pressure;
141 }
142 
143 /**
144     The SDL_MouseID for mouse events simulated with touch input.
145 */
146 enum SDL_MouseID SDL_TOUCH_MOUSEID = -1;
147 
148 /**
149     The SDL_TouchID for touch events simulated with mouse input.
150 */
151 enum SDL_TouchID SDL_MOUSE_TOUCHID = -1;
152 
153 
154 /**
155     Get a list of registered touch devices.
156 
157     On some platforms SDL first sees the touch device if it was actually used.
158     Therefore the returned list might be empty, although devices are available.
159     After using all devices at least once the number will be correct.
160 
161     Params:
162         count = a pointer filled in with the number of devices returned, may
163                 be $(D null).
164 
165     Returns:
166         a null-terminated array of touch device IDs or $(D null) on failure; call
167         $(D SDL_GetError) for more information. This should be freed with
168         $(D SDL_free) when it is no longer needed.
169 */
170 extern SDL_TouchID* SDL_GetTouchDevices(int* count);
171 
172 /**
173     Get the touch device name as reported from the driver.
174 
175     Params:
176         touchID = the touch device instance ID.
177     
178     Returns:
179         touch device name, or $(D null) on failure; call $(D SDL_GetError) for
180         more information.
181 */
182 extern const(char)* SDL_GetTouchDeviceName(SDL_TouchID touchID);
183 
184 /**
185     Get the type of the given touch device.
186 
187     Params:
188         touchID = the ID of a touch device.
189 
190     Returns:
191         Touch device type.
192 */
193 extern SDL_TouchDeviceType SDL_GetTouchDeviceType(SDL_TouchID touchID);
194 
195 /**
196     Get a list of active fingers for a given touch device.
197 
198     Params:
199         touchID =   the ID of a touch device.
200         count =     a pointer filled in with the number of fingers returned, can
201                     be $(D null).
202 
203     Returns:
204         A $(D null) terminated array of SDL_Finger pointers or $(D null) on failure;
205         call $(D SDL_GetError) for more information. This is a single
206         allocation that should be freed with $(D SDL_free) when it is no
207         longer needed.
208 */
209 extern SDL_Finger** SDL_GetTouchFingers(SDL_TouchID touchID, int* count);