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

sdl3_sys/generated/
sensor.rs
