The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SDL2-FFI-0.08
River stage zero No dependents
2 ++
/ SDL2::sensor

NAME

SDL2::sensor - SDL Sensor Event Handling

SYNOPSIS

    use SDL2 qw[:sensor];

DESCRIPTION

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

Functions

You may import these by name or with the :sensor tag.

SDL_LockSensors( )

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.

SDL_UnlockSensors( )

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

SDL_NumSensors( )

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

Returns the number of sensors detected.

SDL_SensorGetDeviceName( ... )

Get the implementation dependent name of a sensor.

Expected parameters include:

device_index - the sensor to obtain name from

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

SDL_SensorGetDeviceType( ... )

Get the type of a sensor.

Expected parameters include:

device_index - the sensor to get the type from

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

SDL_SensorGetDeviceNonPortableType( ... )

Get the platform dependent type of a sensor.

Expected parameters include:

device_index - the sensor to check

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

SDL_SensorGetDeviceInstanceID( ... )

Get the instance ID of a sensor.

Expected parameters include:

device_index - the sensor to get instance id from

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

SDL_SensorOpen( ... )

Open a sensor for use.

Expected parameters include:

device_index - the sensor to open

Returns an SDL2::Sensor sensor object, or undef if an error occurred.

SDL_SensorFromInstanceID( ... )

Return the SDL_Sensor associated with an instance id.

Expected parameters include:

instance_id - the sensor from instance id

Returns an SDL2::Sensor object.

SDL_SensorGetName( ... )

Get the implementation dependent name of a sensor

Expected parameters include:

sensor - the SDL2::Sensor object

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

SDL_SensorGetType( ... ) /** * Get the type of a sensor.

Expected parameters include:

sensor - the SDL2::Sensor object to inspect

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

SDL_SensorGetNonPortableType( ... )

Get the platform dependent type of a sensor.

Expected parameters include:

sensor - the SDL2::Sensor object to inspect

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

SDL_SensorGetInstanceID( ... )

Get the instance ID of a sensor.

Expected parameters include:

sensor - the SDL2::Sensor object to inspect

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

SDL_SensorGetData( ... )

Get the current state of an opened sensor.

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

Expected parameters include:

sensor - the SDL2::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.

SDL_SensorClose( ... )

Close a sensor previously opened with SDL_SensorOpen( ... ).

Expected parameters include:

sensor - the SDL2::Sensor object to close

SDL_SensorUpdate( )

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.

Defined Types, Values, and Enumerations

These may be imported by name or with the :sensor tag.

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.

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

SDL_SENSOR_INVALID - Returned for an invalid sensor
SDL_SENSOR_UNKNOWN - Unknown sensor type
SDL_SENSOR_ACCEL - Accelerometer
SDL_SENSOR_GYRO - Gyroscope

SDL_STANDARD_GRAVITY

This is the standard value for gravitational acceleration.

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.

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.

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>