fermium/
sensor.rs

1//! Lets SDL use various sensors (such as the accelerometer in a phone).
2//!
3//! [`SDL_Init`] must have been called with the [`SDL_INIT_SENSOR`] flag. This
4//! causes SDL to scan the system for sensors, and load appropriate drivers.
5
6use crate::{c_char, c_float, c_int, c_void, stdinc::*};
7
8// makes rustdoc link properly!
9#[allow(unused)]
10use crate::video::*;
11#[allow(unused)]
12use crate::*;
13
14/// SDL's opaque sensor type.
15#[repr(transparent)]
16pub struct SDL_Sensor(c_void);
17
18/// This is a unique ID for a sensor for the time it is connected to the system.
19///
20/// It is never reused for the lifetime of the application.
21///
22/// The ID value starts at 0 and increments from there. The value -1 is an
23/// invalid ID.
24#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
25#[repr(transparent)]
26pub struct SDL_SensorID(pub Sint32);
27
28/// The different sensors defined by SDL
29///
30/// Additional sensors may be available, using platform-dependent semantics.
31///
32/// Hare are the additional Android sensors:
33/// <https://developer.android.com/reference/android/hardware/SensorEvent.html#values>
34#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
35#[repr(transparent)]
36pub struct SDL_SensorType(pub i32);
37
38/// Returned for an invalid sensor
39pub const SDL_SENSOR_INVALID: SDL_SensorType = SDL_SensorType(-1);
40/// Unknown sensor type
41pub const SDL_SENSOR_UNKNOWN: SDL_SensorType = SDL_SensorType(0);
42/// Accelerometer
43pub const SDL_SENSOR_ACCEL: SDL_SensorType = SDL_SensorType(1);
44/// Gyroscope
45pub const SDL_SENSOR_GYRO: SDL_SensorType = SDL_SensorType(2);
46
47/// Accelerometer sensor
48///
49/// The accelerometer returns the current acceleration in SI meters per
50/// second squared. This measurement includes the force of gravity, so
51/// a device at rest will have an value of `SDL_STANDARD_GRAVITY` away
52/// from the center of the earth.
53///
54/// * `values[0]`: Acceleration on the x axis
55/// * `values[1]`: Acceleration on the y axis
56/// * `values[2]`: Acceleration on the z axis
57///
58/// For phones held in portrait mode and game controllers held in front of you,
59/// the axes are defined as follows:
60/// * -X ... +X : left ... right
61/// * -Y ... +Y : bottom ... top
62/// * -Z ... +Z : farther ... closer
63///
64/// The axis data is not changed when the phone is rotated.
65///
66/// See Also: [`SDL_GetDisplayOrientation`]
67pub const SDL_STANDARD_GRAVITY: c_float = 9.80665;
68
69extern "C" {
70  /// Locking for multi-threaded access to the sensor API.
71  ///
72  /// If you are using the sensor API or handling events from multiple threads
73  /// you should use these locking functions to protect access to the sensors.
74  ///
75  /// In particular, you are guaranteed that the sensor list won't change, so
76  /// the API functions that take a sensor index will be valid, and sensor
77  /// events will not be delivered.
78  pub fn SDL_LockSensors() -> c_int;
79
80  /// Reverse of [`SDL_LockSensors`].
81  pub fn SDL_UnlockSensors() -> c_int;
82
83  /// Count the number of sensors attached to the system right now.
84  pub fn SDL_NumSensors() -> c_int;
85
86  /// Get the implementation dependent name of a sensor.
87  ///
88  /// This can be called before any sensors are opened.
89  ///
90  /// **Returns:** The sensor name, or NULL if `device_index` is out of range.
91  pub fn SDL_SensorGetDeviceName(device_index: c_int) -> *const c_char;
92
93  /// Get the type of a sensor.
94  ///
95  /// This can be called before any sensors are opened.
96  ///
97  /// **Returns:** The sensor type, or `SDL_SENSOR_INVALID` if device_index is
98  /// out of range.
99  pub fn SDL_SensorGetDeviceType(device_index: c_int) -> SDL_SensorType;
100
101  /// Get the platform dependent type of a sensor.
102  ///
103  /// This can be called before any sensors are opened.
104  ///
105  /// **Returns:** The sensor platform dependent type, or -1 if `device_index`
106  /// is out of range.
107  pub fn SDL_SensorGetDeviceNonPortableType(device_index: c_int) -> c_int;
108
109  /// Get the instance ID of a sensor.
110  ///
111  /// This can be called before any sensors are opened.
112  ///
113  /// **Returns:** The sensor instance ID, or -1 if `device_index` is out of
114  /// range.
115  pub fn SDL_SensorGetDeviceInstanceID(device_index: c_int) -> SDL_SensorID;
116
117  /// Open a sensor for use.
118  ///
119  /// The index passed as an argument refers to the N'th sensor on the system.
120  ///
121  /// **Returns:** A sensor identifier, or NULL if an error occurred.
122  pub fn SDL_SensorOpen(device_index: c_int) -> *mut SDL_Sensor;
123
124  /// Return the SDL_Sensor associated with an instance id.
125  pub fn SDL_SensorFromInstanceID(instance_id: SDL_SensorID)
126    -> *mut SDL_Sensor;
127
128  /// Get the implementation dependent name of a sensor.
129  ///
130  /// **Returns:** The sensor name, or NULL if the sensor is NULL.
131  pub fn SDL_SensorGetName(sensor: *mut SDL_Sensor) -> *const c_char;
132
133  /// Get the type of a sensor.
134  ///
135  /// This can be called before any sensors are opened.
136  ///
137  /// **Returns:** The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
138  pub fn SDL_SensorGetType(sensor: *mut SDL_Sensor) -> SDL_SensorType;
139
140  /// Get the platform dependent type of a sensor.
141  ///
142  /// This can be called before any sensors are opened.
143  ///
144  /// **Returns:** The sensor platform dependent type, or -1 if the sensor is
145  /// NULL.
146  pub fn SDL_SensorGetNonPortableType(sensor: *mut SDL_Sensor) -> c_int;
147
148  /// Get the instance ID of a sensor.
149  ///
150  /// This can be called before any sensors are opened.
151  ///
152  /// **Returns:** The sensor instance ID, or -1 if the sensor is NULL.
153  pub fn SDL_SensorGetInstanceID(sensor: *mut SDL_Sensor) -> SDL_SensorID;
154
155  /// Get the current state of an opened sensor.
156  ///
157  /// The number of values and interpretation of the data is sensor dependent.
158  ///
159  /// * `sensor` The sensor to query
160  /// * `data` A pointer filled with the current sensor state
161  /// * `num_values` The number of values to write to data
162  ///
163  /// **Returns:** 0 or -1 if an error occurred.
164  pub fn SDL_SensorGetData(
165    sensor: *mut SDL_Sensor, data: *mut c_float, num_values: c_int,
166  ) -> c_int;
167
168  /// Close a sensor previously opened with [`SDL_SensorOpen`]
169  pub fn SDL_SensorClose(sensor: *mut SDL_Sensor);
170
171  /// Update the current state of the open sensors.
172  ///
173  /// This is called automatically by the event loop if sensor events are
174  /// enabled.
175  ///
176  /// This needs to be called from the thread that initialized the sensor
177  /// subsystem.
178  pub fn SDL_SensorUpdate();
179}
fermium/sensor.rs

fermium/
sensor.rs
