sdl3_sys/generated/
touch.rs

1//! SDL offers touch input, on platforms that support it. It can manage
2//! multiple touch devices and track multiple fingers on those devices.
3//!
4//! Touches are mostly dealt with through the event system, in the
5//! [`SDL_EVENT_FINGER_DOWN`], [`SDL_EVENT_FINGER_MOTION`], and [`SDL_EVENT_FINGER_UP`]
6//! events, but there are also functions to query for hardware details, etc.
7//!
8//! The touch system, by default, will also send virtual mouse events; this can
9//! be useful for making a some desktop apps work on a phone without
10//! significant changes. For apps that care about mouse and touch input
11//! separately, they should ignore mouse events that have a `which` field of
12//! [`SDL_TOUCH_MOUSEID`].
13
14use super::stdinc::*;
15
16use super::error::*;
17
18use super::mouse::*;
19
20/// A unique ID for a touch device.
21///
22/// This ID is valid for the time the device is connected to the system, and is
23/// never reused for the lifetime of the application.
24///
25/// The value 0 is an invalid ID.
26///
27/// ## Availability
28/// This datatype is available since SDL 3.2.0.
29#[repr(transparent)]
30#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
31#[cfg_attr(feature = "debug-impls", derive(Debug))]
32pub struct SDL_TouchID(pub Uint64);
33
34impl ::core::cmp::PartialEq<Uint64> for SDL_TouchID {
35    #[inline(always)]
36    fn eq(&self, other: &Uint64) -> bool {
37        &self.0 == other
38    }
39}
40
41impl ::core::cmp::PartialEq<SDL_TouchID> for Uint64 {
42    #[inline(always)]
43    fn eq(&self, other: &SDL_TouchID) -> bool {
44        self == &other.0
45    }
46}
47
48impl From<SDL_TouchID> for Uint64 {
49    #[inline(always)]
50    fn from(value: SDL_TouchID) -> Self {
51        value.0
52    }
53}
54
55#[cfg(feature = "display-impls")]
56impl ::core::fmt::Display for SDL_TouchID {
57    #[inline(always)]
58    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
59        <Uint64 as ::core::fmt::Display>::fmt(&self.0, f)
60    }
61}
62
63impl SDL_TouchID {
64    /// Initialize a `SDL_TouchID` from a raw value.
65    #[inline(always)]
66    pub const fn new(value: Uint64) -> Self {
67        Self(value)
68    }
69}
70
71impl SDL_TouchID {
72    /// Get a copy of the inner raw value.
73    #[inline(always)]
74    pub const fn value(&self) -> Uint64 {
75        self.0
76    }
77}
78
79#[cfg(feature = "metadata")]
80impl sdl3_sys::metadata::GroupMetadata for SDL_TouchID {
81    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
82        &crate::metadata::touch::METADATA_SDL_TouchID;
83}
84
85/// A unique ID for a single finger on a touch device.
86///
87/// This ID is valid for the time the finger (stylus, etc) is touching and will
88/// be unique for all fingers currently in contact, so this ID tracks the
89/// lifetime of a single continuous touch. This value may represent an index, a
90/// pointer, or some other unique ID, depending on the platform.
91///
92/// The value 0 is an invalid ID.
93///
94/// ## Availability
95/// This datatype is available since SDL 3.2.0.
96#[repr(transparent)]
97#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
98#[cfg_attr(feature = "debug-impls", derive(Debug))]
99pub struct SDL_FingerID(pub Uint64);
100
101impl ::core::cmp::PartialEq<Uint64> for SDL_FingerID {
102    #[inline(always)]
103    fn eq(&self, other: &Uint64) -> bool {
104        &self.0 == other
105    }
106}
107
108impl ::core::cmp::PartialEq<SDL_FingerID> for Uint64 {
109    #[inline(always)]
110    fn eq(&self, other: &SDL_FingerID) -> bool {
111        self == &other.0
112    }
113}
114
115impl From<SDL_FingerID> for Uint64 {
116    #[inline(always)]
117    fn from(value: SDL_FingerID) -> Self {
118        value.0
119    }
120}
121
122#[cfg(feature = "display-impls")]
123impl ::core::fmt::Display for SDL_FingerID {
124    #[inline(always)]
125    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
126        <Uint64 as ::core::fmt::Display>::fmt(&self.0, f)
127    }
128}
129
130impl SDL_FingerID {
131    /// Initialize a `SDL_FingerID` from a raw value.
132    #[inline(always)]
133    pub const fn new(value: Uint64) -> Self {
134        Self(value)
135    }
136}
137
138impl SDL_FingerID {
139    /// Get a copy of the inner raw value.
140    #[inline(always)]
141    pub const fn value(&self) -> Uint64 {
142        self.0
143    }
144}
145
146#[cfg(feature = "metadata")]
147impl sdl3_sys::metadata::GroupMetadata for SDL_FingerID {
148    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
149        &crate::metadata::touch::METADATA_SDL_FingerID;
150}
151
152/// An enum that describes the type of a touch device.
153///
154/// ## Availability
155/// This enum is available since SDL 3.2.0.
156///
157/// ## Known values (`sdl3-sys`)
158/// | Associated constant | Global constant | Description |
159/// | ------------------- | --------------- | ----------- |
160/// | [`INVALID`](SDL_TouchDeviceType::INVALID) | [`SDL_TOUCH_DEVICE_INVALID`] | |
161/// | [`DIRECT`](SDL_TouchDeviceType::DIRECT) | [`SDL_TOUCH_DEVICE_DIRECT`] | touch screen with window-relative coordinates |
162/// | [`INDIRECT_ABSOLUTE`](SDL_TouchDeviceType::INDIRECT_ABSOLUTE) | [`SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE`] | trackpad with absolute device coordinates |
163/// | [`INDIRECT_RELATIVE`](SDL_TouchDeviceType::INDIRECT_RELATIVE) | [`SDL_TOUCH_DEVICE_INDIRECT_RELATIVE`] | trackpad with screen cursor-relative coordinates |
164#[repr(transparent)]
165#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
166pub struct SDL_TouchDeviceType(pub ::core::ffi::c_int);
167
168impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_TouchDeviceType {
169    #[inline(always)]
170    fn eq(&self, other: &::core::ffi::c_int) -> bool {
171        &self.0 == other
172    }
173}
174
175impl ::core::cmp::PartialEq<SDL_TouchDeviceType> for ::core::ffi::c_int {
176    #[inline(always)]
177    fn eq(&self, other: &SDL_TouchDeviceType) -> bool {
178        self == &other.0
179    }
180}
181
182impl From<SDL_TouchDeviceType> for ::core::ffi::c_int {
183    #[inline(always)]
184    fn from(value: SDL_TouchDeviceType) -> Self {
185        value.0
186    }
187}
188
189#[cfg(feature = "debug-impls")]
190impl ::core::fmt::Debug for SDL_TouchDeviceType {
191    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
192        #[allow(unreachable_patterns)]
193        f.write_str(match *self {
194            Self::INVALID => "SDL_TOUCH_DEVICE_INVALID",
195            Self::DIRECT => "SDL_TOUCH_DEVICE_DIRECT",
196            Self::INDIRECT_ABSOLUTE => "SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE",
197            Self::INDIRECT_RELATIVE => "SDL_TOUCH_DEVICE_INDIRECT_RELATIVE",
198
199            _ => return write!(f, "SDL_TouchDeviceType({})", self.0),
200        })
201    }
202}
203
204impl SDL_TouchDeviceType {
205    pub const INVALID: Self = Self((-1_i32 as ::core::ffi::c_int));
206    /// touch screen with window-relative coordinates
207    pub const DIRECT: Self = Self((0_i32 as ::core::ffi::c_int));
208    /// trackpad with absolute device coordinates
209    pub const INDIRECT_ABSOLUTE: Self = Self((1_i32 as ::core::ffi::c_int));
210    /// trackpad with screen cursor-relative coordinates
211    pub const INDIRECT_RELATIVE: Self = Self((2_i32 as ::core::ffi::c_int));
212}
213
214pub const SDL_TOUCH_DEVICE_INVALID: SDL_TouchDeviceType = SDL_TouchDeviceType::INVALID;
215/// touch screen with window-relative coordinates
216pub const SDL_TOUCH_DEVICE_DIRECT: SDL_TouchDeviceType = SDL_TouchDeviceType::DIRECT;
217/// trackpad with absolute device coordinates
218pub const SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE: SDL_TouchDeviceType =
219    SDL_TouchDeviceType::INDIRECT_ABSOLUTE;
220/// trackpad with screen cursor-relative coordinates
221pub const SDL_TOUCH_DEVICE_INDIRECT_RELATIVE: SDL_TouchDeviceType =
222    SDL_TouchDeviceType::INDIRECT_RELATIVE;
223
224impl SDL_TouchDeviceType {
225    /// Initialize a `SDL_TouchDeviceType` from a raw value.
226    #[inline(always)]
227    pub const fn new(value: ::core::ffi::c_int) -> Self {
228        Self(value)
229    }
230}
231
232impl SDL_TouchDeviceType {
233    /// Get a copy of the inner raw value.
234    #[inline(always)]
235    pub const fn value(&self) -> ::core::ffi::c_int {
236        self.0
237    }
238}
239
240#[cfg(feature = "metadata")]
241impl sdl3_sys::metadata::GroupMetadata for SDL_TouchDeviceType {
242    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
243        &crate::metadata::touch::METADATA_SDL_TouchDeviceType;
244}
245
246/// Data about a single finger in a multitouch event.
247///
248/// Each touch event is a collection of fingers that are simultaneously in
249/// contact with the touch device (so a "touch" can be a "multitouch," in
250/// reality), and this struct reports details of the specific fingers.
251///
252/// ## Availability
253/// This struct is available since SDL 3.2.0.
254///
255/// ## See also
256/// - [`SDL_GetTouchFingers`]
257#[repr(C)]
258#[derive(Clone, Copy, Default, PartialEq)]
259#[cfg_attr(feature = "debug-impls", derive(Debug))]
260pub struct SDL_Finger {
261    /// the finger ID
262    pub id: SDL_FingerID,
263    /// the x-axis location of the touch event, normalized (0...1)
264    pub x: ::core::ffi::c_float,
265    /// the y-axis location of the touch event, normalized (0...1)
266    pub y: ::core::ffi::c_float,
267    /// the quantity of pressure applied, normalized (0...1)
268    pub pressure: ::core::ffi::c_float,
269}
270
271/// The [`SDL_MouseID`] for mouse events simulated with touch input.
272///
273/// ## Availability
274/// This macro is available since SDL 3.2.0.
275pub const SDL_TOUCH_MOUSEID: SDL_MouseID = SDL_MouseID((-1_i32 as Uint32));
276
277/// The [`SDL_TouchID`] for touch events simulated with mouse input.
278///
279/// ## Availability
280/// This macro is available since SDL 3.2.0.
281pub const SDL_MOUSE_TOUCHID: SDL_TouchID = SDL_TouchID((-1_i32 as Uint64));
282
283unsafe extern "C" {
284    /// Get a list of registered touch devices.
285    ///
286    /// On some platforms SDL first sees the touch device if it was actually used.
287    /// Therefore the returned list might be empty, although devices are available.
288    /// After using all devices at least once the number will be correct.
289    ///
290    /// ## Parameters
291    /// - `count`: a pointer filled in with the number of devices returned, may
292    ///   be NULL.
293    ///
294    /// ## Return value
295    /// Returns a 0 terminated array of touch device IDs or NULL on failure; call
296    ///   [`SDL_GetError()`] for more information. This should be freed with
297    ///   [`SDL_free()`] when it is no longer needed.
298    ///
299    /// ## Availability
300    /// This function is available since SDL 3.2.0.
301    pub fn SDL_GetTouchDevices(count: *mut ::core::ffi::c_int) -> *mut SDL_TouchID;
302}
303
304unsafe extern "C" {
305    /// Get the touch device name as reported from the driver.
306    ///
307    /// ## Parameters
308    /// - `touchID`: the touch device instance ID.
309    ///
310    /// ## Return value
311    /// Returns touch device name, or NULL on failure; call [`SDL_GetError()`] for
312    ///   more information.
313    ///
314    /// ## Availability
315    /// This function is available since SDL 3.2.0.
316    pub fn SDL_GetTouchDeviceName(touchID: SDL_TouchID) -> *const ::core::ffi::c_char;
317}
318
319unsafe extern "C" {
320    /// Get the type of the given touch device.
321    ///
322    /// ## Parameters
323    /// - `touchID`: the ID of a touch device.
324    ///
325    /// ## Return value
326    /// Returns touch device type.
327    ///
328    /// ## Availability
329    /// This function is available since SDL 3.2.0.
330    pub fn SDL_GetTouchDeviceType(touchID: SDL_TouchID) -> SDL_TouchDeviceType;
331}
332
333unsafe extern "C" {
334    /// Get a list of active fingers for a given touch device.
335    ///
336    /// ## Parameters
337    /// - `touchID`: the ID of a touch device.
338    /// - `count`: a pointer filled in with the number of fingers returned, can
339    ///   be NULL.
340    ///
341    /// ## Return value
342    /// Returns a NULL terminated array of [`SDL_Finger`] pointers or NULL on failure;
343    ///   call [`SDL_GetError()`] for more information. This is a single
344    ///   allocation that should be freed with [`SDL_free()`] when it is no
345    ///   longer needed.
346    ///
347    /// ## Availability
348    /// This function is available since SDL 3.2.0.
349    pub fn SDL_GetTouchFingers(
350        touchID: SDL_TouchID,
351        count: *mut ::core::ffi::c_int,
352    ) -> *mut *mut SDL_Finger;
353}
354
355#[cfg(doc)]
356use crate::everything::*;
sdl3_sys/generated/touch.rs

sdl3_sys/generated/
touch.rs
