diff options
Diffstat (limited to 'include/utouch/frame.h')
| -rw-r--r-- | include/utouch/frame.h | 250 |
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 |