Introduce gesture frames

This patch extends the API with parallel new/delete functions,
aiming to eventually replace the open/close function. The new
functions give access to the grail gesture frames, containing
gestural transform information. This information is useful in its
own right, and will eventually replace the internal recognizer.

Signed-off-by: Henrik Rydberg <rydberg@euromail.se>

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