Tizen Native API  6.5

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]handleA gesture handle
[in]errorAn 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]msgAn error message from gesture engine service
[in]user_dataThe 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]handleA gesture handle
[in]gestureA gesture type detected
[in]timestampThe time when the gesture is detected. Epoch time in seconds.
[in]errorAn 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_dataThe user data is passed to hand_gesture_start_recognition()
See also:
hand_gesture_start_recognition()

Enumeration Type Documentation

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

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

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

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]handleA gesture handle
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDNot supported
HAND_GESTURE_ERROR_PERMISSION_DENIEDPermission denied
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter
HAND_GESTURE_ERROR_OUT_OF_MEMORYOut of memory
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation failed
See also:
hand_gesture_destroy()

Destroys a gesture handle.

Since :
6.0
Parameters:
[in]handleA gesture handle
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDNot supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation 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]handleA gesture handle
[out]engine_app_idA gesture engine app ID
[out]engine_nameA gesture engine name
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation 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]handleA gesture handle
[in]gestureA gesture type to be checked
[out]supportedtrue 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_NONESupported
HAND_GESTURE_ERROR_NOT_SUPPORTEDThe gesture is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation 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]handleA gesture handle
[in]callbackA callback function invoked when an error is occurred
[in]user_dataA user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
See also:
hand_gesture_error_cb()
hand_gesture_unset_error_cb()

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]handleA gesture handle used to control the gesture event
[in]optionAn option for detecting gestures
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation 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]handleA gesture handle used to control the gesture event
[in]gestureA gesture type to be monitored
[in]callbackA callback function to receive gesture events
[in]user_dataA user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_PERMISSION_DENIEDPermission denied
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_ALREADY_STARTEDThe handle is being used already
HAND_GESTURE_ERROR_OUT_OF_MEMORYOut of memory
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation 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()

Stops recognizing the gesture registered to the gesture handle.

Since :
6.0
Parameters:
[in]handleA gesture handle
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_NOT_STARTEDNothing is started using the handle
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error

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

Since :
6.0
Parameters:
[in]handleA gesture handle
Returns:
0 on success, otherwise a negative error value
Return values:
HAND_GESTURE_ERROR_NONESuccessful
HAND_GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
HAND_GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
HAND_GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
See also:
hand_gesture_set_error_cb()