SDL 3.0
SDL_sensor.h File Reference

Include file for SDL sensor event handling. More...

+ 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 Uint32 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

SDL_SensorIDSDL_GetSensors (int *count)
 
const char * SDL_GetSensorInstanceName (SDL_SensorID instance_id)
 
SDL_SensorType SDL_GetSensorInstanceType (SDL_SensorID instance_id)
 
int SDL_GetSensorInstanceNonPortableType (SDL_SensorID instance_id)
 
SDL_SensorSDL_OpenSensor (SDL_SensorID instance_id)
 
SDL_SensorSDL_GetSensorFromInstanceID (SDL_SensorID instance_id)
 
const char * SDL_GetSensorName (SDL_Sensor *sensor)
 
SDL_SensorType SDL_GetSensorType (SDL_Sensor *sensor)
 
int SDL_GetSensorNonPortableType (SDL_Sensor *sensor)
 
SDL_SensorID SDL_GetSensorInstanceID (SDL_Sensor *sensor)
 
int SDL_GetSensorData (SDL_Sensor *sensor, float *data, int num_values)
 
void SDL_CloseSensor (SDL_Sensor *sensor)
 
void SDL_UpdateSensors (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 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.

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 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 axis data is not changed when the phone is rotated.

See also
SDL_GetDisplayOrientation()

Definition at line 102 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

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 1 and increments from there. The value 0 is an invalid ID.

Definition at line 59 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

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 68 of file SDL_sensor.h.

69{
70 SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */
71 SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */
72 SDL_SENSOR_ACCEL, /**< Accelerometer */
73 SDL_SENSOR_GYRO, /**< Gyroscope */
74 SDL_SENSOR_ACCEL_L, /**< Accelerometer for left Joy-Con controller and Wii nunchuk */
75 SDL_SENSOR_GYRO_L, /**< Gyroscope for left Joy-Con controller */
76 SDL_SENSOR_ACCEL_R, /**< Accelerometer for right Joy-Con controller */
77 SDL_SENSOR_GYRO_R /**< Gyroscope for right Joy-Con controller */
SDL_SensorType
Definition: SDL_sensor.h:69
@ SDL_SENSOR_GYRO_L
Definition: SDL_sensor.h:75
@ SDL_SENSOR_INVALID
Definition: SDL_sensor.h:70
@ SDL_SENSOR_GYRO
Definition: SDL_sensor.h:73
@ SDL_SENSOR_ACCEL_R
Definition: SDL_sensor.h:76
@ SDL_SENSOR_UNKNOWN
Definition: SDL_sensor.h:71
@ SDL_SENSOR_ACCEL
Definition: SDL_sensor.h:72
@ SDL_SENSOR_ACCEL_L
Definition: SDL_sensor.h:74
@ SDL_SENSOR_GYRO_R
Definition: SDL_sensor.h:77

Function Documentation

◆ SDL_CloseSensor()

void SDL_CloseSensor ( SDL_Sensor sensor)

Close a sensor previously opened with SDL_OpenSensor().

Parameters
sensorThe SDL_Sensor object to close
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorData()

int SDL_GetSensorData ( 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 SDL_Sensor object to query
dataA pointer filled with the current sensor state
num_valuesThe number of values to write to data
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorFromInstanceID()

SDL_Sensor * SDL_GetSensorFromInstanceID ( SDL_SensorID  instance_id)

Return the SDL_Sensor associated with an instance ID.

Parameters
instance_idthe sensor instance ID
Returns
an SDL_Sensor object.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorInstanceID()

SDL_SensorID SDL_GetSensorInstanceID ( SDL_Sensor sensor)

Get the instance ID of a sensor.

Parameters
sensorThe SDL_Sensor object to inspect
Returns
the sensor instance ID, or 0 if sensor is NULL.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorInstanceName()

const char * SDL_GetSensorInstanceName ( SDL_SensorID  instance_id)

Get the implementation dependent name of a sensor.

Parameters
instance_idthe sensor instance ID
Returns
the sensor name, or NULL if instance_id is not valid
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorInstanceNonPortableType()

int SDL_GetSensorInstanceNonPortableType ( SDL_SensorID  instance_id)

Get the platform dependent type of a sensor.

Parameters
instance_idthe sensor instance ID
Returns
the sensor platform dependent type, or -1 if instance_id is not valid
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorInstanceType()

SDL_SensorType SDL_GetSensorInstanceType ( SDL_SensorID  instance_id)

Get the type of a sensor.

Parameters
instance_idthe sensor instance ID
Returns
the SDL_SensorType, or SDL_SENSOR_INVALID if instance_id is not valid
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorName()

const char * SDL_GetSensorName ( SDL_Sensor sensor)

Get the implementation dependent name of a sensor

Parameters
sensorThe SDL_Sensor object
Returns
the sensor name, or NULL if sensor is NULL.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorNonPortableType()

int SDL_GetSensorNonPortableType ( SDL_Sensor sensor)

Get the platform dependent type of a sensor.

Parameters
sensorThe SDL_Sensor object to inspect
Returns
the sensor platform dependent type, or -1 if sensor is NULL.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensors()

SDL_SensorID * SDL_GetSensors ( int *  count)

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

For phones held in portrait mode 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 axis data is not changed when the phone or controller is rotated.

See also
SDL_GetDisplayOrientation() Get a list of currently connected sensors.
Parameters
counta pointer filled in with the number of sensors returned
Returns
a 0 terminated array of sensor instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetSensorType()

SDL_SensorType SDL_GetSensorType ( SDL_Sensor sensor)

Get the type of a sensor.

Parameters
sensorThe 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 3.0.0.

◆ SDL_OpenSensor()

SDL_Sensor * SDL_OpenSensor ( SDL_SensorID  instance_id)

Open a sensor for use.

Parameters
instance_idthe sensor instance ID
Returns
an SDL_Sensor sensor object, or NULL if an error occurred.
Since
This function is available since SDL 3.0.0.

◆ SDL_UpdateSensors()

void SDL_UpdateSensors ( 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.

Since
This function is available since SDL 3.0.0.