# Gesture C API

# Gesture C API

The Gesture C API allows clients to recognize touchpad and button gestures from a controller.

## Summary

Disclaimer: This API is experimental and is subject to changes.

If you are writing C++ code, you might prefer to use the C++ wrapper rather than implement this C API directly.

If you are using multiple controllers, you will need to create multiple gvr_gesture_context objects, one for each controller.

Example API usage:

Initialization:

```
// Create the gesture context.
gvr_gesture_context* context = gvr_gesture_context_create();
```

<br />

Usage:

```
// Get the controller state from client.
gvr_controller_state* controller_state = ...

// Detect the gestures.
gvr_gesture_update(context, controller_state);

// Get the number of detected gestures.
int num_gestures = gvr_gesture_get_count(context);

for (int i = 0; i < num_gestures; i ++) {
  gvr_gesture* gesture_ptr = gvr_gesture_get(context, i);
  switch (gvr_gesture_get_type(gesture_ptr)) {
    case GVR_GESTURE_SWIPE:
      // Handle swipe gesture.
      break;
    case GVR_GESTURE_SCROLL_START:
      // Handle the start of a sequence of scroll gestures.
      break;
    case GVR_GESTURE_SCROLL_UPDATE:
      // Handle an update in a sequence of scroll gestures.
      break;
    case GVR_GESTURE_SCROLL_END:
      // Handle the end of a sequence of scroll gestures.
      break;
    default:
      // Unexpected gesture type.
      break;
   }
}
```

<br />

| ### Enumerations ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gaae634fdca873e59114514c1c34b134fa{ https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ggaae634fdca873e59114514c1c34b134faa1151e364560e5d63459f1caa07f7c468 = 1, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ggaae634fdca873e59114514c1c34b134faa6aa83e2e3174eb32e85d8fe1845c618c = 2, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ggaae634fdca873e59114514c1c34b134faa2369b5566d8695bd2e0ea3dd0fb6527b = 3, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ggaae634fdca873e59114514c1c34b134faa980e109d90bf25b1a8ba7ff7dd9d8cb3 = 4 }` | enumGesture directions. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f2394469b17860e95412cd19603a90f{ https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gga6f2394469b17860e95412cd19603a90fa2031c472c5b68fca2cd2102c439f2252 = 1, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gga6f2394469b17860e95412cd19603a90fa4dfaf0f6c254f0442d2b40d49af7c58c = 2, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gga6f2394469b17860e95412cd19603a90fa2359e986d96177216a93c7b13d115b48 = 3, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gga6f2394469b17860e95412cd19603a90fad3b550a10cf906e3772a7e3d6062e3af = 4 }` | enumGesture types. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3` | typedef `struct gvr_gesture_` Opaque handle to gesture. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0` | typedef `struct gvr_gesture_context_` Opaque handle to gesture context. |

| ### Functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga263fc3f9e951200f4527df01a9bf3493()` | `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *` Creates and initializes a gesture context instance which can be used to invoke the gesture API functions. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gafbd4908686345284c067c61f82919c1f(https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 **context)` | `void` Destroys the gesture context. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gab6156f8925dbe3027318f2b56e585d00(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *context, int index)` | `const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3 *` Returns the gesture with the given index. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga22c6de4d7013d5ff69a9d33ff7b48236(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *context)` | `int` Returns the number of gestures detected in previous [gvr_gesture_update()](https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga828a68be30e6eaa9e9af9b364ce340e0). |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gafe4d1fe96bfcfc7ab2bec78e52515c05(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3 *gesture)` | `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gaae634fdca873e59114514c1c34b134fa` Returns the direction (up/down/left/right) of given gesture. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga12088254c858dec5c56cc9200ecf13fd(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3 *gesture)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-vec2f#structgvr__vec2f` Returns the displacement (in touchpad unit) of given gesture. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga4152d41c83571b02de3ff7ac2267bd58(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3 *gesture)` | `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f2394469b17860e95412cd19603a90f` Returns the type (swipe/scroll_start/scroll_update/scroll_end) of given gesture. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga0d88077725148a2c02935f592d5c439f(const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga6f0bfd2d87e96ce0d9eda948879956c3 *gesture)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-vec2f#structgvr__vec2f` Returns the velocity (in normalized distance / second) of the given gesture, where (0,0) is the top-left of the touchpad and (1,1) is the bottom right. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga38867fb99c76a629bc1e93093da725b0(https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *context)` | `void` Restarts gesture detection. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga828a68be30e6eaa9e9af9b364ce340e0(const gvr_controller_state *controller_state, https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *context)` | `void` Updates the gesture context based on controller state. |
| `https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga11eb904fbd0a3c9982fec9ba73437b70(const gvr_controller_state *controller_state, const https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga9ddc2588d09c6a443b00c3f1541b1fd0 *context, https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga25a81f172e4de5c794b8f3ddb6194f41 button)` | `bool` Returns whether a long press on controller button has been detected. |

## Enumerations

### gvr_gesture_direction

```
 gvr_gesture_direction
```
Gesture directions.

| Properties ||
|---|---|
| `GVR_GESTURE_DIRECTION_DOWN` | Finger moves down on the touch pad. |
| `GVR_GESTURE_DIRECTION_LEFT` | Finger moves left on the touch pad. |
| `GVR_GESTURE_DIRECTION_RIGHT` | Finger moves right on the touch pad. |
| `GVR_GESTURE_DIRECTION_UP` | Finger moves up on the touch pad. |

### gvr_gesture_type

```
 gvr_gesture_type
```
Gesture types.

| Properties ||
|---|---|
| `GVR_GESTURE_SCROLL_END` | Finger stops scrolling. This is a transient state that is only true for a single frame. |
| `GVR_GESTURE_SCROLL_START` | Finger starts scrolling on touch pad. This is a transient state that is only true for a single frame. |
| `GVR_GESTURE_SCROLL_UPDATE` | Finger is in the process of scrolling. |
| `GVR_GESTURE_SWIPE` | Finger moves quickly across the touch pad. This is a transient state that is only true for a single frame. |

## Typedefs

### gvr_gesture

```
struct gvr_gesture_ gvr_gesture
```
Opaque handle to gesture.

### gvr_gesture_context

```
struct gvr_gesture_context_ gvr_gesture_context
```
Opaque handle to gesture context.

## Functions

### gvr_gesture_context_create

```
gvr_gesture_context * gvr_gesture_context_create()
```
Creates and initializes a gesture context instance which can be used to invoke the gesture API functions.

<br />

| Details ||
|---|---|
| **Returns** | A pointer to the created gesture context instance. |

### gvr_gesture_context_destroy

```
void gvr_gesture_context_destroy(
  gvr_gesture_context **context
)
```
Destroys the gesture context.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | A pointer to a pointer to the gesture context instance. The pointer will be set to null after destruction. | |

### gvr_gesture_get

```
const gvr_gesture * gvr_gesture_get(
  const gvr_gesture_context *context,
  int index
)
```
Returns the gesture with the given index.

The returned pointer remains valid only until the list is modified i.e. by calling [gvr_gesture_update()](https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga828a68be30e6eaa9e9af9b364ce340e0) or [gvr_gesture_context_destroy()](https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1gafbd4908686345284c067c61f82919c1f).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | A pointer to the gesture context instance. | | `index` | The index of the gesture to be returned. | |
| **Returns** | A pointer to the gesture instance at the given index. |

### gvr_gesture_get_count

```
int gvr_gesture_get_count(
  const gvr_gesture_context *context
)
```
Returns the number of gestures detected in previous [gvr_gesture_update()](https://developers.google.com/vr/reference/android-ndk/group/gesture#group___gesture_1ga828a68be30e6eaa9e9af9b364ce340e0).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | A pointer to the gesture context instance. | |
| **Returns** | The number of detected gestures. |

### gvr_gesture_get_direction

```
gvr_gesture_direction gvr_gesture_get_direction(
  const gvr_gesture *gesture
)
```
Returns the direction (up/down/left/right) of given gesture.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `gesture` | A pointer to the gesture instance. | |
| **Returns** | The direction of the given gesture. |

### gvr_gesture_get_displacement

```
gvr_vec2f gvr_gesture_get_displacement(
  const gvr_gesture *gesture
)
```
Returns the displacement (in touchpad unit) of given gesture.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `gesture` | A pointer to the gesture instance. | |
| **Returns** | The displacement of the given gesture. |

### gvr_gesture_get_type

```
gvr_gesture_type gvr_gesture_get_type(
  const gvr_gesture *gesture
)
```
Returns the type (swipe/scroll_start/scroll_update/scroll_end) of given gesture.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `gesture` | A pointer to the gesture instance. | |
| **Returns** | The type of the given gesture. |

### gvr_gesture_get_velocity

```
gvr_vec2f gvr_gesture_get_velocity(
  const gvr_gesture *gesture
)
```
Returns the velocity (in normalized distance / second) of the given gesture, where (0,0) is the top-left of the touchpad and (1,1) is the bottom right.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `gesture` | A pointer to the gesture instance. | |
| **Returns** | The velocity of the given gesture. |

### gvr_gesture_restart

```
void gvr_gesture_restart(
  gvr_gesture_context *context
)
```
Restarts gesture detection.

This should be used whenever the user does not lift up the finger from the controller touchpad, but the gesture detection needs to be restarted (e.g. the controller reticle moves from a non-scrollable region to a scrollable region).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `context` | A pointer to the gesture context instance. | |

### gvr_gesture_update

```
void gvr_gesture_update(
  const gvr_controller_state *controller_state,
  gvr_gesture_context *context
)
```
Updates the gesture context based on controller state.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `controller_state` | A pointer to the controller state instance. | | `context` | A pointer to the gesture context instance. | |

### gvr_get_button_long_press

```
bool gvr_get_button_long_press(
  const gvr_controller_state *controller_state,
  const gvr_gesture_context *context,
  gvr_controller_button button
)
```
Returns whether a long press on controller button has been detected.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `controller_state` | A pointer to the controller state instance. | | `context` | A pointer to the gesture context instance. | | `button` | A controller button type. | |
| **Returns** | Whether the given button has been long pressed. |