The gesture recognition API allows applications to be notified and react when the user performs a gesture.

Required Header

#include <gesture_recognition.h>

Overview

The gesture recognition API allows to register callback functions to be called when the user performs meaningful gestures listed in gesture_type_e, for example, shaking the device.

Regardless of the gesture types, the overall process of using the gesture recognition API is as follows.

If necessary, applications can check whether a gesture type is supported in the current device in advance. Note that, some gestures may not be supported in some devices, if the devices do not have necessary sensors.

    bool supported = false;
    gesture_is_supported(GESTURE_SHAKE, &supported);

    if (!supported) {
        // Not supported in the current device.
    }

If the gesture type is supported, to use the recognition engine, an handle for the gesture recognition needs to be initialized first.

    gesture_h handle;

    result = gesture_create(&handle);

    if (result != GESTURE_ERROR_NONE) {
        // An error occurred.
    }

With the handle initialized, a callback function, which will be called when a specified gesture is detected, is registered by using gesture_start_recognition().

    result = gesture_start_recognition(handle, GESTURE_SHAKE, GESTURE_OPTION_DEFAULT, gesture_cb, NULL);

    if (result != GESTURE_ERROR_NONE) {
        // An error occurred. Do necessary error handling here.
    }

Then the callback function gesture_cb will be called whenever the shake gesture is detected.

Note that, calling gesture_start_recognition() twice on the same handle returns GESTURE_ERROR_ALREADY_STARTED. If it needs to recognize another gesture using the same handle, the started recognition session should be stopped and restarted with the new gesture type. Otherwise, the application needs to created multiple handles, one handle for each gesture needed.

An example callback function is as follows.

    void gesture_cb(gesture_type_e type, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
    {
        int result;
        gesture_event_e event;

        if (error != GESTURE_ERROR_NONE) {
            // An error occurred. Do necessary error handling here.
            return;
        }

        if (type == GESTURE_SHAKE) {
            // More than one gestures can be started using the same callback function.

            result = gesture_get_event(data, &event);

            if (result != GESTURE_ERROR_NONE) {
                // An error occurred. Do necessary error handling here.
                return;
            }

            if (event == GESTURE_SHAKE_DETECTED) {
                // Shake gesture is started

            } else if (event == GESTURE_SHAKE_FINISHED) {
                // Shake gesture is stopped
            }
        }
    }

As we started gesture recognition with GESTURE_SHAKE, gesture_get_event() returns either GESTURE_SHAKE_DETECTED or GESTURE_SHAKE_FINISHED as it has two different states, the gesture is started, or finished. Most of the gesture types, however, simply provide GESTURE_EVENT_DETECTED. In such cases, GESTURE_EVENT_NONE may not be delivered at all.

If GESTURE_TILT is started, within the callback function, gesture_get_tilt() can be used to extract the tilting degrees.

Finally, if the application does not need to be notified the gesture event, it can be stopped as follows.

    gesture_stop_recognition(handle);

    // If the handle will not be used anymore, its resources needs be released explicitly.
    gesture_release(handle);

Related Features

This API is related with the following features:

It is recommended to design feature related code in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions
int	gesture_is_supported (gesture_type_e gesture, bool *supported)
	Check whether the gesture is supported or not.
int	gesture_create (gesture_h *handle)
	Initializes a gesture handle.
int	gesture_release (gesture_h handle)
	Releases the resources occupied by the gesture handle.
int	gesture_start_recognition (gesture_h handle, gesture_type_e gesture, gesture_option_e option, gesture_recognition_cb callback, void *user_data)
	Starts to recognize a gesture.
int	gesture_stop_recognition (gesture_h handle)
	Stops recognizing the gesture registered to the gesture handle.
int	gesture_get_event (const gesture_data_h data, gesture_event_e *event)
	Gets the gesture event from the gesture data received.
int	gesture_get_tilt (const gesture_data_h data, int x, int y)
	Gets the tilting degrees from GESTURE_TILT data received.
Typedefs
typedef struct _gesture_handle_s *	gesture_h
	The gesture recognizer controlling handle.
typedef struct _gesture_data_s *	gesture_data_h
	Delivery through gesture_recognition_cb() of gesture data handle.
typedef void(*	gesture_recognition_cb )(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
	Called when a gesture is detected.

Typedef Documentation

typedef struct _gesture_data_s* gesture_data_h

Delivery through gesture_recognition_cb() of gesture data handle.

Since :: 2.3

typedef struct _gesture_handle_s* gesture_h

The gesture recognizer controlling handle.

Since :: 2.3

typedef void(* gesture_recognition_cb)(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)

Called when a gesture is detected.

Since :: 2.3

Parameters:

[in]	gesture	Gesture type detected
[in]	data	Detailed information of the detected gesture. gesture_get_event() or gesture_get_tilt() can be used to extract the information from `data`.
[in]	timestamp	The time when the gesture is detected. Epoch time in seconds.
[in]	error	An error value. It can be one of the following error values: GESTURE_ERROR_NONE, if the operation succeeded. GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported in the current profile. GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error. GESTURE_ERROR_PERMISSION_DENIED, if the application has no permission to use this.
[in]	user_data	The user data had passed to gesture_start_recognition()

Precondition:: gesture_start_recognition()

Enumeration Type Documentation

enum gesture_error_e

Enumeration for error codes.

Since :: 2.3

Enumerator:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid function parameter
GESTURE_ERROR_INVALID_OPERATION	Function not implemented
GESTURE_ERROR_OUT_OF_MEMORY	Out of memory
GESTURE_ERROR_PERMISSION_DENIED	Permission denied
GESTURE_ERROR_NOT_SUPPORTED	Not supported
GESTURE_ERROR_ALREADY_STARTED	Recognition is already started
GESTURE_ERROR_NOT_STARTED	Recognition is not started
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

enum gesture_event_e

Enumeration for gesture event types.

With regards to type of the gesture, gesture_get_event() returns one of the followings.

Since :: 2.3

Enumerator:

GESTURE_EVENT_NONE	Detected nothing
GESTURE_EVENT_DETECTED	Detected the gesture
GESTURE_SHAKE_DETECTED	Shake gesture started
GESTURE_SHAKE_FINISHED	Shake gesture stopped
GESTURE_SNAP_X_NEGATIVE	Detected -X snap
GESTURE_SNAP_X_POSITIVE	Detected +X snap
GESTURE_SNAP_Y_NEGATIVE	Detected -Y snap
GESTURE_SNAP_Y_POSITIVE	Detected +Y snap
GESTURE_SNAP_Z_NEGATIVE	Detected -Z snap
GESTURE_SNAP_Z_POSITIVE	Detected +Z snap

enum gesture_option_e

Enumeration for gesture recognition option.

If the default option is used, the system tries to reduce power consumption. For example, the recognition engine may stop detecting gestures if the display is turned off. Using GESTURE_OPTION_ALWAYS_ON disables such power-saving functionalities.

Since :: 2.3

Enumerator:

GESTURE_OPTION_DEFAULT	Running in the default setting
GESTURE_OPTION_ALWAYS_ON	Trying to detect gestures always

enum gesture_type_e

Enumeration for gesture types.

Since :: 2.3

Enumerator:

GESTURE_DOUBLE_TAP	The mobile device is tapped twice
GESTURE_MOVE_TO_EAR	The mobile device is moved near to an ear
GESTURE_NO_MOVE	The mobile device is being stopped for a while
GESTURE_PICK_UP	The mobile device is picked up
GESTURE_SHAKE	The mobile device is quickly moved back and forth
GESTURE_SNAP	The mobile device is moved along an axis and back
GESTURE_TILT	The mobile device is tilted
GESTURE_TURN_FACE_DOWN	The mobile device is flipped from face to back
GESTURE_WRIST_UP	The wearable device is moved and faced up

Function Documentation

int gesture_create ( gesture_h * handle )

Initializes a gesture handle.

Since :: 2.3

Parameters:

[out] handle Gesture handle to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error, e.g., out of memory

See also:: gesture_release()

int gesture_get_event	(	const gesture_data_h	data,
		gesture_event_e *	event
	)

Gets the gesture event from the gesture data received.

Since :: 2.3

Parameters:

[in]	data	Gesture data received through a callback function
[out]	event	Gesture event data

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

int gesture_get_tilt	(	const gesture_data_h	data,
		int *	x,
		int *	y
	)

Gets the tilting degrees from GESTURE_TILT data received.

Since :: 2.3

Parameters:

[in]	data	Tilt gesture data received through a callback function
[out]	x	Tilting degree on X-axis
[out]	y	Tilting degree on Y-axis

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

int gesture_is_supported	(	gesture_type_e	gesture,
		bool *	supported
	)

Check whether the gesture is supported or not.

Check if the given gesture type is supported in the current device.

Since :: 2.3

Parameters:

[in]	gesture	Gesture type to be checked
[out]	supported	`true` if the gesture is recognizable in the current device, `false` otherwise

Returns:: 0 if the gesture is supported, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Supported
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	The `gesture` is not supported
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error
GESTURE_ERROR_PERMISSION_DENIED	Does not have permission to use this

int gesture_release ( gesture_h handle )

Releases the resources occupied by the gesture handle.

Since :: 2.3

Parameters:

[in] handle Gesture handle to be released

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

Precondition:: gesture_create()

int gesture_start_recognition	(	gesture_h	handle,
		gesture_type_e	gesture,
		gesture_option_e	option,
		gesture_recognition_cb	callback,
		void *	user_data
	)

Starts to recognize a gesture.

Sets a callback function to be invoked when the gesture is detected, and starts to monitor occurrences of the gesture.

Since :: 2.3

Parameters:

[in]	handle	Gesture handle to be used to control the gesture event
[in]	gesture	Gesture type to be monitored
[in]	option	Detection option
[in]	callback	Callback function to receive gesture events
[in]	user_data	User data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_ALREADY_STARTED	The `handle` is being used already
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error
GESTURE_ERROR_PERMISSION_DENIED	Does not have permission to use this

Precondition:: gesture_create()

Postcondition:: gesture_recognition_cb()

See also:: gesture_stop_recognition()

int gesture_stop_recognition ( gesture_h handle )

Stops recognizing the gesture registered to the gesture handle.

Since :: 2.3

Parameters:

[in] handle Gesture handle to release its callback function registered

Returns:: 0 on success, otherwise a negative error value

Return values:

GESTURE_ERROR_NONE	Successful
GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
GESTURE_ERROR_NOT_STARTED	Nothing is started using the `handle`
GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation