GestureWorks Core API Reference

From GestureWorks Tutorials
Jump to: navigation, search

Logo gestureworks core.png

 


Contents

API Overview

The Gestureworks Core API consists of a series of methods, functions and data structures which are used to connect applications to the GestureworksCore.dll, prompt the core to analyze and process gestures, then return structured gesture event data to the application layer.


Core Functions

The functions available through the core are as follows:

void initializeGestureWorks(int screen_width, int screen_height)
Initializes GestureWorks and calibrates stroke based gestures for your resolution.

void resizeScreen(int width, int height)
Updates the internal screen size.

bool loadGML(char* path_to_gml)
Loads all gesture definitions from the specified GML file. Multiple files may be loaded. Returns true if one or more gesture object was created.

bool registerWindowForTouch(HWND hwnd)
Tells GestureWorks which window (application) you want to touch enable via a handle to the window. Returns true upon success.

bool registerWindowForTouchByName(char* window_name)
Tells GestureWorks which window (application) you want to touch enable via the process name. Returns true upon success.

bool registerTouchObject(char* object_name)
Registers a touch object with GestureWorks by name. The object’s name is arbitrary can and be anything the application developer chooses.

bool deregisterTouchObject(char* object_name)
Deregisters a touch object with GestureWorks by name. The object must have been registered with the same name in a call to registerTouchObject

bool addGesture(char* touch_object_name, char* gesture_name)
Enables processing of the specified gesture on the touch object. The gesture name is defined in the GML and the touch object name is defined in the call to registerTouchObject. The GML file containing the gesture must be loaded first. Returns true upon success.

bool addGestureSet(char* touch_object_name, char* set_name)
Enables a set of gestures on a touch object where the set is defined in a loaded GML file. Returns true upon success.

bool removeGesture(char* touch_object_name, char* gesture_name)
Removes gesture processing of the specified gesture from the specified touch object. Returns true upon successful removal.

bool removeGestureSet(char* touch_object_name, char* set_name)
Removes gesture processing for a set of gestures from the specified touch object where the set is defined in a loaded GML file. Returns true upon success.

void processFrame()
Tell GestureWorks to process the current frame of data.

PointEventArray* consumePointEvents()
Consume point events that were processed in the call to processFrame.

GestureEventArray* consumeGestureEvents()
Consume gesture events that were processed in the call to processFrame.

bool addTouchPoint(char* touch_object_name, int point_id)
Assigns a touch point to a touch object, usually after the client application has performed a hit test or otherwise determined that the touch point has collided with the touch object.

void addEvent(touchpoint touch_event)
Adds a touch event to the Gestureworks pipeline for processing. This is used to feed Gestureworks touch events obtained from sources other than Windows.


Structures

The following structures with relevant public members are exported by the core library:

Point

    - float x
    - float y
    - float z
    - float w
    - float h
    - float r


PointEvent

    - int point_id
    - int status
    - Point position
    - clock_t timestamp


PointEventArray

    - PointEvent* events
    - int size


Where point_id is a unique identifier, and status is enumerated as {TOUCHUPDATE, TOUCHADDED, TOUCHREMOVED}.

GestureEvent

    - int ID
    - char* gesture_type
    - char* gesture_id
    - char* xml_snippet
    - char* target
    - int source
    - int n
    - int hold_n
    - float x
    - float y
    - int timestamp
    - int phase
    - int* locked_points
    - MapStruct values


Where target is the name of the touch object which owns the gesture (as defined by registerTouchObject), n is the number of touch points involved in the gesture, and x & y are the screen coordinates of where the gesture occurred. The values map is where relevant gesture values will be returned by name as defined in the GML. See the Gestureworks Core Collection Viewer provided in this package for an example of how to use this structure for typical display manipulations.

Phase describes the current state of the gesture:

  • 0 = GESTURE_BEGIN : The beginning of a gesture.
  • 1 = GESTURE_ACTIVE : The gesture is currently being generated by direct manipulation.
  • 2 = GESTURE_RELEASE : Direct manipulation has ceased.
  • 3 = GESTURE_PASSIVE : The gesture is being generated by indirect manipulation (e.g. inertial filters).
  • 4 = GESTURE_END : The gesture has completed. This is the last event.


GestureEventArray

    - int size
    - GestureEvent* events


MapStruct

    - char** names
    - float* values
    - int size


touchpoint

    - clock_t timestamp
    - int status
    - long int id
    - float x
    - float y
    - float z
    - float w
    - float h
    - float r
    - float p

Personal tools

Variants
Actions
Navigation
Toolbox