59
59
#include <stdint.h>
62
* @defgroup v1 uTouch-Frame 1.x
67
#define UTOUCH_FRAME_VERSION 0x00001010
70
* struct utouch_surface - device surface details
71
* @needs_pointer: device needs a screen pointer to function
72
* @is_direct: surface is a direct device (e.g. touchscreen)
73
* @is_buttonpad: surface has button(s) under it
74
* @is_semi_mt: surface detects bounding rectangle only
75
* @use_touch_major: device uses major axis for contact modulation
76
* @use_touch_minor: device uses minor axis for contact modulation
77
* @use_width_major: device uses approaching major axis for contact modulation
78
* @use_width_minor: device uses approaching minor axis for contact modulation
79
* @use_orientation: device uses ellipse orientation for contact modulation
80
* @use_pressure: device uses pressure for contact modulation
81
* @use_distance: device uses hover distance
82
* @phys_width: physical width in millimeters (mm)
83
* @phys_height: physical height in millimeters (mm)
84
* @phys_pressure: maximal physical pressure (N/cm^2)
85
* @min_x: minimum horizontal device coordinate
86
* @min_y: minimum vertical device coordinate
87
* @max_x: maximum horizontal device coordinate
88
* @max_y: maximum vertical device coordinate
89
* @max_pressure: maximum pressure device coordinate
90
* @max_orient: maximum orientation device coordinate
91
* @mapped_min_x: minimum horizontal mapped coordinate
92
* @mapped_min_y: minimum vertical mapped coordinate
93
* @mapped_max_x: maximum horizontal mapped coordinate
94
* @mapped_max_y: maximum vertical mapped coordinate
95
* @mapped_max_pressure: maximum pressure mapped coordinate
97
* The mutable contact given by utouch_frame_get_current_slot() should
98
* be set in device coordinates. The contact data is subsequently
99
* transformed to mapped (e.g., screen) coordinates in
100
* utouch_frame_sync(). To a frame user, all data will appear in
101
* mapped coordinates.
103
* Device properties and touch surface details. Later versions of this
104
* struct may grow in size, but will remain binary compatible with
107
struct utouch_surface {
132
float mapped_max_pressure;
137
#define UTOUCH_TOOL_FINGER 0
138
#define UTOUCH_TOOL_PEN 1
141
* struct utouch_contact - surface contact details
142
* @prev: pointer to same slot of previous frame
143
* @active: currently in use
144
* @slot: slot occupied by this contact
145
* @id: unique id of this contact
146
* @tool_type: the tool type of this contact
147
* @x: horizontal center position coordinate (surface units)
148
* @y: vertical center position coordinate (surface units)
149
* @touch_major: major axis of contact (surface units)
150
* @touch_minor: minor axis of contact (surface units)
151
* @width_major: major axis of approaching contact (surface units)
152
* @width_minor: minor axis of approaching contact (surface units)
153
* @orientation: direction of ellipse (left: -Pi/2, up: 0, right: Pi/2)
154
* @pressure: pressure of contact (pressure units)
155
* @distance: distance of contact (surface units)
156
* @vx: horizontal velocity coordinate (units / millisecond)
157
* @vy: vertical velocity coordinate (units / millisecond)
159
* Surface contact details. Later versions of this struct may grow in
160
* size, but will remain binary compatible with older versions.
162
* Contact structures are connected into one ring per slot. The
163
* previous contact pointers are ABI agnostic, owned by the engine,
164
* and have engine scope.
166
struct utouch_contact {
167
const struct utouch_contact *prev;
185
/* time in milliseconds */
186
typedef uint64_t utouch_frame_time_t;
188
/* the frame engine handle */
189
typedef struct utouch_frame_engine *utouch_frame_handle;
192
* struct utouch_frame - emitted frame details
193
* @prev: pointer to previous frame
194
* @sequence_id: frame sequence number
195
* @revision: changes whenever the contact count changes
196
* @slot_revision: changes whenever the slot id array change
197
* @num_active: the number of contacts in the active array
198
* @time: time of frame completion (ms)
199
* @mod_time: time of last contact count change (ms)
200
* @slot_mod_time: time of last slot id array change (ms)
201
* @active: the array of active contacts
203
* Contact frame details. Later versions of this struct may grow in
204
* size, but will remain binary compatible with older versions.
206
* Frames are connected into a ring. The previous frame pointer is ABI
207
* agnostic, owned by the engine, and has engine scope.
209
struct utouch_frame {
210
const struct utouch_frame *prev;
211
unsigned int sequence_id;
212
unsigned int revision;
213
unsigned int slot_revision;
214
unsigned int num_active;
215
utouch_frame_time_t time;
216
utouch_frame_time_t mod_time;
217
utouch_frame_time_t slot_mod_time;
218
struct utouch_contact **active;
219
struct utouch_contact **slots;
223
* utouch_frame_get_version - get library abi version
225
* Returns the version of the library, which may be different
226
* from the api version of the compiled user program.
229
unsigned int utouch_frame_get_version(void);
232
* utouch_frame_get_num_frames - get number of supported frames
234
* Returns the number of frames supported by this engine.
237
unsigned int utouch_frame_get_num_frames(utouch_frame_handle fh);
240
* utouch_frame_get_num_slots - get number of supported slots
242
* Returns the number of simultaneous contacts supported by this engine.
245
unsigned int utouch_frame_get_num_slots(utouch_frame_handle fh);
248
utouch_frame_handle utouch_frame_new_engine_raw(unsigned int num_frames,
249
unsigned int num_slots,
250
unsigned int frame_rate,
251
unsigned int version,
252
unsigned int surface_size,
253
unsigned int frame_size,
254
unsigned int slot_size);
257
* utouch_frame_new_engine - allocate a new frame engine
258
* @num_frames: number of frames in cyclic buffer
259
* @num_slots: maximum number of slots per frame
260
* @frame_rate: maximum frame rate (frames/s)
262
* Allocates memory, initializes the internal engine and returns a
263
* handle to it. A rate of 100 frames per second is normal.
265
#define utouch_frame_new_engine(num_frames, num_slots, frame_rate) \
266
utouch_frame_new_engine_raw(num_frames, \
269
UTOUCH_FRAME_VERSION, \
270
sizeof(struct utouch_surface), \
271
sizeof(struct utouch_frame), \
272
sizeof(struct utouch_contact))
275
* utouch_frame_delete_engine - deallocate a frame engine
276
* @fh: frame engine in use
278
* Deallocates all memory associated with the engine.
281
void utouch_frame_delete_engine(utouch_frame_handle fh);
284
* utouch_frame_get_surface - get the mutable device surface information
285
* @fh: the frame engine in use
287
* Returns a pointer to the mutable device surface information. It is
288
* preferrably set up by one of the input handlers. The pointer is ABI
289
* agnostic, has frame engine scope, and is owned by the engine.
292
struct utouch_surface *utouch_frame_get_surface(utouch_frame_handle fh);
295
* utouch_frame_get_current_slot - get the current mutable slot contact
296
* @fh: the frame engine in use
298
* Returns a pointer to the contact current being modified. The
299
* pointer is ABI agnostic, has frame engine scope, and is owned by
303
struct utouch_contact *utouch_frame_get_current_slot(utouch_frame_handle fh);
306
* utouch_frame_set_current_slot - set the current slot number
307
* @fh: the frame engine in use
308
* @slot: the slot number
310
* Sets the slot currently being modified. Returns zero if successful,
311
* negative error otherwise.
314
int utouch_frame_set_current_slot(utouch_frame_handle fh, int slot);
317
* utouch_frame_set_current_id - set the current slot by touch id
318
* @fh: the frame engine in use
321
* Sets the slot currently being modified, by touch id. If the id is
322
* not currently in use (does not have an active slot), a new slot is
323
* assigned. Returns zero if successful, negative error otherwise.
326
int utouch_frame_set_current_id(utouch_frame_handle fh, int id);
329
* utouch_frame_sync - synchronize and return new frame
330
* @fh: the frame engine in use
331
* @time: the frame synchronization time (ms)
333
* Scans through the updates, and in case the changes make up a new
334
* frame, returns the updated frame.
336
* If time is zero, a time-of-receipt will be used instead.
338
* The frame returned is always the next in the cyclic list, and
339
* always points back at the previous frame returned by this function.
341
* The returned pointer is ABI agnostic and owned by the frame
342
* engine. It may very well be zero if there is nothing to report or
343
* if the frame rate is limited.
346
const struct utouch_frame *utouch_frame_sync(utouch_frame_handle fh,
347
utouch_frame_time_t time);
350
* utouch_coordinate_transform_cb - user-definable callback that transforms a touch point
351
* @x: pointer to an x coordinate (in, out)
352
* @y: pointer to a y coordinate (in, out)
353
* @user_data: opaque pointer, passed by the user when setting the callback
355
typedef void (*utouch_coordinate_transform_cb)(float *x, float *y, void *user_data);
358
* utouch_frame_set_coordinate_transform_callback - set a callback to obtain a transformation
359
* to apply to every touch point
360
* @fh: the frame engine in use
361
* @callback: the callback that transforms x and y
362
* @user_data: opaque pointer to user data for the callback
365
void utouch_frame_set_coordinate_transform_callback(utouch_frame_handle fh,
366
utouch_coordinate_transform_cb callback,
371
* @defgroup v2 uTouch-Frame 2.x
375
/** An object for the context of the uTouch Frame instance */
61
/** An object for the context of the frame instance */
376
62
typedef struct UFHandle_* UFHandle;
377
63
/** An object for an event */
378
64
typedef struct UFEvent_* UFEvent;
added
removed
include/oif/frame.h
