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();

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;
   }
}

Enumerations

gvr_gesture_direction{
  GVR_GESTURE_DIRECTION_UP = 1,
  GVR_GESTURE_DIRECTION_DOWN = 2,
  GVR_GESTURE_DIRECTION_LEFT = 3,
  GVR_GESTURE_DIRECTION_RIGHT = 4
}
enum
Gesture directions.
gvr_gesture_type{
  GVR_GESTURE_SWIPE = 1,
  GVR_GESTURE_SCROLL_START = 2,
  GVR_GESTURE_SCROLL_UPDATE = 3,
  GVR_GESTURE_SCROLL_END = 4
}
enum
Gesture types.

Typedefs

gvr_gesture typedef
struct gvr_gesture_
Opaque handle to gesture.
gvr_gesture_context typedef
struct gvr_gesture_context_
Opaque handle to gesture context.

Functions

gvr_gesture_context_create()
Creates and initializes a gesture context instance which can be used to invoke the gesture API functions.
gvr_gesture_context_destroy(gvr_gesture_context **context)
void
Destroys the gesture context.
gvr_gesture_get(const gvr_gesture_context *context, int index)
const gvr_gesture *
Returns the gesture with the given index.
gvr_gesture_get_count(const gvr_gesture_context *context)
int
Returns the number of gestures detected in previous gvr_gesture_update().
gvr_gesture_get_direction(const gvr_gesture *gesture)
Returns the direction (up/down/left/right) of given gesture.
gvr_gesture_get_displacement(const gvr_gesture *gesture)
Returns the displacement (in touchpad unit) of given gesture.
gvr_gesture_get_type(const gvr_gesture *gesture)
Returns the type (swipe/scroll_start/scroll_update/scroll_end) of given gesture.
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.
gvr_gesture_restart(gvr_gesture_context *context)
void
Restarts gesture detection.
gvr_gesture_update(const gvr_controller_state *controller_state, gvr_gesture_context *context)
void
Updates the gesture context based on controller state.
gvr_get_button_long_press(const gvr_controller_state *controller_state, const gvr_gesture_context *context, gvr_controller_button 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.

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.

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() or gvr_gesture_context_destroy().

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().

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.

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.

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.

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.

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

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.

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.

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.