Initial load of utouch-framev1.0.0

Compiles and runs on mtdev. ABI proof.

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

1 files changed, 250 insertions, 0 deletions

diff --git a/include/utouch/frame.h b/include/utouch/frame.h
new file mode 100644
index 0000000..08e4e26
--- /dev/null
+++ b/include/utouch/frame.h
@@ -0,0 +1,250 @@
+/*****************************************************************************
+ *
+ * utouch-frame - Touch Frame Library
+ *
+ * Copyright (C) 2010-2011 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ ****************************************************************************/
+
+#ifndef _UTOUCH_FRAME_H
+#define _UTOUCH_FRAME_H
+
+#include <stdint.h>
+
+#define UTOUCH_FRAME_VERSION    0x00001000
+
+/**
+ * struct utouch_surface - device surface details
+ * @needs_pointer: device needs a screen pointer to function
+ * @is_direct: surface is a direct device (e.g. touchscreen)
+ * @is_buttonpad: surface has button(s) under it
+ * @is_semi_mt: surface detects bounding rectangle only
+ * @use_touch_major: device uses major axis for contact modulation
+ * @use_touch_minor: device uses minor axis for contact modulation
+ * @use_width_major: device uses approaching major axis for contact modulation
+ * @use_width_minor: device uses approaching minor axis for contact modulation
+ * @use_orientation: device uses ellipse orientation for contact modulation
+ * @use_pressure: device uses pressure for contact modulation
+ * @use_distance: device uses hover distance
+ * @phys_width: physical width in millimeters (mm)
+ * @phys_height: physical height in millimeters (mm)
+ * @phys_pressure: maximal physical pressure (N/cm^2)
+ * @min_x: minimum horizontal coordinate value
+ * @min_y: minimum vertical coordinate value
+ * @max_x: maximum horizontal coordinate value
+ * @max_y: maximum vertical coordinate value
+ * @max_pressure: maximum pressure coordinate value
+ *
+ * Device properties and touch surface details. Later versions of this
+ * struct may grow in size, but will remain binary compatible with
+ * older versions.
+ */
+struct utouch_surface {
+        int needs_pointer;
+        int is_direct;
+        int is_buttonpad;
+        int is_semi_mt;
+        int use_touch_major;
+        int use_touch_minor;
+        int use_width_major;
+        int use_width_minor;
+        int use_orientation;
+        int use_pressure;
+        int use_distance;
+        float phys_width;
+        float phys_height;
+        float phys_pressure;
+        float min_x;
+        float min_y;
+        float max_x;
+        float max_y;
+        float max_pressure;
+};
+
+#define UTOUCH_TOOL_FINGER      0
+#define UTOUCH_TOOL_PEN         1
+
+/**
+ * struct utouch_contact - surface contact details
+ * @prev: pointer to same slot of previous frame
+ * @active: currently in use
+ * @slot: slot occupied by this contact
+ * @id: unique id of this contact
+ * @tool_type: the tool type of this contact
+ * @x: horizontal center position coordinate (surface units)
+ * @y: vertical center position coordinate (surface units)
+ * @touch_major: major axis of contact (surface units)
+ * @touch_minor: minor axis of contact (surface units)
+ * @width_major: major axis of approaching contact (surface units)
+ * @width_minor: minor axis of approaching contact (surface units)
+ * @orientation: direction of ellipse (left: -Pi/2, up: 0, right: Pi/2)
+ * @pressure: pressure of contact (pressure units)
+ * @distance: distance of contact (surface units)
+ *
+ * Surface contact details. Later versions of this struct may grow in
+ * size, but will remain binary compatible with older versions.
+ *
+ * Contact structures are connected into one ring per slot. The
+ * previous contact pointers are ABI agnostic, owned by the engine,
+ * and have engine scope.
+ */
+struct utouch_contact {
+        const struct utouch_contact *prev;
+        int active;
+        int slot;
+        int id;
+        int tool_type;
+        float x;
+        float y;
+        float touch_major;
+        float touch_minor;
+        float width_major;
+        float width_minor;
+        float orientation;
+        float pressure;
+        float distance;
+};
+
+/* time in milliseconds */
+typedef uint64_t utouch_frame_time_t;
+
+/* the frame engine handle */
+typedef struct utouch_frame_engine *utouch_frame_handle;
+
+/**
+ * struct utouch_frame - emitted frame details
+ * @prev: pointer to previous frame
+ * @sequence_id: frame sequence number
+ * @revision: changes whenever the contact count changes
+ * @slot_revision: changes whenever the slot id array change
+ * @num_active: the number of contacts in the active array
+ * @time: time of frame completion (ms)
+ * @mod_time: time of last contact count change (ms)
+ * @slot_mod_time: time of last slot id array change (ms)
+ * @active: the array of active contacts
+ *
+ * Contact frame details. Later versions of this struct may grow in
+ * size, but will remain binary compatible with older versions.
+ *
+ * Frames are connected into a ring. The previous frame pointer is ABI
+ * agnostic, owned by the engine, and has engine scope.
+ */
+struct utouch_frame {
+        const struct utouch_frame *prev;
+        unsigned int sequence_id;
+        unsigned int revision;
+        unsigned int slot_revision;
+        unsigned int num_active;
+        utouch_frame_time_t time;
+        utouch_frame_time_t mod_time;
+        utouch_frame_time_t slot_mod_time;
+        struct utouch_contact **active;
+        struct utouch_contact **slots;
+};
+
+/**
+ * utouch_frame_get_version - get library abi version
+ *
+ * Returns the version of the library, which may be different
+ * from the api version of the compiled user program.
+ */
+unsigned int utouch_frame_get_version(void);
+
+utouch_frame_handle utouch_frame_new_engine_raw(unsigned int num_frames,
+                                                unsigned int num_slots,
+                                                unsigned int frame_rate,
+                                                unsigned int version,
+                                                unsigned int surface_size,
+                                                unsigned int frame_size,
+                                                unsigned int slot_size);
+
+/**
+ * utouch_frame_new_engine - allocate a new frame engine
+ * @num_frames: number of frames in cyclic buffer
+ * @num_slots: maximum number of slots per frame
+ * @frame_rate: maximum frame rate (frames/s)
+ *
+ * Allocates memory, initializes the internal engine and returns a
+ * handle to it. A rate of 100 frames per second is normal.
+ */
+#define utouch_frame_new_engine(num_frames, num_slots, frame_rate)      \
+        utouch_frame_new_engine_raw(num_frames,                         \
+                                    num_slots,                          \
+                                    frame_rate,                         \
+                                    UTOUCH_FRAME_VERSION,               \
+                                    sizeof(struct utouch_surface),      \
+                                    sizeof(struct utouch_frame),        \
+                                    sizeof(struct utouch_contact))
+
+/**
+ * utouch_frame_delete_engine - deallocate a frame engine
+ * @fh: frame engine in use
+ *
+ * Deallocates all memory associated with the engine.
+ */
+void utouch_frame_delete_engine(utouch_frame_handle fh);
+
+/**
+ * utouch_frame_get_surface - get the mutable device surface information
+ * @fh: the frame engine in use
+ *
+ * Returns a pointer to the mutable device surface information. It is
+ * preferrably set up by one of the input handlers. The pointer is ABI
+ * agnostic, has frame engine scope, and is owned by the engine.
+ */
+struct utouch_surface *utouch_frame_get_surface(utouch_frame_handle fh);
+
+/**
+ * utouch_frame_get_current_slot - get the current mutable slot contact
+ * @fh: the frame engine in use
+ *
+ * Returns a pointer to the contact current being modified. The
+ * pointer is ABI agnostic, has frame engine scope, and is owned by
+ * the engine.
+ */
+struct utouch_contact *utouch_frame_get_current_slot(utouch_frame_handle fh);
+
+/**
+ * utouch_frame_set_current_slot - set the current slot number
+ * @fh: the frame engine in use
+ * @slot: the slot number
+ *
+ * Sets the slot currently being modified. Returns zero if successful,
+ * negative error otherwise.
+ */
+int utouch_frame_set_current_slot(utouch_frame_handle fh, int slot);
+
+/**
+ * utouch_frame_sync - synchronize and return new frame
+ * @fh: the frame engine in use
+ * @time: the frame synchronization time (ms)
+ *
+ * Scans through the updates, and in case the changes make up a new
+ * frame, returns the updated frame.
+ *
+ * If time is zero, a time-of-receipt will be used instead.
+ *
+ * The frame returned is always the next in the cyclic list, and
+ * always points back at the previous frame returned by this function.
+ *
+ * The returned pointer is ABI agnostic and owned by the frame
+ * engine. It may very well be zero if there is nothing to report or
+ * if the frame rate is limited.
+ */
+const struct utouch_frame *utouch_frame_sync(utouch_frame_handle fh,
+                                             utouch_frame_time_t time);
+
+#endif