1 files changed, 204 insertions, 0 deletions

diff --git a/include/grail.h b/include/grail.h
index b208556..d9f3937 100644
--- a/include/grail.h
+++ b/include/grail.h
@@ -44,8 +44,17 @@ extern "C" {
 #define GRAIL_STATUS_UPDATE     1
 #define GRAIL_STATUS_END        2
 
+#define GRAIL_EXPECT_CENTER_X   0x0001
+#define GRAIL_EXPECT_CENTER_Y   0x0002
+#define GRAIL_EXPECT_DRAG_X     0x0004
+#define GRAIL_EXPECT_DRAG_Y     0x0008
+#define GRAIL_EXPECT_SCALE      0x0010
+#define GRAIL_EXPECT_ANGLE      0x0020
+#define GRAIL_EXPECT_MASK       0x003f
+
 typedef float grail_prop_t;                     /* gesture properties */
 typedef utouch_frame_time_t grail_time_t;       /* time in milliseconds */
+typedef struct grail *grail_handle;             /* the grail instance handle */
 
 /**
  * struct grail_get_version - get grail library version
@@ -69,6 +78,64 @@ struct grail_coord {
         float x, y;
 };
 
+grail_handle GRAIL_PUBLIC grail_new_raw(utouch_frame_handle fh,
+                                        unsigned int num_frames,
+                                        void *select,
+                                        unsigned int version,
+                                        unsigned int control_size,
+                                        unsigned int frame_size,
+                                        unsigned int slot_size);
+
+/**
+ * grail_new - allocate and initialize a new grail instance
+ * @fh: utouch frame handle to use
+ * @num_frames: number of frames in cyclic buffer
+ * @select: client selection callback
+ *
+ * Initialize the internal grail structures.
+ *
+ * Returns zero in case of failure.
+ */
+#define grail_new(fh, num_frames, select)               \
+        grail_new_raw(fh, num_frames, select,           \
+                      GRAIL_VERSION,                    \
+                      sizeof(struct grail_control),     \
+                      sizeof(struct grail_frame),       \
+                      sizeof(struct grail_element))
+
+/**
+ * grail_delete - destroy and delete grail instance
+ * @ge: grail instance in use
+ *
+ * Deallocates all internal memory structures.
+ */
+void GRAIL_PUBLIC grail_delete(grail_handle ge);
+
+/**
+ * grail_get_control - get mutable control structure
+ * @ge: the grail device in use
+ *
+ * Return the control struct of the grail instance.
+ *
+ * The control pointer is ABI agnostic, owned by the grail instance, and
+ * has grail scope.
+ */
+struct grail_control GRAIL_PUBLIC *grail_get_control(grail_handle ge);
+
+/**
+ * grail_pump_frame - insert touch frames into grail
+ * @ge: the grail device in use
+ * @frame: the touch frame to insert
+ *
+ * Insert a new touch frame into the grail engine. If the frame induces a
+ * new gesture frame, a pointer to the frame is returned.
+ *
+ * The grail frame pointer is ABI agnostic, owned by the grail instance, and
+ * has grail scope.
+ */
+const struct grail_frame GRAIL_PUBLIC *
+grail_pump_frame(grail_handle ge, const struct utouch_frame *frame);
+
 /**
  * struct grail_client_id - Gesture client information
  * @client: Client id
@@ -95,6 +162,143 @@ struct grail_client_info {
 };
 
 /**
+ * struct grail_control - control parameters of grail
+ * @glue_ms: minimum time to hold activation (ms)
+ * @bar_center_x: horizontal distance to activate (surface width fraction)
+ * @bar_center_y: vertical distance to activate (surface height fraction)
+ * @bar_drag_x: horizontal distance to activate (surface width fraction)
+ * @bar_drag_y: vertical distance to activate (surface height fraction)
+ * @bar_scale: minimum scaling to activate (fraction)
+ * @bar_angle: minimum angle to activate (radians)
+ * @drop_x_ms: horizontal expect timeout (ms)
+ * @drop_y_ms: vertical expect timeout (ms)
+ * @drop_scale_ms: scaling expect timeout (ms)
+ * @drop_angle_ms: rotation expect timeout (ms)
+ * @pivot_unbound: when true, the pivot is not bound to the contact area
+ *
+ * The parameters are used to tune the behavior of the gesture recognition.
+ *
+ * The moveness is a number between zero and one denoting the
+ * character of the current transform. Zero means pure rotate and
+ * scale, one means pure drag.
+ *
+ * Later versions of this struct may grow in size, but will remain
+ * binary compatible with older versions.
+ */
+struct grail_control {
+        float glue_ms;
+        float bar_center_x;
+        float bar_center_y;
+        float bar_drag_x;
+        float bar_drag_y;
+        float bar_scale;
+        float bar_angle;
+        float drop_x_ms;
+        float drop_y_ms;
+        float drop_scale_ms;
+        float drop_angle_ms;
+        int pivot_unbound;
+};
+
+/**
+ * struct grail_frame - frame of ongoing elementary transformations
+ * @prev: pointer to the previous gesture frame
+ * @touch: pointer to the touch frame triggering this gesture frame
+ * @num_ongoing: number of elements in the ongoing array
+ * @ongoing: array of ongoing transformation elements
+ * @slots: array of all transformation slots
+ *
+ * A gesture frame consists of one or several touch frames glued
+ * together into a stable transition, combined with information on
+ * ongoing elementary gestural transformations. The array of ongoing
+ * elements contains all elements with a nonzero expect mask.
+ *
+ * Later versions of this struct may grow in size, but will remain
+ * binary compatible with older versions.
+ */
+struct grail_frame {
+        const struct grail_frame *prev;
+        const struct utouch_frame *touch;
+        unsigned int num_ongoing;
+        struct grail_element **ongoing;
+        struct grail_element **slots;
+};
+
+/**
+ * struct grail_element - elementary gesture transformation
+ * @prev: respective element of previous frame
+ * @slot: the transformation slot occupied by this element
+ * @id: unique identifier of the ongoing transformation
+ * @num_touches: number of contacts of this element
+ * @touches: array of contacts of this element
+ * @start_time: start time of this element
+ * @start_center: center position at start of transform (surface units)
+ * @expect_mask: bitmask of expected gestures (grail main types)
+ * @active_mask: bitmask of activated gestures (grail main types)
+ * @center: gesture center position (surface units)
+ * @velocity: current center velocity (surface units per second)
+ * @radius: gesture radius from center (surface units)
+ * @transform: the transformation matrix of the gesture
+ * @pivot: current center of rotate and scale (surface units)
+ * @drag: accumulated transformation displacement (surface units)
+ * @scale: accumulated scale (dimensionless)
+ * @angle: accumulated rotation angle (radians)
+ *
+ * The grail element describes the ongoing gestural transformation of
+ * a particular set of contacts. The expect mask describes which
+ * gestural transformations may become active during the course of
+ * events, and the active mask describes which have passed their
+ * respective activation threshold. The set of expected gestures can
+ * change over time, for instance by exclusion or timeout.
+ *
+ * Applications handling rotation, either by transformation matrix or
+ * angle, should use the drag displacement. For other applications,
+ * the center displacement may be used instead, as to not lose
+ * movement accuracy.
+ *
+ * Later versions of this struct may grow in size, but will remain
+ * binary compatible with older versions.
+ */
+struct grail_element {
+        const struct grail_element *prev;
+        int slot;
+        int id;
+        int num_touches;
+        const struct utouch_contact **touches;
+        grail_time_t start_time;
+        struct grail_coord start_center;
+        unsigned int expect_mask;
+        unsigned int active_mask;
+        struct grail_coord center;
+        struct grail_coord velocity;
+        float radius2;
+        float transform[6];
+        float moveness;
+        struct grail_coord pivot;
+        struct grail_coord drag;
+        float scale2;
+        float angle;
+};
+
+/**
+ * grail_element_transform - transform coordinates using element
+ * @slot: the transformation element to use
+ * @q: the grail coordinate to fill
+ * @x: the grail coordinate to transform
+ *
+ * Performs the 3x3 transform *q = T *p, where T is the element
+ * transform.
+ */
+static inline void grail_element_transform(const struct grail_element *slot,
+                                           struct grail_coord *q,
+                                           const struct grail_coord *p)
+{
+        const float *T = slot->transform;
+        q->x = T[0] * p->x + T[1] * p->y + T[2];
+        q->y = T[3] * p->x + T[4] * p->y + T[5];
+}
+
+/**
  * struct grail_event - Gesture event
  * @type: The gesture type
  * @id: Unique identifier foof the gesture instance