1 /* 2 DSDL 3 Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20 21 ========================================================================== 22 23 Simple DirectMedia Layer 24 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 25 26 This software is provided 'as-is', without any express or implied 27 warranty. In no event will the authors be held liable for any damages 28 arising from the use of this software. 29 30 Permission is granted to anyone to use this software for any purpose, 31 including commercial applications, and to alter it and redistribute it 32 freely, subject to the following restrictions: 33 34 1. The origin of this software must not be misrepresented; you must not 35 claim that you wrote the original software. If you use this software 36 in a product, an acknowledgment in the product documentation would be 37 appreciated but is not required. 38 2. Altered source versions must be plainly marked as such, and must not be 39 misrepresented as being the original software. 40 3. This notice may not be removed or altered from any source distribution. 41 */ 42 43 /** 44 SDL Sensor Handling 45 46 See_Also: 47 $(LINK2 https://wiki.libsdl.org/SDL3/CategorySensor, SDL3 Sensor Documentation) 48 49 Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga 50 License: Subject to the terms of the Zlib License, as written in the LICENSE file. 51 Authors: 52 Luna Nielsen 53 */ 54 module sdl.sensor; 55 import sdl.properties; 56 import sdl.stdc; 57 58 extern (C) nothrow @nogc: 59 60 /** 61 The opaque structure used to identify an opened SDL sensor. 62 */ 63 struct SDL_Sensor; 64 65 /** 66 This is a unique ID for a sensor for the time it is connected to the 67 system, and is never reused for the lifetime of the application. 68 69 The value 0 is an invalid ID. 70 */ 71 alias SDL_SensorID = Uint32; 72 73 /** 74 A constant to represent standard gravity for accelerometer sensors. 75 76 The accelerometer returns the current acceleration in SI meters per second 77 squared. This measurement includes the force of gravity, so a device at 78 rest will have an value of SDL_STANDARD_GRAVITY away from the center of the 79 earth, which is a positive Y value. 80 */ 81 enum SDL_STANDARD_GRAVITY = 9.80665f; 82 83 /** 84 The different sensors defined by SDL. 85 86 Additional sensors may be available, using platform dependent semantics. 87 88 Here are the additional Android sensors: 89 90 https://developer.android.com/reference/android/hardware/SensorEvent.html#values 91 92 Accelerometer sensor notes: 93 94 The accelerometer returns the current acceleration in SI meters per second 95 squared. This measurement includes the force of gravity, so a device at 96 rest will have an value of SDL_STANDARD_GRAVITY away from the center of the 97 earth, which is a positive Y value. 98 99 - `values[0]`: Acceleration on the x axis 100 - `values[1]`: Acceleration on the y axis 101 - `values[2]`: Acceleration on the z axis 102 103 For phones and tablets held in natural orientation and game controllers 104 held in front of you, the axes are defined as follows: 105 106 - -X ... +X : left ... right 107 - -Y ... +Y : bottom ... top 108 - -Z ... +Z : farther ... closer 109 110 The accelerometer axis data is not changed when the device is rotated. 111 112 Gyroscope sensor notes: 113 114 The gyroscope returns the current rate of rotation in radians per second. 115 The rotation is positive in the counter-clockwise direction. That is, an 116 observer looking from a positive location on one of the axes would see 117 positive rotation on that axis when it appeared to be rotating 118 counter-clockwise. 119 120 - `values[0]`: Angular speed around the x axis (pitch) 121 - `values[1]`: Angular speed around the y axis (yaw) 122 - `values[2]`: Angular speed around the z axis (roll) 123 124 For phones and tablets held in natural orientation and game controllers 125 held in front of you, the axes are defined as follows: 126 127 - -X ... +X : left ... right 128 - -Y ... +Y : bottom ... top 129 - -Z ... +Z : farther ... closer 130 131 The gyroscope axis data is not changed when the device is rotated. 132 133 See_Also: 134 $(D SDL_GetCurrentDisplayOrientation) 135 */ 136 enum SDL_SensorType { 137 138 /** 139 Returned for an invalid sensor 140 */ 141 SDL_SENSOR_INVALID = -1, 142 143 /** 144 Unknown sensor type 145 */ 146 SDL_SENSOR_UNKNOWN, 147 148 /** 149 Accelerometer 150 */ 151 SDL_SENSOR_ACCEL, 152 153 /** 154 Gyroscope 155 */ 156 SDL_SENSOR_GYRO, 157 158 /** 159 Accelerometer for left Joy-Con controller and Wii nunchuk 160 */ 161 SDL_SENSOR_ACCEL_L, 162 163 /** 164 Gyroscope for left Joy-Con controller 165 */ 166 SDL_SENSOR_GYRO_L, 167 168 /** 169 Accelerometer for right Joy-Con controller 170 */ 171 SDL_SENSOR_ACCEL_R, 172 173 /** 174 Gyroscope for right Joy-Con controller 175 */ 176 SDL_SENSOR_GYRO_R 177 } 178 179 /** 180 Get a list of currently connected sensors. 181 182 Params: 183 count = a pointer filled in with the number of sensors returned, may 184 be NULL. 185 186 Returns: 187 A 0 terminated array of sensor instance IDs or NULL on failure; 188 call SDL_GetError() for more information. This should be freed 189 with SDL_free() when it is no longer needed. 190 */ 191 extern SDL_SensorID* SDL_GetSensors(int* count); 192 193 /** 194 Get the implementation dependent name of a sensor. 195 196 This can be called before any sensors are opened. 197 198 Params: 199 instance_id = the sensor instance ID. 200 201 Returns: 202 The sensor name, or NULL if `instance_id` is not valid. 203 */ 204 extern const(char)* SDL_GetSensorNameForID(SDL_SensorID instance_id); 205 206 /** 207 Get the type of a sensor. 208 209 This can be called before any sensors are opened. 210 211 Params: 212 instance_id = the sensor instance ID. 213 214 Returns: 215 The SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is 216 not valid. 217 */ 218 extern SDL_SensorType SDL_GetSensorTypeForID(SDL_SensorID instance_id); 219 220 /** 221 Get the platform dependent type of a sensor. 222 223 This can be called before any sensors are opened. 224 225 Params: 226 instance_id = the sensor instance ID. 227 228 Returns: 229 The sensor platform dependent type, or -1 if `instance_id` is not 230 valid. 231 */ 232 extern int SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); 233 234 /** 235 Open a sensor for use. 236 237 Params: 238 instance_id = the sensor instance ID. 239 240 Returns: 241 An SDL_Sensor object or NULL on failure; call SDL_GetError() for 242 more information. 243 */ 244 extern SDL_Sensor* SDL_OpenSensor(SDL_SensorID instance_id); 245 246 /** 247 Return the SDL_Sensor associated with an instance ID. 248 249 Params: 250 instance_id = the sensor instance ID. 251 252 Returns: 253 An SDL_Sensor object or NULL on failure; call SDL_GetError() for 254 more information. 255 */ 256 extern SDL_Sensor* SDL_GetSensorFromID(SDL_SensorID instance_id); 257 258 /** 259 Get the properties associated with a sensor. 260 261 Params: 262 sensor = the SDL_Sensor object. 263 264 Returns: 265 A valid property ID on success or 0 on failure; call 266 SDL_GetError() for more information. 267 */ 268 extern SDL_PropertiesID SDL_GetSensorProperties(SDL_Sensor* sensor); 269 270 /** 271 Get the implementation dependent name of a sensor. 272 273 Params: 274 sensor = the SDL_Sensor object. 275 276 Returns: 277 The sensor name or NULL on failure; call SDL_GetError() for more 278 information. 279 */ 280 extern const(char)* SDL_GetSensorName(SDL_Sensor* sensor); 281 282 /** 283 Get the type of a sensor. 284 285 Params: 286 sensor = the SDL_Sensor object to inspect. 287 288 Returns: 289 The SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is 290 NULL. 291 */ 292 extern SDL_SensorType SDL_GetSensorType(SDL_Sensor* sensor); 293 294 /** 295 Get the platform dependent type of a sensor. 296 297 Params: 298 sensor = the SDL_Sensor object to inspect. 299 300 Returns: 301 The sensor platform dependent type, or -1 if `sensor` is NULL. 302 */ 303 extern int SDL_GetSensorNonPortableType(SDL_Sensor* sensor); 304 305 /** 306 Get the instance ID of a sensor. 307 308 Params: 309 sensor = the SDL_Sensor object to inspect. 310 311 Returns: 312 The sensor instance ID, or 0 on failure; call SDL_GetError() for 313 more information. 314 */ 315 extern SDL_SensorID SDL_GetSensorID(SDL_Sensor* sensor); 316 317 /** 318 Get the current state of an opened sensor. 319 320 The number of values and interpretation of the data is sensor dependent. 321 322 Params: 323 sensor = the SDL_Sensor object to query. 324 data = a pointer filled with the current sensor state. 325 num_values = the number of values to write to data. 326 327 Returns: 328 true on success or false on failure; call SDL_GetError() for more 329 information. 330 */ 331 extern bool SDL_GetSensorData(SDL_Sensor* sensor, float* data, int num_values); 332 333 /** 334 Close a sensor previously opened with SDL_OpenSensor(). 335 336 Params: 337 sensor = the SDL_Sensor object to close. 338 */ 339 extern void SDL_CloseSensor(SDL_Sensor* sensor); 340 341 /** 342 Update the current state of the open sensors. 343 344 This is called automatically by the event loop if sensor events are 345 enabled. 346 347 This needs to be called from the thread that initialized the sensor 348 subsystem. 349 */ 350 extern void SDL_UpdateSensors();