1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
/*****************************************************************************
*
* 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
#ifdef __cplusplus
extern "C" {
#endif
#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);
#ifdef __cplusplus
}
#endif
#endif
|
