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 = "metadata")]
56impl sdl3_sys::metadata::GroupMetadata for SDL_TouchID {
57    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
58        &crate::metadata::touch::METADATA_SDL_TouchID;
59}
60
61/// A unique ID for a single finger on a touch device.
62///
63/// This ID is valid for the time the finger (stylus, etc) is touching and will
64/// be unique for all fingers currently in contact, so this ID tracks the
65/// lifetime of a single continuous touch. This value may represent an index, a
66/// pointer, or some other unique ID, depending on the platform.
67///
68/// The value 0 is an invalid ID.
69///
70/// ## Availability
71/// This datatype is available since SDL 3.2.0.
72#[repr(transparent)]
73#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
74#[cfg_attr(feature = "debug-impls", derive(Debug))]
75pub struct SDL_FingerID(pub Uint64);
76
77impl ::core::cmp::PartialEq<Uint64> for SDL_FingerID {
78    #[inline(always)]
79    fn eq(&self, other: &Uint64) -> bool {
80        &self.0 == other
81    }
82}
83
84impl ::core::cmp::PartialEq<SDL_FingerID> for Uint64 {
85    #[inline(always)]
86    fn eq(&self, other: &SDL_FingerID) -> bool {
87        self == &other.0
88    }
89}
90
91impl From<SDL_FingerID> for Uint64 {
92    #[inline(always)]
93    fn from(value: SDL_FingerID) -> Self {
94        value.0
95    }
96}
97
98#[cfg(feature = "metadata")]
99impl sdl3_sys::metadata::GroupMetadata for SDL_FingerID {
100    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
101        &crate::metadata::touch::METADATA_SDL_FingerID;
102}
103
104/// An enum that describes the type of a touch device.
105///
106/// ## Availability
107/// This enum is available since SDL 3.2.0.
108///
109/// ## Known values (`sdl3-sys`)
110/// | Associated constant | Global constant | Description |
111/// | ------------------- | --------------- | ----------- |
112/// | [`INVALID`](SDL_TouchDeviceType::INVALID) | [`SDL_TOUCH_DEVICE_INVALID`] | |
113/// | [`DIRECT`](SDL_TouchDeviceType::DIRECT) | [`SDL_TOUCH_DEVICE_DIRECT`] | touch screen with window-relative coordinates |
114/// | [`INDIRECT_ABSOLUTE`](SDL_TouchDeviceType::INDIRECT_ABSOLUTE) | [`SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE`] | trackpad with absolute device coordinates |
115/// | [`INDIRECT_RELATIVE`](SDL_TouchDeviceType::INDIRECT_RELATIVE) | [`SDL_TOUCH_DEVICE_INDIRECT_RELATIVE`] | trackpad with screen cursor-relative coordinates |
116#[repr(transparent)]
117#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
118pub struct SDL_TouchDeviceType(pub ::core::ffi::c_int);
119
120impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_TouchDeviceType {
121    #[inline(always)]
122    fn eq(&self, other: &::core::ffi::c_int) -> bool {
123        &self.0 == other
124    }
125}
126
127impl ::core::cmp::PartialEq<SDL_TouchDeviceType> for ::core::ffi::c_int {
128    #[inline(always)]
129    fn eq(&self, other: &SDL_TouchDeviceType) -> bool {
130        self == &other.0
131    }
132}
133
134impl From<SDL_TouchDeviceType> for ::core::ffi::c_int {
135    #[inline(always)]
136    fn from(value: SDL_TouchDeviceType) -> Self {
137        value.0
138    }
139}
140
141#[cfg(feature = "debug-impls")]
142impl ::core::fmt::Debug for SDL_TouchDeviceType {
143    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
144        #[allow(unreachable_patterns)]
145        f.write_str(match *self {
146            Self::INVALID => "SDL_TOUCH_DEVICE_INVALID",
147            Self::DIRECT => "SDL_TOUCH_DEVICE_DIRECT",
148            Self::INDIRECT_ABSOLUTE => "SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE",
149            Self::INDIRECT_RELATIVE => "SDL_TOUCH_DEVICE_INDIRECT_RELATIVE",
150
151            _ => return write!(f, "SDL_TouchDeviceType({})", self.0),
152        })
153    }
154}
155
156impl SDL_TouchDeviceType {
157    pub const INVALID: Self = Self((-1_i32 as ::core::ffi::c_int));
158    /// touch screen with window-relative coordinates
159    pub const DIRECT: Self = Self((0_i32 as ::core::ffi::c_int));
160    /// trackpad with absolute device coordinates
161    pub const INDIRECT_ABSOLUTE: Self = Self((1_i32 as ::core::ffi::c_int));
162    /// trackpad with screen cursor-relative coordinates
163    pub const INDIRECT_RELATIVE: Self = Self((2_i32 as ::core::ffi::c_int));
164}
165
166pub const SDL_TOUCH_DEVICE_INVALID: SDL_TouchDeviceType = SDL_TouchDeviceType::INVALID;
167/// touch screen with window-relative coordinates
168pub const SDL_TOUCH_DEVICE_DIRECT: SDL_TouchDeviceType = SDL_TouchDeviceType::DIRECT;
169/// trackpad with absolute device coordinates
170pub const SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE: SDL_TouchDeviceType =
171    SDL_TouchDeviceType::INDIRECT_ABSOLUTE;
172/// trackpad with screen cursor-relative coordinates
173pub const SDL_TOUCH_DEVICE_INDIRECT_RELATIVE: SDL_TouchDeviceType =
174    SDL_TouchDeviceType::INDIRECT_RELATIVE;
175
176#[cfg(feature = "metadata")]
177impl sdl3_sys::metadata::GroupMetadata for SDL_TouchDeviceType {
178    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
179        &crate::metadata::touch::METADATA_SDL_TouchDeviceType;
180}
181
182/// Data about a single finger in a multitouch event.
183///
184/// Each touch event is a collection of fingers that are simultaneously in
185/// contact with the touch device (so a "touch" can be a "multitouch," in
186/// reality), and this struct reports details of the specific fingers.
187///
188/// ## Availability
189/// This struct is available since SDL 3.2.0.
190///
191/// ## See also
192/// - [`SDL_GetTouchFingers`]
193#[repr(C)]
194#[derive(Clone, Copy, Default, PartialEq)]
195#[cfg_attr(feature = "debug-impls", derive(Debug))]
196pub struct SDL_Finger {
197    /// the finger ID
198    pub id: SDL_FingerID,
199    /// the x-axis location of the touch event, normalized (0...1)
200    pub x: ::core::ffi::c_float,
201    /// the y-axis location of the touch event, normalized (0...1)
202    pub y: ::core::ffi::c_float,
203    /// the quantity of pressure applied, normalized (0...1)
204    pub pressure: ::core::ffi::c_float,
205}
206
207/// The [`SDL_MouseID`] for mouse events simulated with touch input.
208///
209/// ## Availability
210/// This macro is available since SDL 3.2.0.
211pub const SDL_TOUCH_MOUSEID: SDL_MouseID = SDL_MouseID((-1_i32 as Uint32));
212
213/// The [`SDL_TouchID`] for touch events simulated with mouse input.
214///
215/// ## Availability
216/// This macro is available since SDL 3.2.0.
217pub const SDL_MOUSE_TOUCHID: SDL_TouchID = SDL_TouchID((-1_i32 as Uint64));
218
219unsafe extern "C" {
220    /// Get a list of registered touch devices.
221    ///
222    /// On some platforms SDL first sees the touch device if it was actually used.
223    /// Therefore the returned list might be empty, although devices are available.
224    /// After using all devices at least once the number will be correct.
225    ///
226    /// ## Parameters
227    /// - `count`: a pointer filled in with the number of devices returned, may
228    ///   be NULL.
229    ///
230    /// ## Return value
231    /// Returns a 0 terminated array of touch device IDs or NULL on failure; call
232    ///   [`SDL_GetError()`] for more information. This should be freed with
233    ///   [`SDL_free()`] when it is no longer needed.
234    ///
235    /// ## Availability
236    /// This function is available since SDL 3.2.0.
237    pub fn SDL_GetTouchDevices(count: *mut ::core::ffi::c_int) -> *mut SDL_TouchID;
238}
239
240unsafe extern "C" {
241    /// Get the touch device name as reported from the driver.
242    ///
243    /// ## Parameters
244    /// - `touchID`: the touch device instance ID.
245    ///
246    /// ## Return value
247    /// Returns touch device name, or NULL on failure; call [`SDL_GetError()`] for
248    ///   more information.
249    ///
250    /// ## Availability
251    /// This function is available since SDL 3.2.0.
252    pub fn SDL_GetTouchDeviceName(touchID: SDL_TouchID) -> *const ::core::ffi::c_char;
253}
254
255unsafe extern "C" {
256    /// Get the type of the given touch device.
257    ///
258    /// ## Parameters
259    /// - `touchID`: the ID of a touch device.
260    ///
261    /// ## Return value
262    /// Returns touch device type.
263    ///
264    /// ## Availability
265    /// This function is available since SDL 3.2.0.
266    pub fn SDL_GetTouchDeviceType(touchID: SDL_TouchID) -> SDL_TouchDeviceType;
267}
268
269unsafe extern "C" {
270    /// Get a list of active fingers for a given touch device.
271    ///
272    /// ## Parameters
273    /// - `touchID`: the ID of a touch device.
274    /// - `count`: a pointer filled in with the number of fingers returned, can
275    ///   be NULL.
276    ///
277    /// ## Return value
278    /// Returns a NULL terminated array of [`SDL_Finger`] pointers or NULL on failure;
279    ///   call [`SDL_GetError()`] for more information. This is a single
280    ///   allocation that should be freed with [`SDL_free()`] when it is no
281    ///   longer needed.
282    ///
283    /// ## Availability
284    /// This function is available since SDL 3.2.0.
285    pub fn SDL_GetTouchFingers(
286        touchID: SDL_TouchID,
287        count: *mut ::core::ffi::c_int,
288    ) -> *mut *mut SDL_Finger;
289}
290
291#[cfg(doc)]
292use crate::everything::*;
sdl3_sys/generated/touch.rs

sdl3_sys/generated/
touch.rs
