SDL 2.0
SDL_sensor.h File Reference
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "begin_code.h"
#include "close_code.h"
+ Include dependency graph for SDL_sensor.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define SDL_STANDARD_GRAVITY   9.80665f
 

Typedefs

typedef Sint32 SDL_SensorID
 

Enumerations

enum  SDL_SensorType {
  SDL_SENSOR_INVALID = -1 ,
  SDL_SENSOR_UNKNOWN ,
  SDL_SENSOR_ACCEL ,
  SDL_SENSOR_GYRO
}
 

Functions

int SDL_NumSensors (void)
 Count the number of sensors attached to the system right now. More...
 
const char * SDL_SensorGetDeviceName (int device_index)
 Get the implementation dependent name of a sensor. More...
 
SDL_SensorType SDL_SensorGetDeviceType (int device_index)
 Get the type of a sensor. More...
 
int SDL_SensorGetDeviceNonPortableType (int device_index)
 Get the platform dependent type of a sensor. More...
 
SDL_SensorID SDL_SensorGetDeviceInstanceID (int device_index)
 Get the instance ID of a sensor. More...
 
SDL_Sensor * SDL_SensorOpen (int device_index)
 Open a sensor for use. More...
 
SDL_Sensor * SDL_SensorFromInstanceID (SDL_SensorID instance_id)
 
const char * SDL_SensorGetName (SDL_Sensor *sensor)
 Get the implementation dependent name of a sensor. More...
 
SDL_SensorType SDL_SensorGetType (SDL_Sensor *sensor)
 Get the type of a sensor. More...
 
int SDL_SensorGetNonPortableType (SDL_Sensor *sensor)
 Get the platform dependent type of a sensor. More...
 
SDL_SensorID SDL_SensorGetInstanceID (SDL_Sensor *sensor)
 Get the instance ID of a sensor. More...
 
int SDL_SensorGetData (SDL_Sensor *sensor, float *data, int num_values)
 
void SDL_SensorClose (SDL_Sensor *sensor)
 
void SDL_SensorUpdate (void)
 

Detailed Description

Include file for SDL sensor event handling

Definition in file SDL_sensor.h.

Macro Definition Documentation

◆ SDL_STANDARD_GRAVITY

#define SDL_STANDARD_GRAVITY   9.80665f

Accelerometer sensor

The accelerometer returns the current acceleration in SI meters per second squared. This includes gravity, so a device at rest will have an acceleration of SDL_STANDARD_GRAVITY straight down.

values[0]: Acceleration on the x axis values[1]: Acceleration on the y axis values[2]: Acceleration on the z axis

For phones held in portrait mode, the axes are defined as follows: -X ... +X : left ... right -Y ... +Y : bottom ... top -Z ... +Z : farther ... closer

The axis data is not changed when the phone is rotated.

See also
SDL_GetDisplayOrientation()

Definition at line 97 of file SDL_sensor.h.

Typedef Documentation

◆ SDL_SensorID

This is a unique ID for a sensor for the time it is connected to the system, and is never reused for the lifetime of the application.

The ID value starts at 0 and increments from there. The value -1 is an invalid ID.

Definition at line 60 of file SDL_sensor.h.

Enumeration Type Documentation

◆ SDL_SensorType

Enumerator
SDL_SENSOR_INVALID 

Returned for an invalid sensor

SDL_SENSOR_UNKNOWN 

Unknown sensor type

SDL_SENSOR_ACCEL 

Accelerometer

SDL_SENSOR_GYRO 

Gyroscope

Definition at line 69 of file SDL_sensor.h.

70{
71 SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */
72 SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */
73 SDL_SENSOR_ACCEL, /**< Accelerometer */
74 SDL_SENSOR_GYRO /**< Gyroscope */
SDL_SensorType
Definition: SDL_sensor.h:70
@ SDL_SENSOR_INVALID
Definition: SDL_sensor.h:71
@ SDL_SENSOR_GYRO
Definition: SDL_sensor.h:74
@ SDL_SENSOR_UNKNOWN
Definition: SDL_sensor.h:72
@ SDL_SENSOR_ACCEL
Definition: SDL_sensor.h:73

Function Documentation

◆ SDL_NumSensors()

int SDL_NumSensors ( void  )

Count the number of sensors attached to the system right now.

Gyroscope sensor

The gyroscope returns the current rate of rotation in radians per second. The rotation is positive in the counter-clockwise direction. That is, an observer looking from a positive location on one of the axes would see positive rotation on that axis when it appeared to be rotating counter-clockwise.

values[0]: Angular speed around the x axis values[1]: Angular speed around the y axis values[2]: Angular speed around the z axis

For phones held in portrait mode, the axes are defined as follows: -X ... +X : left ... right -Y ... +Y : bottom ... top -Z ... +Z : farther ... closer

The axis data is not changed when the phone is rotated.

See also
SDL_GetDisplayOrientation()

Definition at line 97 of file SDL_sensor.c.

98{
99 int i, total_sensors = 0;
101 for (i = 0; i < SDL_arraysize(SDL_sensor_drivers); ++i) {
102 total_sensors += SDL_sensor_drivers[i]->GetCount();
103 }
105 return total_sensors;
106}
static SDL_SensorDriver * SDL_sensor_drivers[]
Definition: SDL_sensor.c:35
static void SDL_LockSensors(void)
Definition: SDL_sensor.c:52
static void SDL_UnlockSensors(void)
Definition: SDL_sensor.c:60
#define SDL_arraysize(array)
Definition: SDL_stdinc.h:115
return Display return Display Bool Bool int int int return Display XEvent Bool(*) XPointer return Display return Display Drawable _Xconst char unsigned int unsigned int return Display Pixmap Pixmap XColor XColor unsigned int unsigned int return Display _Xconst char char int char return Display Visual unsigned int int int char unsigned int unsigned int in i)
Definition: SDL_x11sym.h:50
int(* GetCount)(void)
Definition: SDL_syssensor.h:60

References SDL_SensorDriver::GetCount, i, SDL_arraysize, SDL_LockSensors(), SDL_sensor_drivers, and SDL_UnlockSensors().

◆ SDL_SensorClose()

void SDL_SensorClose ( SDL_Sensor *  sensor)

Close a sensor previously opened with SDL_SensorOpen()

Definition at line 390 of file SDL_sensor.c.

391{
392 SDL_Sensor *sensorlist;
393 SDL_Sensor *sensorlistprev;
394
395 if (!SDL_PrivateSensorValid(sensor)) {
396 return;
397 }
398
400
401 /* First decrement ref count */
402 if (--sensor->ref_count > 0) {
404 return;
405 }
406
409 return;
410 }
411
412 sensor->driver->Close(sensor);
413 sensor->hwdata = NULL;
414
415 sensorlist = SDL_sensors;
416 sensorlistprev = NULL;
417 while (sensorlist) {
418 if (sensor == sensorlist) {
419 if (sensorlistprev) {
420 /* unlink this entry */
421 sensorlistprev->next = sensorlist->next;
422 } else {
423 SDL_sensors = sensor->next;
424 }
425 break;
426 }
427 sensorlistprev = sensorlist;
428 sensorlist = sensorlist->next;
429 }
430
431 SDL_free(sensor->name);
432
433 /* Free the data associated with this sensor */
434 SDL_free(sensor);
435
437}
#define SDL_free
static SDL_Sensor * SDL_sensors
Definition: SDL_sensor.c:46
static SDL_bool SDL_updating_sensor
Definition: SDL_sensor.c:47
static int SDL_PrivateSensorValid(SDL_Sensor *sensor)
Definition: SDL_sensor.c:305
#define NULL
Definition: begin_code.h:167

References NULL, SDL_free, SDL_LockSensors(), SDL_PrivateSensorValid(), SDL_sensors, SDL_UnlockSensors(), and SDL_updating_sensor.

Referenced by SDL_SensorQuit(), and SDL_SensorUpdate().

◆ SDL_SensorFromInstanceID()

SDL_Sensor * SDL_SensorFromInstanceID ( SDL_SensorID  instance_id)

Return the SDL_Sensor associated with an instance id.

Definition at line 287 of file SDL_sensor.c.

288{
289 SDL_Sensor *sensor;
290
292 for (sensor = SDL_sensors; sensor; sensor = sensor->next) {
293 if (sensor->instance_id == instance_id) {
294 break;
295 }
296 }
298 return sensor;
299}

References SDL_LockSensors(), SDL_sensors, and SDL_UnlockSensors().

◆ SDL_SensorGetData()

int SDL_SensorGetData ( SDL_Sensor *  sensor,
float *  data,
int  num_values 
)

Get the current state of an opened sensor.

The number of values and interpretation of the data is sensor dependent.

Parameters
sensorThe sensor to query
dataA pointer filled with the current sensor state
num_valuesThe number of values to write to data
Returns
0 or -1 if an error occurred.

Definition at line 375 of file SDL_sensor.c.

376{
377 if (!SDL_PrivateSensorValid(sensor)) {
378 return -1;
379 }
380
381 num_values = SDL_min(num_values, SDL_arraysize(sensor->data));
382 SDL_memcpy(data, sensor->data, num_values*sizeof(*data));
383 return 0;
384}
#define SDL_memcpy
GLint GLenum GLsizei GLsizei GLsizei GLint GLsizei const GLvoid * data
Definition: SDL_opengl.h:1974
#define SDL_min(x, y)
Definition: SDL_stdinc.h:406

References SDL_arraysize, SDL_memcpy, SDL_min, and SDL_PrivateSensorValid().

◆ SDL_SensorGetDeviceInstanceID()

SDL_SensorID SDL_SensorGetDeviceInstanceID ( int  device_index)

Get the instance ID of a sensor.

This can be called before any sensors are opened.

Returns
The sensor instance ID, or -1 if device_index is out of range.

Definition at line 193 of file SDL_sensor.c.

194{
195 SDL_SensorDriver *driver;
196 SDL_SensorID instance_id = -1;
197
199 if (SDL_GetDriverAndSensorIndex(device_index, &driver, &device_index)) {
200 instance_id = driver->GetDeviceInstanceID(device_index);
201 }
203
204 return instance_id;
205}
static SDL_bool SDL_GetDriverAndSensorIndex(int device_index, SDL_SensorDriver **driver, int *driver_index)
Definition: SDL_sensor.c:122
Sint32 SDL_SensorID
Definition: SDL_sensor.h:60
SDL_SensorID(* GetDeviceInstanceID)(int device_index)
Definition: SDL_syssensor.h:75

References SDL_SensorDriver::GetDeviceInstanceID, SDL_GetDriverAndSensorIndex(), SDL_LockSensors(), and SDL_UnlockSensors().

◆ SDL_SensorGetDeviceName()

const char * SDL_SensorGetDeviceName ( int  device_index)

Get the implementation dependent name of a sensor.

This can be called before any sensors are opened.

Returns
The sensor name, or NULL if device_index is out of range.

Definition at line 147 of file SDL_sensor.c.

148{
149 SDL_SensorDriver *driver;
150 const char *name = NULL;
151
153 if (SDL_GetDriverAndSensorIndex(device_index, &driver, &device_index)) {
154 name = driver->GetDeviceName(device_index);
155 }
157
158 /* FIXME: Really we should reference count this name so it doesn't go away after unlock */
159 return name;
160}
GLuint const GLchar * name
const char *(* GetDeviceName)(int device_index)
Definition: SDL_syssensor.h:66

References SDL_SensorDriver::GetDeviceName, NULL, SDL_GetDriverAndSensorIndex(), SDL_LockSensors(), and SDL_UnlockSensors().

◆ SDL_SensorGetDeviceNonPortableType()

int SDL_SensorGetDeviceNonPortableType ( int  device_index)

Get the platform dependent type of a sensor.

This can be called before any sensors are opened.

Returns
The sensor platform dependent type, or -1 if device_index is out of range.

Definition at line 178 of file SDL_sensor.c.

179{
180 SDL_SensorDriver *driver;
181 int type = -1;
182
184 if (SDL_GetDriverAndSensorIndex(device_index, &driver, &device_index)) {
185 type = driver->GetDeviceNonPortableType(device_index);
186 }
188
189 return type;
190}
GLuint GLuint GLsizei GLenum type
Definition: SDL_opengl.h:1571
int(* GetDeviceNonPortableType)(int device_index)
Definition: SDL_syssensor.h:72

References SDL_SensorDriver::GetDeviceNonPortableType, SDL_GetDriverAndSensorIndex(), SDL_LockSensors(), and SDL_UnlockSensors().

◆ SDL_SensorGetDeviceType()

SDL_SensorType SDL_SensorGetDeviceType ( int  device_index)

Get the type of a sensor.

This can be called before any sensors are opened.

Returns
The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.

Definition at line 163 of file SDL_sensor.c.

164{
165 SDL_SensorDriver *driver;
167
169 if (SDL_GetDriverAndSensorIndex(device_index, &driver, &device_index)) {
170 type = driver->GetDeviceType(device_index);
171 }
173
174 return type;
175}
SDL_SensorType(* GetDeviceType)(int device_index)
Definition: SDL_syssensor.h:69

References SDL_SensorDriver::GetDeviceType, SDL_GetDriverAndSensorIndex(), SDL_LockSensors(), SDL_SENSOR_INVALID, and SDL_UnlockSensors().

◆ SDL_SensorGetInstanceID()

SDL_SensorID SDL_SensorGetInstanceID ( SDL_Sensor *  sensor)

Get the instance ID of a sensor.

This can be called before any sensors are opened.

Returns
The sensor instance ID, or -1 if the sensor is NULL.

Definition at line 362 of file SDL_sensor.c.

363{
364 if (!SDL_PrivateSensorValid(sensor)) {
365 return -1;
366 }
367
368 return sensor->instance_id;
369}

References SDL_PrivateSensorValid().

◆ SDL_SensorGetName()

const char * SDL_SensorGetName ( SDL_Sensor *  sensor)

Get the implementation dependent name of a sensor.

Returns
The sensor name, or NULL if the sensor is NULL.

Definition at line 323 of file SDL_sensor.c.

324{
325 if (!SDL_PrivateSensorValid(sensor)) {
326 return NULL;
327 }
328
329 return sensor->name;
330}

References NULL, and SDL_PrivateSensorValid().

◆ SDL_SensorGetNonPortableType()

int SDL_SensorGetNonPortableType ( SDL_Sensor *  sensor)

Get the platform dependent type of a sensor.

This can be called before any sensors are opened.

Returns
The sensor platform dependent type, or -1 if the sensor is NULL.

Definition at line 349 of file SDL_sensor.c.

350{
351 if (!SDL_PrivateSensorValid(sensor)) {
352 return -1;
353 }
354
355 return sensor->non_portable_type;
356}

References SDL_PrivateSensorValid().

◆ SDL_SensorGetType()

SDL_SensorType SDL_SensorGetType ( SDL_Sensor *  sensor)

Get the type of a sensor.

This can be called before any sensors are opened.

Returns
The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.

Definition at line 336 of file SDL_sensor.c.

337{
338 if (!SDL_PrivateSensorValid(sensor)) {
339 return SDL_SENSOR_INVALID;
340 }
341
342 return sensor->type;
343}

References SDL_PrivateSensorValid(), and SDL_SENSOR_INVALID.

◆ SDL_SensorOpen()

SDL_Sensor * SDL_SensorOpen ( int  device_index)

Open a sensor for use.

The index passed as an argument refers to the N'th sensor on the system.

Returns
A sensor identifier, or NULL if an error occurred.

Definition at line 215 of file SDL_sensor.c.

216{
217 SDL_SensorDriver *driver;
218 SDL_SensorID instance_id;
219 SDL_Sensor *sensor;
220 SDL_Sensor *sensorlist;
221 const char *sensorname = NULL;
222
224
225 if (!SDL_GetDriverAndSensorIndex(device_index, &driver, &device_index)) {
227 return NULL;
228 }
229
230 sensorlist = SDL_sensors;
231 /* If the sensor is already open, return it
232 * it is important that we have a single sensor * for each instance id
233 */
234 instance_id = driver->GetDeviceInstanceID(device_index);
235 while (sensorlist) {
236 if (instance_id == sensorlist->instance_id) {
237 sensor = sensorlist;
238 ++sensor->ref_count;
240 return sensor;
241 }
242 sensorlist = sensorlist->next;
243 }
244
245 /* Create and initialize the sensor */
246 sensor = (SDL_Sensor *) SDL_calloc(sizeof(*sensor), 1);
247 if (sensor == NULL) {
250 return NULL;
251 }
252 sensor->driver = driver;
253 sensor->instance_id = instance_id;
254 sensor->type = driver->GetDeviceType(device_index);
255 sensor->non_portable_type = driver->GetDeviceNonPortableType(device_index);
256
257 if (driver->Open(sensor, device_index) < 0) {
258 SDL_free(sensor);
260 return NULL;
261 }
262
263 sensorname = driver->GetDeviceName(device_index);
264 if (sensorname) {
265 sensor->name = SDL_strdup(sensorname);
266 } else {
267 sensor->name = NULL;
268 }
269
270 /* Add sensor to list */
271 ++sensor->ref_count;
272 /* Link the sensor in the list */
273 sensor->next = SDL_sensors;
274 SDL_sensors = sensor;
275
277
278 driver->Update(sensor);
279
280 return sensor;
281}
#define SDL_strdup
#define SDL_calloc
#define SDL_OutOfMemory()
Definition: SDL_error.h:52
void(* Update)(SDL_Sensor *sensor)
Definition: SDL_syssensor.h:88
int(* Open)(SDL_Sensor *sensor, int device_index)
Definition: SDL_syssensor.h:81

References SDL_SensorDriver::GetDeviceInstanceID, SDL_SensorDriver::GetDeviceName, SDL_SensorDriver::GetDeviceNonPortableType, SDL_SensorDriver::GetDeviceType, NULL, SDL_SensorDriver::Open, SDL_calloc, SDL_free, SDL_GetDriverAndSensorIndex(), SDL_LockSensors(), SDL_OutOfMemory, SDL_sensors, SDL_strdup, SDL_UnlockSensors(), and SDL_SensorDriver::Update.

◆ SDL_SensorUpdate()

void SDL_SensorUpdate ( void  )

Update the current state of the open sensors.

This is called automatically by the event loop if sensor events are enabled.

This needs to be called from the thread that initialized the sensor subsystem.

Definition at line 738 of file SDL_dynapi_procs.h.

References SDL_SensorDriver::Detect, i, SDL_arraysize, SDL_FALSE, SDL_INIT_SENSOR, SDL_LockSensors(), SDL_sensor_drivers, SDL_SensorClose(), SDL_sensors, SDL_TRUE, SDL_UnlockSensors(), SDL_updating_sensor, and SDL_WasInit.