SDL sensor management. More...

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

Typedefs
using	SDL::SensorRaw = SDL_Sensor*
	Alias to raw representation for Sensor.
using	SDL::SensorRef = ResourceRef<Sensor>
	Reference 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.
using	SDL::SensorType = SDL_SensorType
	The different sensors defined by SDL.

Functions
OwnArray< SensorID >	SDL::GetSensors ()
	Get a list of currently connected sensors.
const char *	SDL::GetSensorNameForID (SensorID instance_id)
	Get the implementation dependent name of a sensor.
SensorType	SDL::GetSensorTypeForID (SensorID instance_id)
	Get the type of a sensor.
int	SDL::GetSensorNonPortableTypeForID (SensorID instance_id)
	Get the platform dependent type of a sensor.
Sensor	SDL::OpenSensor (SensorID instance_id)
	Open a sensor for use.
SensorRef	SDL::GetSensorFromID (SensorID instance_id)
	Return the Sensor associated with an instance ID.
PropertiesRef	SDL::GetSensorProperties (SensorRef sensor)
	Get the properties associated with a sensor.
const char *	SDL::GetSensorName (SensorRef sensor)
	Get the implementation dependent name of a sensor.
SensorType	SDL::GetSensorType (SensorRef sensor)
	Get the type of a sensor.
int	SDL::GetSensorNonPortableType (SensorRef sensor)
	Get the platform dependent type of a sensor.
SensorID	SDL::GetSensorID (SensorRef sensor)
	Get the instance ID of a sensor.
void	SDL::GetSensorData (SensorRef sensor, float *data, int num_values)
	Get the current state of an opened sensor.
void	SDL::CloseSensor (SensorRaw sensor)
	Close a sensor previously opened with OpenSensor().
void	SDL::UpdateSensors ()
	Update the current state of the open sensors.
	SDL::Sensor::Sensor (SensorID instance_id)
	Open a sensor for use.
PropertiesRef	SDL::Sensor::GetProperties ()
	Get the properties associated with a sensor.
const char *	SDL::Sensor::GetName ()
	Get the implementation dependent name of a sensor.
SensorType	SDL::Sensor::GetType ()
	Get the type of a sensor.
int	SDL::Sensor::GetNonPortableType ()
	Get the platform dependent type of a sensor.
SensorID	SDL::Sensor::GetID ()
	Get the instance ID of a sensor.
void	SDL::Sensor::GetData (float *data, int num_values)
	Get the current state of an opened sensor.
void	SDL::Sensor::Close ()
	Close a sensor previously opened with OpenSensor().

Variables
constexpr SensorType	SDL::SENSOR_INVALID
	Returned for an invalid sensor.
constexpr SensorType	SDL::SENSOR_UNKNOWN
	Unknown sensor type.
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.
constexpr SensorType	SDL::SENSOR_ACCEL_R
	Accelerometer for right Joy-Con controller.
constexpr SensorType	SDL::SENSOR_GYRO_R
	Gyroscope for right Joy-Con controller.
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.

Detailed Description

SDL sensor management.

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

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

◆ SensorRef

using SDL::SensorRef = ResourceRef<Sensor>

Reference for Sensor.

This does not take ownership!

◆ SensorType

using SDL::SensorType = 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 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

Close a sensor previously opened with OpenSensor().

Since: This function is available since SDL 3.2.0.

◆ CloseSensor()

void SDL::CloseSensor ( SensorRaw sensor )

inline

Close a sensor previously opened with OpenSensor().

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

Get the current state of an opened sensor.

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

Get the instance ID of a sensor.

Returns: the sensor instance ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetName()

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

inline

Get the implementation dependent name of a sensor.

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

Get the platform dependent type of a sensor.

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

Get the properties associated with a sensor.

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	(	SensorRef	sensor,
		float *	data,
		int	num_values )

inline

Get the current state of an opened sensor.

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

Return the Sensor associated with an instance ID.

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 ( SensorRef sensor )

inline

Get the instance ID of a sensor.

Parameters

sensor the Sensor object to inspect.

Returns: the sensor instance ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetSensorName()

const char * SDL::GetSensorName ( SensorRef sensor )

inline

Get the implementation dependent name of a sensor.

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

Get the implementation dependent name of a sensor.

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 ( SensorRef sensor )

inline

Get the platform dependent type of a sensor.

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

Get the platform dependent type of a sensor.

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 ( SensorRef sensor )

inline

Get the properties associated with a sensor.

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

Get a list of currently connected sensors.

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 ( SensorRef sensor )

inline

Get the type of a sensor.

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

Get the type of a sensor.

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

Get the type of a sensor.

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

Open a sensor for use.

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.

◆ Sensor()

SDL::Sensor::Sensor ( SensorID instance_id )

inline

Open a sensor for use.

Parameters

instance_id the sensor instance ID.

Postcondition: 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

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

Unknown sensor type.

◆ STANDARD_GRAVITY

float SDL::STANDARD_GRAVITY = SDL_STANDARD_GRAVITY

constexpr

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

◆ SensorRef

◆ SensorType

Function Documentation

◆ Close()

◆ CloseSensor()

◆ GetData()

◆ GetID()

◆ GetName()

◆ GetNonPortableType()

◆ GetProperties()

◆ GetSensorData()

◆ GetSensorFromID()

◆ GetSensorID()

◆ GetSensorName()

◆ GetSensorNameForID()

◆ GetSensorNonPortableType()

◆ GetSensorNonPortableTypeForID()

◆ GetSensorProperties()

◆ GetSensors()

◆ GetSensorType()

◆ GetSensorTypeForID()

◆ GetType()

◆ OpenSensor()

◆ Sensor()

◆ UpdateSensors()

Variable Documentation

◆ SENSOR_ACCEL_R

◆ SENSOR_GYRO_L

◆ SENSOR_GYRO_R

◆ SENSOR_INVALID

◆ SENSOR_UNKNOWN

◆ STANDARD_GRAVITY