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 struct _SDL_Sensor | SDL_Sensor
typedef Sint32 | SDL_SensorID

## Enumerations

enum | SDL_SensorType { SDL_SENSOR_INVALID = -1 , SDL_SENSOR_UNKNOWN , SDL_SENSOR_ACCEL , SDL_SENSOR_GYRO , SDL_SENSOR_ACCEL_L , SDL_SENSOR_GYRO_L , SDL_SENSOR_ACCEL_R , SDL_SENSOR_GYRO_R }

## Functions

void | SDL_LockSensors (void)
void | SDL_UnlockSensors (void)
int | SDL_NumSensors (void)
const char * | SDL_SensorGetDeviceName (int device_index)
SDL_SensorType | SDL_SensorGetDeviceType (int device_index)
int | SDL_SensorGetDeviceNonPortableType (int device_index)
SDL_SensorID | SDL_SensorGetDeviceInstanceID (int device_index)
SDL_Sensor * | SDL_SensorOpen (int device_index)
SDL_Sensor * | SDL_SensorFromInstanceID (SDL_SensorID instance_id)
const char * | SDL_SensorGetName (SDL_Sensor *sensor)
SDL_SensorType | SDL_SensorGetType (SDL_Sensor *sensor)
int | SDL_SensorGetNonPortableType (SDL_Sensor *sensor)
SDL_SensorID | SDL_SensorGetInstanceID (SDL_Sensor *sensor)
int | SDL_SensorGetData (SDL_Sensor *sensor, float *data, int num_values)
int | SDL_SensorGetDataWithTimestamp (SDL_Sensor *sensor, Uint64 *timestamp, float *data, int num_values)
void | SDL_SensorClose (SDL_Sensor *sensor)
void | SDL_SensorUpdate (void)

## Macro Definition Documentation

## SDL_STANDARD_GRAVITY

#define SDL_STANDARD_GRAVITY 9.80665f

A constant to represent standard gravity for accelerometer sensors.

The accelerometer returns the current acceleration in SI meters per second squared. This measurement includes the force of gravity, so a device at rest will have an value of SDL_STANDARD_GRAVITY away from the center of the earth, which is a positive Y value.

Definition at line 134 of file SDL_sensor.h.

## Typedef Documentation

## SDL_Sensor

typedef struct _SDL_Sensor SDL_Sensor

Definition at line 51 of file SDL_sensor.h.

## SDL_SensorID

typedef Sint32 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

enum SDL_SensorType

The different sensors defined by SDL.

Additional sensors may be available, using platform dependent semantics.

Here are the additional Android sensors:

https://developer.android.com/reference/android/hardware/SensorEvent.html#values

Accelerometer sensor notes:

The accelerometer returns the current acceleration in SI meters per second squared. This measurement includes the force of gravity, so a device at rest will have an value of SDL_STANDARD_GRAVITY away from the center of the earth, which is a positive Y value.

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

For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:

- -X ... +X : left ... right
- -Y ... +Y : bottom ... top
- -Z ... +Z : farther ... closer

The accelerometer axis data is not changed when the device is rotated.

Gyroscope sensor notes:

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 (pitch)
- values[1]: Angular speed around the y axis (yaw)
- values[2]: Angular speed around the z axis (roll)

For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:

- -X ... +X : left ... right
- -Y ... +Y : bottom ... top
- -Z ... +Z : farther ... closer

The gyroscope axis data is not changed when the device is rotated.

See also
  SDL_GetDisplayOrientation

Enumerator
SDL_SENSOR_INVALID | Returned for an invalid sensor
SDL_SENSOR_UNKNOWN | Unknown sensor type
SDL_SENSOR_ACCEL | Accelerometer
SDL_SENSOR_GYRO | Gyroscope
SDL_SENSOR_ACCEL_L | Accelerometer for left Joy-Con controller and Wii nunchuk
SDL_SENSOR_GYRO_L | Gyroscope for left Joy-Con controller
SDL_SENSOR_ACCEL_R | Accelerometer for right Joy-Con controller
SDL_SENSOR_GYRO_R | Gyroscope for right Joy-Con controller

Definition at line 114 of file SDL_sensor.h.

{
SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */
SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */
SDL_SENSOR_ACCEL, /**< Accelerometer */
SDL_SENSOR_GYRO, /**< Gyroscope */
SDL_SENSOR_ACCEL_L, /**< Accelerometer for left Joy-Con controller and Wii nunchuk */
SDL_SENSOR_GYRO_L, /**< Gyroscope for left Joy-Con controller */
SDL_SENSOR_ACCEL_R, /**< Accelerometer for right Joy-Con controller */
SDL_SENSOR_GYRO_R /**< Gyroscope for right Joy-Con controller */
} SDL_SensorType;
SDL_SensorType
SDL_SensorType
Definition SDL_sensor.h:115
SDL_SENSOR_GYRO_L
@ SDL_SENSOR_GYRO_L
Definition SDL_sensor.h:121
SDL_SENSOR_INVALID
@ SDL_SENSOR_INVALID
Definition SDL_sensor.h:116
SDL_SENSOR_GYRO
@ SDL_SENSOR_GYRO
Definition SDL_sensor.h:119
SDL_SENSOR_ACCEL_R
@ SDL_SENSOR_ACCEL_R
Definition SDL_sensor.h:122
SDL_SENSOR_UNKNOWN
@ SDL_SENSOR_UNKNOWN
Definition SDL_sensor.h:117
SDL_SENSOR_ACCEL
@ SDL_SENSOR_ACCEL
Definition SDL_sensor.h:118
SDL_SENSOR_ACCEL_L
@ SDL_SENSOR_ACCEL_L
Definition SDL_sensor.h:120
SDL_SENSOR_GYRO_R
@ SDL_SENSOR_GYRO_R
Definition SDL_sensor.h:123

## Function Documentation

## SDL_LockSensors()

void SDL_LockSensors | ( | void |  | ) |

extern

Locking for multi-threaded access to the sensor API

If you are using the sensor API or handling events from multiple threads you should use these locking functions to protect access to the sensors.

In particular, you are guaranteed that the sensor list won't change, so the API functions that take a sensor index will be valid, and sensor events will not be delivered.

Since
  This function is available since SDL 2.0.14.

## SDL_NumSensors()

int SDL_NumSensors | ( | void |  | ) |

extern

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

Returns
  the number of sensors detected.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorClose()

void SDL_SensorClose | ( | SDL_Sensor * | sensor | ) |

extern

Close a sensor previously opened with SDL_SensorOpen().

Parameters

  sensor | The SDL_Sensor object to close.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorFromInstanceID()

SDL_Sensor * SDL_SensorFromInstanceID | ( | SDL_SensorID | instance_id | ) |

extern

Return the SDL_Sensor associated with an instance id.

Parameters

  instance_id | The sensor from instance id.

Returns
  an SDL_Sensor object.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetData()

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

extern

Get the current state of an opened sensor.

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

Parameters

  sensor | The SDL_Sensor object to query.
  data | A pointer filled with the current sensor state.
  num_values | The number of values to write to data.

Returns
  0 or -1 if an error occurred.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetDataWithTimestamp()

int SDL_SensorGetDataWithTimestamp | ( | SDL_Sensor * | sensor,
|  | Uint64 * | timestamp,
|  | float * | data,
|  | int | num_values )

extern

Get the current state of an opened sensor with the timestamp of the last update.

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

Parameters

  sensor | The SDL_Sensor object to query.
  timestamp | A pointer filled with the timestamp in microseconds of the current sensor reading if available, or 0 if not.
  data | A pointer filled with the current sensor state.
  num_values | The number of values to write to data.

Returns
  0 or -1 if an error occurred.

Since
  This function is available since SDL 2.26.0.

## SDL_SensorGetDeviceInstanceID()

SDL_SensorID SDL_SensorGetDeviceInstanceID | ( | int | device_index | ) |

extern

Get the instance ID of a sensor.

Parameters

  device_index | The sensor to get instance id from.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetDeviceName()

const char * SDL_SensorGetDeviceName | ( | int | device_index | ) |

extern

Get the implementation dependent name of a sensor.

Parameters

  device_index | The sensor to obtain name from.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetDeviceNonPortableType()

int SDL_SensorGetDeviceNonPortableType | ( | int | device_index | ) |

extern

Get the platform dependent type of a sensor.

Parameters

  device_index | The sensor to check.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetDeviceType()

SDL_SensorType SDL_SensorGetDeviceType | ( | int | device_index | ) |

extern

Get the type of a sensor.

Parameters

  device_index | The sensor to get the type from.

Returns
  the SDL_SensorType, or SDL_SENSOR_INVALID if device_index is out of range.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetInstanceID()

SDL_SensorID SDL_SensorGetInstanceID | ( | SDL_Sensor * | sensor | ) |

extern

Get the instance ID of a sensor.

Parameters

  sensor | The SDL_Sensor object to inspect.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetName()

const char * SDL_SensorGetName | ( | SDL_Sensor * | sensor | ) |

extern

Get the implementation dependent name of a sensor

Parameters

  sensor | The SDL_Sensor object.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetNonPortableType()

int SDL_SensorGetNonPortableType | ( | SDL_Sensor * | sensor | ) |

extern

Get the platform dependent type of a sensor.

Parameters

  sensor | The SDL_Sensor object to inspect.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorGetType()

SDL_SensorType SDL_SensorGetType | ( | SDL_Sensor * | sensor | ) |

extern

Get the type of a sensor.

Parameters

  sensor | The SDL_Sensor object to inspect.

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

Since
  This function is available since SDL 2.0.9.

## SDL_SensorOpen()

SDL_Sensor * SDL_SensorOpen | ( | int | device_index | ) |

extern

Open a sensor for use.

Parameters

  device_index | The sensor to open.

Returns
  an SDL_Sensor sensor object, or NULL if an error occurred.

Since
  This function is available since SDL 2.0.9.

## SDL_SensorUpdate()

void SDL_SensorUpdate | ( | void |  | ) |

extern

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.

Since
  This function is available since SDL 2.0.9.

## SDL_UnlockSensors()

void SDL_UnlockSensors | ( | void |  | ) |

extern