sdl3_sys/generated/
sensor.rs

1//! SDL sensor management.
2//!
3//! These APIs grant access to gyros and accelerometers on various platforms.
4//!
5//! In order to use these functions, [`SDL_Init()`] must have been called with the
6//! [`SDL_INIT_SENSOR`] flag. This causes SDL to scan the system for sensors, and
7//! load appropriate drivers.
8
9use super::stdinc::*;
10
11use super::error::*;
12
13use super::properties::*;
14
15/// This is a unique ID for a sensor for the time it is connected to the
16/// system, and is never reused for the lifetime of the application.
17///
18/// The value 0 is an invalid ID.
19///
20/// ## Availability
21/// This datatype is available since SDL 3.2.0.
22#[repr(transparent)]
23#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
24#[cfg_attr(feature = "debug-impls", derive(Debug))]
25pub struct SDL_SensorID(pub Uint32);
26
27impl ::core::cmp::PartialEq<Uint32> for SDL_SensorID {
28    #[inline(always)]
29    fn eq(&self, other: &Uint32) -> bool {
30        &self.0 == other
31    }
32}
33
34impl ::core::cmp::PartialEq<SDL_SensorID> for Uint32 {
35    #[inline(always)]
36    fn eq(&self, other: &SDL_SensorID) -> bool {
37        self == &other.0
38    }
39}
40
41impl From<SDL_SensorID> for Uint32 {
42    #[inline(always)]
43    fn from(value: SDL_SensorID) -> Self {
44        value.0
45    }
46}
47
48#[cfg(feature = "metadata")]
49impl sdl3_sys::metadata::GroupMetadata for SDL_SensorID {
50    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
51        &crate::metadata::sensor::METADATA_SDL_SensorID;
52}
53
54/// A constant to represent standard gravity for accelerometer sensors.
55///
56/// The accelerometer returns the current acceleration in SI meters per second
57/// squared. This measurement includes the force of gravity, so a device at
58/// rest will have an value of [`SDL_STANDARD_GRAVITY`] away from the center of the
59/// earth, which is a positive Y value.
60///
61/// ## Availability
62/// This macro is available since SDL 3.2.0.
63pub const SDL_STANDARD_GRAVITY: ::core::ffi::c_float = 9.80665_f32;
64
65/// The different sensors defined by SDL.
66///
67/// Additional sensors may be available, using platform dependent semantics.
68///
69/// Here are the additional Android sensors:
70///
71/// <https://developer.android.com/reference/android/hardware/SensorEvent.html#values>
72///
73/// Accelerometer sensor notes:
74///
75/// The accelerometer returns the current acceleration in SI meters per second
76/// squared. This measurement includes the force of gravity, so a device at
77/// rest will have an value of [`SDL_STANDARD_GRAVITY`] away from the center of the
78/// earth, which is a positive Y value.
79///
80/// - `values[0]`: Acceleration on the x axis
81/// - `values[1]`: Acceleration on the y axis
82/// - `values[2]`: Acceleration on the z axis
83///
84/// For phones and tablets held in natural orientation and game controllers
85/// held in front of you, the axes are defined as follows:
86///
87/// - -X ... +X : left ... right
88/// - -Y ... +Y : bottom ... top
89/// - -Z ... +Z : farther ... closer
90///
91/// The accelerometer axis data is not changed when the device is rotated.
92///
93/// Gyroscope sensor notes:
94///
95/// The gyroscope returns the current rate of rotation in radians per second.
96/// The rotation is positive in the counter-clockwise direction. That is, an
97/// observer looking from a positive location on one of the axes would see
98/// positive rotation on that axis when it appeared to be rotating
99/// counter-clockwise.
100///
101/// - `values[0]`: Angular speed around the x axis (pitch)
102/// - `values[1]`: Angular speed around the y axis (yaw)
103/// - `values[2]`: Angular speed around the z axis (roll)
104///
105/// For phones and tablets held in natural orientation and game controllers
106/// held in front of you, the axes are defined as follows:
107///
108/// - -X ... +X : left ... right
109/// - -Y ... +Y : bottom ... top
110/// - -Z ... +Z : farther ... closer
111///
112/// The gyroscope axis data is not changed when the device is rotated.
113///
114/// ## Availability
115/// This enum is available since SDL 3.2.0.
116///
117/// ## See also
118/// - [`SDL_GetCurrentDisplayOrientation`]
119///
120/// ## Known values (`sdl3-sys`)
121/// | Associated constant | Global constant | Description |
122/// | ------------------- | --------------- | ----------- |
123/// | [`INVALID`](SDL_SensorType::INVALID) | [`SDL_SENSOR_INVALID`] | Returned for an invalid sensor |
124/// | [`UNKNOWN`](SDL_SensorType::UNKNOWN) | [`SDL_SENSOR_UNKNOWN`] | Unknown sensor type |
125/// | [`ACCEL`](SDL_SensorType::ACCEL) | [`SDL_SENSOR_ACCEL`] | Accelerometer |
126/// | [`GYRO`](SDL_SensorType::GYRO) | [`SDL_SENSOR_GYRO`] | Gyroscope |
127/// | [`ACCEL_L`](SDL_SensorType::ACCEL_L) | [`SDL_SENSOR_ACCEL_L`] | Accelerometer for left Joy-Con controller and Wii nunchuk |
128/// | [`GYRO_L`](SDL_SensorType::GYRO_L) | [`SDL_SENSOR_GYRO_L`] | Gyroscope for left Joy-Con controller |
129/// | [`ACCEL_R`](SDL_SensorType::ACCEL_R) | [`SDL_SENSOR_ACCEL_R`] | Accelerometer for right Joy-Con controller |
130/// | [`GYRO_R`](SDL_SensorType::GYRO_R) | [`SDL_SENSOR_GYRO_R`] | Gyroscope for right Joy-Con controller |
131/// | [`COUNT`](SDL_SensorType::COUNT) | [`SDL_SENSOR_COUNT`] | |
132#[repr(transparent)]
133#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
134pub struct SDL_SensorType(pub ::core::ffi::c_int);
135
136impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_SensorType {
137    #[inline(always)]
138    fn eq(&self, other: &::core::ffi::c_int) -> bool {
139        &self.0 == other
140    }
141}
142
143impl ::core::cmp::PartialEq<SDL_SensorType> for ::core::ffi::c_int {
144    #[inline(always)]
145    fn eq(&self, other: &SDL_SensorType) -> bool {
146        self == &other.0
147    }
148}
149
150impl From<SDL_SensorType> for ::core::ffi::c_int {
151    #[inline(always)]
152    fn from(value: SDL_SensorType) -> Self {
153        value.0
154    }
155}
156
157#[cfg(feature = "debug-impls")]
158impl ::core::fmt::Debug for SDL_SensorType {
159    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
160        #[allow(unreachable_patterns)]
161        f.write_str(match *self {
162            Self::INVALID => "SDL_SENSOR_INVALID",
163            Self::UNKNOWN => "SDL_SENSOR_UNKNOWN",
164            Self::ACCEL => "SDL_SENSOR_ACCEL",
165            Self::GYRO => "SDL_SENSOR_GYRO",
166            Self::ACCEL_L => "SDL_SENSOR_ACCEL_L",
167            Self::GYRO_L => "SDL_SENSOR_GYRO_L",
168            Self::ACCEL_R => "SDL_SENSOR_ACCEL_R",
169            Self::GYRO_R => "SDL_SENSOR_GYRO_R",
170            Self::COUNT => "SDL_SENSOR_COUNT",
171
172            _ => return write!(f, "SDL_SensorType({})", self.0),
173        })
174    }
175}
176
177impl SDL_SensorType {
178    /// Returned for an invalid sensor
179    pub const INVALID: Self = Self((-1_i32 as ::core::ffi::c_int));
180    /// Unknown sensor type
181    pub const UNKNOWN: Self = Self((0_i32 as ::core::ffi::c_int));
182    /// Accelerometer
183    pub const ACCEL: Self = Self((1_i32 as ::core::ffi::c_int));
184    /// Gyroscope
185    pub const GYRO: Self = Self((2_i32 as ::core::ffi::c_int));
186    /// Accelerometer for left Joy-Con controller and Wii nunchuk
187    pub const ACCEL_L: Self = Self((3_i32 as ::core::ffi::c_int));
188    /// Gyroscope for left Joy-Con controller
189    pub const GYRO_L: Self = Self((4_i32 as ::core::ffi::c_int));
190    /// Accelerometer for right Joy-Con controller
191    pub const ACCEL_R: Self = Self((5_i32 as ::core::ffi::c_int));
192    /// Gyroscope for right Joy-Con controller
193    pub const GYRO_R: Self = Self((6_i32 as ::core::ffi::c_int));
194    pub const COUNT: Self = Self((7_i32 as ::core::ffi::c_int));
195}
196
197/// Returned for an invalid sensor
198pub const SDL_SENSOR_INVALID: SDL_SensorType = SDL_SensorType::INVALID;
199/// Unknown sensor type
200pub const SDL_SENSOR_UNKNOWN: SDL_SensorType = SDL_SensorType::UNKNOWN;
201/// Accelerometer
202pub const SDL_SENSOR_ACCEL: SDL_SensorType = SDL_SensorType::ACCEL;
203/// Gyroscope
204pub const SDL_SENSOR_GYRO: SDL_SensorType = SDL_SensorType::GYRO;
205/// Accelerometer for left Joy-Con controller and Wii nunchuk
206pub const SDL_SENSOR_ACCEL_L: SDL_SensorType = SDL_SensorType::ACCEL_L;
207/// Gyroscope for left Joy-Con controller
208pub const SDL_SENSOR_GYRO_L: SDL_SensorType = SDL_SensorType::GYRO_L;
209/// Accelerometer for right Joy-Con controller
210pub const SDL_SENSOR_ACCEL_R: SDL_SensorType = SDL_SensorType::ACCEL_R;
211/// Gyroscope for right Joy-Con controller
212pub const SDL_SENSOR_GYRO_R: SDL_SensorType = SDL_SensorType::GYRO_R;
213pub const SDL_SENSOR_COUNT: SDL_SensorType = SDL_SensorType::COUNT;
214
215#[cfg(feature = "metadata")]
216impl sdl3_sys::metadata::GroupMetadata for SDL_SensorType {
217    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
218        &crate::metadata::sensor::METADATA_SDL_SensorType;
219}
220
221unsafe extern "C" {
222    /// Get a list of currently connected sensors.
223    ///
224    /// ## Parameters
225    /// - `count`: a pointer filled in with the number of sensors returned, may
226    ///   be NULL.
227    ///
228    /// ## Return value
229    /// Returns a 0 terminated array of sensor instance IDs or NULL on failure;
230    ///   call [`SDL_GetError()`] for more information. This should be freed
231    ///   with [`SDL_free()`] when it is no longer needed.
232    ///
233    /// ## Availability
234    /// This function is available since SDL 3.2.0.
235    pub fn SDL_GetSensors(count: *mut ::core::ffi::c_int) -> *mut SDL_SensorID;
236}
237
238unsafe extern "C" {
239    /// Get the implementation dependent name of a sensor.
240    ///
241    /// This can be called before any sensors are opened.
242    ///
243    /// ## Parameters
244    /// - `instance_id`: the sensor instance ID.
245    ///
246    /// ## Return value
247    /// Returns the sensor name, or NULL if `instance_id` is not valid.
248    ///
249    /// ## Availability
250    /// This function is available since SDL 3.2.0.
251    pub fn SDL_GetSensorNameForID(instance_id: SDL_SensorID) -> *const ::core::ffi::c_char;
252}
253
254unsafe extern "C" {
255    /// Get the type of a sensor.
256    ///
257    /// This can be called before any sensors are opened.
258    ///
259    /// ## Parameters
260    /// - `instance_id`: the sensor instance ID.
261    ///
262    /// ## Return value
263    /// Returns the [`SDL_SensorType`], or [`SDL_SENSOR_INVALID`] if `instance_id` is
264    ///   not valid.
265    ///
266    /// ## Availability
267    /// This function is available since SDL 3.2.0.
268    pub fn SDL_GetSensorTypeForID(instance_id: SDL_SensorID) -> SDL_SensorType;
269}
270
271unsafe extern "C" {
272    /// Get the platform dependent type of a sensor.
273    ///
274    /// This can be called before any sensors are opened.
275    ///
276    /// ## Parameters
277    /// - `instance_id`: the sensor instance ID.
278    ///
279    /// ## Return value
280    /// Returns the sensor platform dependent type, or -1 if `instance_id` is not
281    ///   valid.
282    ///
283    /// ## Availability
284    /// This function is available since SDL 3.2.0.
285    pub fn SDL_GetSensorNonPortableTypeForID(instance_id: SDL_SensorID) -> ::core::ffi::c_int;
286}
287
288unsafe extern "C" {
289    /// Open a sensor for use.
290    ///
291    /// ## Parameters
292    /// - `instance_id`: the sensor instance ID.
293    ///
294    /// ## Return value
295    /// Returns an [`SDL_Sensor`] object or NULL on failure; call [`SDL_GetError()`] for
296    ///   more information.
297    ///
298    /// ## Availability
299    /// This function is available since SDL 3.2.0.
300    pub fn SDL_OpenSensor(instance_id: SDL_SensorID) -> *mut SDL_Sensor;
301}
302
303unsafe extern "C" {
304    /// Return the [`SDL_Sensor`] associated with an instance ID.
305    ///
306    /// ## Parameters
307    /// - `instance_id`: the sensor instance ID.
308    ///
309    /// ## Return value
310    /// Returns an [`SDL_Sensor`] object or NULL on failure; call [`SDL_GetError()`] for
311    ///   more information.
312    ///
313    /// ## Availability
314    /// This function is available since SDL 3.2.0.
315    pub fn SDL_GetSensorFromID(instance_id: SDL_SensorID) -> *mut SDL_Sensor;
316}
317
318unsafe extern "C" {
319    /// Get the properties associated with a sensor.
320    ///
321    /// ## Parameters
322    /// - `sensor`: the [`SDL_Sensor`] object.
323    ///
324    /// ## Return value
325    /// Returns a valid property ID on success or 0 on failure; call
326    ///   [`SDL_GetError()`] for more information.
327    ///
328    /// ## Availability
329    /// This function is available since SDL 3.2.0.
330    pub fn SDL_GetSensorProperties(sensor: *mut SDL_Sensor) -> SDL_PropertiesID;
331}
332
333unsafe extern "C" {
334    /// Get the implementation dependent name of a sensor.
335    ///
336    /// ## Parameters
337    /// - `sensor`: the [`SDL_Sensor`] object.
338    ///
339    /// ## Return value
340    /// Returns the sensor name or NULL on failure; call [`SDL_GetError()`] for more
341    ///   information.
342    ///
343    /// ## Availability
344    /// This function is available since SDL 3.2.0.
345    pub fn SDL_GetSensorName(sensor: *mut SDL_Sensor) -> *const ::core::ffi::c_char;
346}
347
348unsafe extern "C" {
349    /// Get the type of a sensor.
350    ///
351    /// ## Parameters
352    /// - `sensor`: the [`SDL_Sensor`] object to inspect.
353    ///
354    /// ## Return value
355    /// Returns the [`SDL_SensorType`] type, or [`SDL_SENSOR_INVALID`] if `sensor` is
356    ///   NULL.
357    ///
358    /// ## Availability
359    /// This function is available since SDL 3.2.0.
360    pub fn SDL_GetSensorType(sensor: *mut SDL_Sensor) -> SDL_SensorType;
361}
362
363unsafe extern "C" {
364    /// Get the platform dependent type of a sensor.
365    ///
366    /// ## Parameters
367    /// - `sensor`: the [`SDL_Sensor`] object to inspect.
368    ///
369    /// ## Return value
370    /// Returns the sensor platform dependent type, or -1 if `sensor` is NULL.
371    ///
372    /// ## Availability
373    /// This function is available since SDL 3.2.0.
374    pub fn SDL_GetSensorNonPortableType(sensor: *mut SDL_Sensor) -> ::core::ffi::c_int;
375}
376
377unsafe extern "C" {
378    /// Get the instance ID of a sensor.
379    ///
380    /// ## Parameters
381    /// - `sensor`: the [`SDL_Sensor`] object to inspect.
382    ///
383    /// ## Return value
384    /// Returns the sensor instance ID, or 0 on failure; call [`SDL_GetError()`] for
385    ///   more information.
386    ///
387    /// ## Availability
388    /// This function is available since SDL 3.2.0.
389    pub fn SDL_GetSensorID(sensor: *mut SDL_Sensor) -> SDL_SensorID;
390}
391
392unsafe extern "C" {
393    /// Get the current state of an opened sensor.
394    ///
395    /// The number of values and interpretation of the data is sensor dependent.
396    ///
397    /// ## Parameters
398    /// - `sensor`: the [`SDL_Sensor`] object to query.
399    /// - `data`: a pointer filled with the current sensor state.
400    /// - `num_values`: the number of values to write to data.
401    ///
402    /// ## Return value
403    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
404    ///   information.
405    ///
406    /// ## Availability
407    /// This function is available since SDL 3.2.0.
408    pub fn SDL_GetSensorData(
409        sensor: *mut SDL_Sensor,
410        data: *mut ::core::ffi::c_float,
411        num_values: ::core::ffi::c_int,
412    ) -> ::core::primitive::bool;
413}
414
415unsafe extern "C" {
416    /// Close a sensor previously opened with [`SDL_OpenSensor()`].
417    ///
418    /// ## Parameters
419    /// - `sensor`: the [`SDL_Sensor`] object to close.
420    ///
421    /// ## Availability
422    /// This function is available since SDL 3.2.0.
423    pub fn SDL_CloseSensor(sensor: *mut SDL_Sensor);
424}
425
426unsafe extern "C" {
427    /// Update the current state of the open sensors.
428    ///
429    /// This is called automatically by the event loop if sensor events are
430    /// enabled.
431    ///
432    /// This needs to be called from the thread that initialized the sensor
433    /// subsystem.
434    ///
435    /// ## Availability
436    /// This function is available since SDL 3.2.0.
437    pub fn SDL_UpdateSensors();
438}
439
440/// The opaque structure used to identify an opened SDL sensor.
441///
442/// ## Availability
443/// This struct is available since SDL 3.2.0.
444#[repr(C)]
445pub struct SDL_Sensor {
446    _opaque: [::core::primitive::u8; 0],
447}
448
449#[cfg(doc)]
450use crate::everything::*;
sdl3_sys/generated/sensor.rs

sdl3_sys/generated/
sensor.rs
