The Gesture API provides functions for recognizing hand gestures from input sensor data.

Required Header

#include <gesture.h>

Overview

You can use Gesture API to recognize a user's hand movement. Applications can start and stop recognizing hand gestures and receive the corresponding results with the registered callback function. To use Gesture, follow these steps:
1. Create a handle
2. Set options such as a hand type, a work mode, and other options necessary to recognize hand gestures
3. Start recognizing hand gestures
4. Stop recognizing
5. Destroy a handle
The Gesture API also notifies you (by callback mechanism) when the input gesture is recognized. An application should register a callback function to receive the recognized results with hand_gesture_start_recognition().

Related Features

This API is related with the following features:

http://tizen.org/feature/sensor.gesture_recognition
It is recommended to design feature related codes 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	hand_gesture_is_supported_type (hand_gesture_h handle, hand_gesture_type_e gesture, bool *supported)
	Checks whether a gesture is supported or not.
int	hand_gesture_create (hand_gesture_h *handle)
	Creates a gesture handle.
int	hand_gesture_destroy (hand_gesture_h handle)
	Destroys a gesture handle.
int	hand_gesture_set_option (hand_gesture_h handle, hand_gesture_option_e option)
	Sets an option for gesture recognition.
int	hand_gesture_start_recognition (hand_gesture_h handle, hand_gesture_type_e gesture, hand_gesture_recognition_cb callback, void *user_data)
	Starts to recognize a gesture.
int	hand_gesture_stop_recognition (hand_gesture_h handle)
	Stops recognizing the gesture registered to the gesture handle.
int	hand_gesture_get_engine_info (hand_gesture_h handle, char engine_app_id, char engine_name)
	Gets a gesture engine information.
int	hand_gesture_set_error_cb (hand_gesture_h handle, hand_gesture_error_cb callback, void *user_data)
	Sets a callback function to be invoked when an error is occurred.
int	hand_gesture_unset_error_cb (hand_gesture_h handle)
	Unsets a callback function to be invoked when an error is occurred.
Typedefs
typedef struct hand_gesture_s *	hand_gesture_h
	The hand gesture handle.
typedef void(*	hand_gesture_recognition_cb )(hand_gesture_h handle, hand_gesture_type_e gesture, double timestamp, hand_gesture_error_e error, void *user_data)
	Called when a gesture is detected.
typedef void(*	hand_gesture_error_cb )(hand_gesture_h handle, hand_gesture_error_e error, const char msg, void user_data)
	Called when an error is occurred.
typedef struct hand_gesture_data_s *	hand_gesture_data_h
	Delivery through hand_gesture_recognition_cb() of gesture data handle.

Typedef Documentation

typedef struct hand_gesture_data_s* hand_gesture_data_h

Delivery through hand_gesture_recognition_cb() of gesture data handle.

Since :: 6.0

typedef void(* hand_gesture_error_cb)(hand_gesture_h handle, hand_gesture_error_e error, const char *msg, void *user_data)

Called when an error is occurred.

Following error codes can be delivered:
HAND_GESTURE_ERROR_INVALID_PARAMETER,
HAND_GESTURE_ERROR_INVALID_OPERATION,
HAND_GESTURE_ERROR_OUT_OF_MEMORY,
HAND_GESTURE_ERROR_OPERATION_FAILED

Since :: 6.0

Remarks:: The handle is the same object for which the callback was set. The handle is available until hand_gesture_destroy() is called. The msg is managed by the platform and will be released when invoking this callback function is finished.

Parameters:

[in]	handle	A gesture handle
[in]	error	An error value. It can be one of the following error values: HAND_GESTURE_ERROR_INVALID_PARAMETER, HAND_GESTURE_ERROR_INVALID_OPERATION, HAND_GESTURE_ERROR_OUT_OF_MEMORY, HAND_GESTURE_ERROR_OPERATION_FAILED
[in]	msg	An error message from gesture engine service
[in]	user_data	The user data is passed to hand_gesture_set_error_cb()

See also:: hand_gesture_set_error_cb(); hand_gesture_unset_error_cb()

typedef struct hand_gesture_s* hand_gesture_h

The hand gesture handle.

Since :: 6.0

typedef void(* hand_gesture_recognition_cb)(hand_gesture_h handle, hand_gesture_type_e gesture, double timestamp, hand_gesture_error_e error, void *user_data)

Called when a gesture is detected.

Following error codes can be delivered:
HAND_GESTURE_ERROR_NONE,
HAND_GESTURE_ERROR_NOT_SUPPORTED,
HAND_GESTURE_ERROR_INVALID_PARAMETER,
HAND_GESTURE_ERROR_OPERATION_FAILED

Since :: 6.0

Remarks:: The handle is managed by the platform and will be released when hand_gesture_destroy() is called.

Parameters:

[in]	handle	A gesture handle
[in]	gesture	A gesture type detected
[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: HAND_GESTURE_ERROR_NONE, if the operation succeeded. HAND_GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported on the device. HAND_GESTURE_ERROR_INVALID_PARAMETER, if the parameter is invalid. HAND_GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
[in]	user_data	The user data is passed to hand_gesture_start_recognition()

See also:: hand_gesture_start_recognition()

Enumeration Type Documentation

enum hand_gesture_error_e

Enumerations for hand gesture function error.

Since :: 6.0

Enumerator:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid function parameter
HAND_GESTURE_ERROR_INVALID_OPERATION	Function not implemented
HAND_GESTURE_ERROR_OUT_OF_MEMORY	Out of memory
HAND_GESTURE_ERROR_PERMISSION_DENIED	Permission denied
HAND_GESTURE_ERROR_ALREADY_STARTED	Recognition is already started
HAND_GESTURE_ERROR_NOT_STARTED	Recognition is not started
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

enum hand_gesture_option_e

Enumerations 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 HAND_GESTURE_OPTION_ALWAYS_ON disables such power-saving functionalities.

Since :: 6.0

Enumerator:

HAND_GESTURE_OPTION_DEFAULT	Running in the default setting
HAND_GESTURE_OPTION_ALWAYS_ON	Trying to detect gestures always

enum hand_gesture_type_e

Enumerations for hand gesture types.

Since :: 6.0

Enumerator:

HAND_GESTURE_NONE	Nothing type
HAND_GESTURE_WRIST_UP	The wearable device is moved and faced up

Function Documentation

int hand_gesture_create ( hand_gesture_h * handle )

Creates a gesture handle.

Since :: 6.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch

Remarks:: If the function succeeds, handle must be released with hand_gesture_destroy().

Parameters:

[out] handle A gesture handle

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Not supported
HAND_GESTURE_ERROR_PERMISSION_DENIED	Permission denied
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter
HAND_GESTURE_ERROR_OUT_OF_MEMORY	Out of memory
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed

See also:: hand_gesture_destroy()

int hand_gesture_destroy ( hand_gesture_h handle )

Destroys a gesture handle.

Since :: 6.0

Parameters:

[in] handle A gesture handle

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed

See also:: hand_gesture_create()

int hand_gesture_get_engine_info	(	hand_gesture_h	handle,
		char **	engine_app_id,
		char **	engine_name
	)

Gets a gesture engine information.

Since :: 6.0

Remarks:: The engine_app_id and the engine_name should be released using free().

Parameters:

[in]	handle	A gesture handle
[out]	engine_app_id	A gesture engine app ID
[out]	engine_name	A gesture engine name

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

int hand_gesture_is_supported_type	(	hand_gesture_h	handle,
		hand_gesture_type_e	gesture,
		bool *	supported
	)

Checks whether a gesture is supported or not.

Check if the given gesture type is supported on the device.

Since :: 6.0

Parameters:

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

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

Return values:

HAND_GESTURE_ERROR_NONE	Supported
HAND_GESTURE_ERROR_NOT_SUPPORTED	The `gesture` is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

int hand_gesture_set_error_cb	(	hand_gesture_h	handle,
		hand_gesture_error_cb	callback,
		void *	user_data
	)

Sets a callback function to be invoked when an error is occurred.

Since :: 6.0

Parameters:

[in]	handle	A gesture handle
[in]	callback	A callback function invoked when an error is occurred
[in]	user_data	A user data to be passed to the callback function

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

See also:: hand_gesture_error_cb(); hand_gesture_unset_error_cb()

int hand_gesture_set_option	(	hand_gesture_h	handle,
		hand_gesture_option_e	option
	)

Sets an option for gesture recognition.

Since :: 6.0

Remarks:: If you would like to set a gesture option, you should call this function before hand_gesture_start_recognition() is invoked.
If you do not call this function, HAND_GESTURE_OPTION_DEFAULT will be set as the default option.

Parameters:

[in]	handle	A gesture handle used to control the gesture event
[in]	option	An option for detecting gestures

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

See also:: hand_gesture_start_recognition()

int hand_gesture_start_recognition	(	hand_gesture_h	handle,
		hand_gesture_type_e	gesture,
		hand_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 :: 6.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch

Parameters:

[in]	handle	A gesture handle used to control the gesture event
[in]	gesture	A gesture type to be monitored
[in]	callback	A callback function to receive gesture events
[in]	user_data	A user data to be passed to the callback function

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_PERMISSION_DENIED	Permission denied
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_ALREADY_STARTED	The `handle` is being used already
HAND_GESTURE_ERROR_OUT_OF_MEMORY	Out of memory
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

Precondition:: hand_gesture_create(); hand_gesture_set_option()

Postcondition:: hand_gesture_recognition_cb()

See also:: hand_gesture_stop_recognition()

int hand_gesture_stop_recognition ( hand_gesture_h handle )

Stops recognizing the gesture registered to the gesture handle.

Since :: 6.0

Parameters:

[in] handle A gesture handle

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_NOT_STARTED	Nothing is started using the `handle`
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

int hand_gesture_unset_error_cb ( hand_gesture_h handle )

Unsets a callback function to be invoked when an error is occurred.

Since :: 6.0

Parameters:

[in] handle A gesture handle

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

Return values:

HAND_GESTURE_ERROR_NONE	Successful
HAND_GESTURE_ERROR_NOT_SUPPORTED	Gesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETER	Invalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILED	Operation failed because of a system error

See also:: hand_gesture_set_error_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation