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()	gvr_gesture_context * 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)	gvr_gesture_direction Returns the direction (up/down/left/right) of given gesture.
gvr_gesture_get_displacement(const gvr_gesture *gesture)	gvr_vec2f Returns the displacement (in touchpad unit) of given gesture.
gvr_gesture_get_type(const gvr_gesture *gesture)	gvr_gesture_type Returns the type (swipe/scroll_start/scroll_update/scroll_end) of given gesture.
gvr_gesture_get_velocity(const gvr_gesture *gesture)	gvr_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.
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.