SDL sensor management. More...

Collaboration diagram for Sensors:

Classes
struct	SDL::SensorParam
	Safely wrap Sensor for non owning parameters. More...

class	SDL::Sensor
	The opaque structure used to identify an opened SDL sensor. More...

struct	SDL::SensorRef
	Semi-safe reference for Sensor. More...

Typedefs
using	SDL::SensorRaw = SDL_Sensor *
	Alias to raw representation for Sensor.

using	SDL::SensorID = Uint32
	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. More...

using	SDL::SensorType = SDL_SensorType
	The different sensors defined by SDL. More...

Functions
OwnArray< SensorID >	SDL::GetSensors ()
	Get a list of currently connected sensors. More...

const char *	SDL::GetSensorNameForID (SensorID instance_id)
	Get the implementation dependent name of a sensor. More...

SensorType	SDL::GetSensorTypeForID (SensorID instance_id)
	Get the type of a sensor. More...

int	SDL::GetSensorNonPortableTypeForID (SensorID instance_id)
	Get the platform dependent type of a sensor. More...

Sensor	SDL::OpenSensor (SensorID instance_id)
	Open a sensor for use. More...

SensorRef	SDL::GetSensorFromID (SensorID instance_id)
	Return the Sensor associated with an instance ID. More...

PropertiesRef	SDL::GetSensorProperties (SensorParam sensor)
	Get the properties associated with a sensor. More...

const char *	SDL::GetSensorName (SensorParam sensor)
	Get the implementation dependent name of a sensor. More...

SensorType	SDL::GetSensorType (SensorParam sensor)
	Get the type of a sensor. More...

int	SDL::GetSensorNonPortableType (SensorParam sensor)
	Get the platform dependent type of a sensor. More...

SensorID	SDL::GetSensorID (SensorParam sensor)
	Get the instance ID of a sensor. More...

void	SDL::GetSensorData (SensorParam sensor, float *data, int num_values)
	Get the current state of an opened sensor. More...

void	SDL::CloseSensor (SensorRaw sensor)
	Close a sensor previously opened with Sensor.Sensor(). More...

void	SDL::UpdateSensors ()
	Update the current state of the open sensors. More...

PropertiesRef	SDL::Sensor::GetProperties ()
	Get the properties associated with a sensor. More...

const char *	SDL::Sensor::GetName ()
	Get the implementation dependent name of a sensor. More...

SensorType	SDL::Sensor::GetType ()
	Get the type of a sensor. More...

int	SDL::Sensor::GetNonPortableType ()
	Get the platform dependent type of a sensor. More...

SensorID	SDL::Sensor::GetID ()
	Get the instance ID of a sensor. More...

void	SDL::Sensor::GetData (float *data, int num_values)
	Get the current state of an opened sensor. More...

void	SDL::Sensor::Close ()
	Close a sensor previously opened with Sensor.Sensor(). More...

Variables
constexpr SensorType	SDL::SENSOR_INVALID
	Returned for an invalid sensor. More...

constexpr SensorType	SDL::SENSOR_UNKNOWN
	Unknown sensor type. More...

constexpr SensorType	SDL::SENSOR_ACCEL = SDL_SENSOR_ACCEL
	Accelerometer.

constexpr SensorType	SDL::SENSOR_GYRO = SDL_SENSOR_GYRO
	Gyroscope.

constexpr SensorType	SDL::SENSOR_ACCEL_L = SDL_SENSOR_ACCEL_L
	Accelerometer for left Joy-Con controller and Wii nunchuk.

constexpr SensorType	SDL::SENSOR_GYRO_L
	Gyroscope for left Joy-Con controller. More...

constexpr SensorType	SDL::SENSOR_ACCEL_R
	Accelerometer for right Joy-Con controller. More...

constexpr SensorType	SDL::SENSOR_GYRO_R
	Gyroscope for right Joy-Con controller. More...

constexpr SensorType	SDL::SENSOR_COUNT = SDL_SENSOR_COUNT
	SENSOR_COUNT.

constexpr float	SDL::STANDARD_GRAVITY = SDL_STANDARD_GRAVITY
	A constant to represent standard gravity for accelerometer sensors. More...

Detailed Description

These APIs grant access to gyros and accelerometers on various platforms.

In order to use these functions, Init() must have been called with the INIT_SENSOR flag. This causes SDL to scan the system for sensors, and load appropriate drivers.

Typedef Documentation

◆ SensorID

using SDL::SensorID = typedef Uint32

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

◆ SensorType

using SDL::SensorType = typedef SDL_SensorType

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 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.

Since: This enum is available since SDL 3.2.0.

See also: Display.GetCurrentOrientation

Function Documentation

◆ Close()

void SDL::Sensor::Close ( )

inline

Since: This function is available since SDL 3.2.0.

◆ CloseSensor()

void SDL::CloseSensor ( SensorRaw sensor )

inline

Parameters

sensor the Sensor object to close.

Since: This function is available since SDL 3.2.0.

◆ GetData()

void SDL::Sensor::GetData	(	float *	data,
		int	num_values
	)

inline

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

Parameters

data	a pointer filled with the current sensor state.
num_values	the number of values to write to data.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetID()

SensorID SDL::Sensor::GetID ( )

inline

Returns: the sensor instance ID, or 0 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetName()

const char * SDL::Sensor::GetName ( )

inline

Returns: the sensor name or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetNonPortableType()

int SDL::Sensor::GetNonPortableType ( )

inline

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

Since: This function is available since SDL 3.2.0.

◆ GetProperties()

PropertiesRef SDL::Sensor::GetProperties ( )

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetSensorData()

void SDL::GetSensorData	(	SensorParam	sensor,
		float *	data,
		int	num_values
	)

inline

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

Parameters

sensor	the Sensor object to query.
data	a pointer filled with the current sensor state.
num_values	the number of values to write to data.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetSensorFromID()

SensorRef SDL::GetSensorFromID ( SensorID instance_id )

inline

Parameters

instance_id the sensor instance ID.

Returns: an Sensor object or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetSensorID()

SensorID SDL::GetSensorID ( SensorParam sensor )

inline

Parameters

sensor the Sensor object to inspect.

Returns: the sensor instance ID, or 0 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetSensorName()

const char * SDL::GetSensorName ( SensorParam sensor )

inline

Parameters

sensor the Sensor object.

Returns: the sensor name or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetSensorNameForID()

const char * SDL::GetSensorNameForID ( SensorID instance_id )

inline

This can be called before any sensors are opened.

Parameters

instance_id the sensor instance ID.

Returns: the sensor name, or nullptr if instance_id is not valid.

Since: This function is available since SDL 3.2.0.

◆ GetSensorNonPortableType()

int SDL::GetSensorNonPortableType ( SensorParam sensor )

inline

Parameters

sensor the Sensor object to inspect.

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

Since: This function is available since SDL 3.2.0.

◆ GetSensorNonPortableTypeForID()

int SDL::GetSensorNonPortableTypeForID ( SensorID instance_id )

inline

This can be called before any sensors are opened.

Parameters

instance_id the 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.2.0.

◆ GetSensorProperties()

PropertiesRef SDL::GetSensorProperties ( SensorParam sensor )

inline

Parameters

sensor the Sensor object.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetSensors()

OwnArray< SensorID > SDL::GetSensors ( )

inline

Returns: a 0 terminated array of sensor instance IDs or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ GetSensorType()

SensorType SDL::GetSensorType ( SensorParam sensor )

inline

Parameters

sensor the Sensor object to inspect.

Returns: the SensorType type, or SENSOR_INVALID if sensor is nullptr.

Since: This function is available since SDL 3.2.0.

◆ GetSensorTypeForID()

SensorType SDL::GetSensorTypeForID ( SensorID instance_id )

inline

This can be called before any sensors are opened.

Parameters

instance_id the sensor instance ID.

Returns: the SensorType, or SENSOR_INVALID if instance_id is not valid.

Since: This function is available since SDL 3.2.0.

◆ GetType()

SensorType SDL::Sensor::GetType ( )

inline

Returns: the SensorType type, or SENSOR_INVALID if sensor is nullptr.

Since: This function is available since SDL 3.2.0.

◆ OpenSensor()

Sensor SDL::OpenSensor ( SensorID instance_id )

inline

Parameters

instance_id the sensor instance ID.

Returns: an Sensor object or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ UpdateSensors()

void SDL::UpdateSensors ( )

inline

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.2.0.

SDL_SENSOR_UNKNOWN

◆ STANDARD_GRAVITY

constexpr float SDL::STANDARD_GRAVITY = SDL_STANDARD_GRAVITY

constexpr

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 STANDARD_GRAVITY away from the center of the earth, which is a positive Y value.

Since: This constant is available since SDL 3.2.0.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ SensorID

◆ SensorType

Function Documentation

◆ Close()

◆ CloseSensor()

◆ GetData()

◆ GetID()

◆ GetName()

◆ GetNonPortableType()

◆ GetProperties()

◆ GetSensorData()

◆ GetSensorFromID()

◆ GetSensorID()

◆ GetSensorName()

◆ GetSensorNameForID()

◆ GetSensorNonPortableType()

◆ GetSensorNonPortableTypeForID()

◆ GetSensorProperties()

◆ GetSensors()

◆ GetSensorType()

◆ GetSensorTypeForID()

◆ GetType()

◆ OpenSensor()

◆ UpdateSensors()

Variable Documentation

◆ SENSOR_ACCEL_R

◆ SENSOR_GYRO_L

◆ SENSOR_GYRO_R

◆ SENSOR_INVALID

◆ SENSOR_UNKNOWN

◆ STANDARD_GRAVITY