1
ļ»æGesture Engine Interface Support
2
================================
3
Stephen M. Webb <stephen.webb@bregmasoft.ca>
10
This document describes GEIS, an interface between an application and an
11
underlying gesture recognition system.
13
A GEIS implementation provides a mechanism for recognizing user interface
14
gestures on various configurable devices and for propagating those recognized
15
gestures to subscribed applications.
20
A _gesture_ is a defined set of particular movements of pointing devices. GEIS
21
provides no interpretation of gestures, only recognition and propagation.
23
Because gestures can be defined to have global meaning as well as local meaning,
24
it makes sense that gesture recognition be provided by the system rather than be
25
included as a library by a particular application or toolkit. This allows, for
26
example, a set of gestures to be defined for the window manager in use on a
27
display to receive gesture events even when another application is in the
28
foreground and receiving the input.
33
The purpose of GEIS is intended to provide a consistent and stable application
34
programming interface for gesture recognition and propagation on multiple target
35
platforms (for example, Linux, Unix, and Windows), multiple target input
36
devices (for example mice, touch pads, mutitouch touchscreens, tables, nunchuks),
37
and multiple gesture recognition engines. Different gesture engines may be
38
available on the same platform.
40
A number of basic types are defined for portability between various underlying
41
display, input, and operating systems.
46
+GeisBoolean+ is an integral type representing a boolean value and should only
47
hold the values +GEIS_TRUE+ (1) and +GEIS_FALSE+ (0).
49
+GeisInt+ is an integral type large enough to hold any integral gesture attribute
50
value which may be represented on the native platform. This may includes
51
bitmasks, enumerants, integers, handles, and so forth.
53
+GeisFloat+ is a floating-point type which can represent floating-point valued
56
+GeisString+ is a C-style zero-terminated string of characters in some character
57
set. A +GeisString+ is a read-only string and does not have to be freed or
58
disposed of by the caller.
63
An application may need to support different sets of gestures from different
64
input devices or associated with different regions of the same device. For this
65
reason, GEIS provides for one or more distinct connections to the underlying
66
gesture engine. The instances are distinguished by a GeisInstance object. All
67
gesture types and gesture instances IDs are in a namespace associated with the
68
GeisInstance and are not guaranteed to be system wide unique.
70
Threading and Concurrency
71
^^^^^^^^^^^^^^^^^^^^^^^^^
73
The GEIS API does not specify threading, reentrancy, or concurrency attributes.
74
The implementation must supply detailed documentation on these aspects.
79
The API provides a method to enumerate the available gesture-capable input
80
devices (including the dynamic appearance and disappearance of such devices) and
81
a way to specify a subset of these devices for use in a particular gesture
82
detection instance. A client application might typically respond to gestures
83
from any input device, but others, such as a drawing application, may wish to
84
bypass gesture detection on, for example, a drawing tablet while accepting them
85
from a touchscreen for other functions such as zoom and rotate.
87
GEIS uses a set of client-supplied callbacks to report the availability of input
88
devices so that devices that dynamically appear or disappear can be reported
89
through a consistent interface.
91
GEIS Functions and Errors
92
-------------------------
97
NOTE: This section is not complete.
99
GEIS functions usually return a status code indicating success or failure. The
100
status codes that may be returned, and their meanings, are as follows.
103
Normal, successful completion of the function.
105
+GEIS_BAD_ARGUMENT+::
106
One or more argument values are invalid. Any command taking parameters may
109
+GEIS_STATUS_NOT_SUPPORTED+::
110
An operation or configuration item is not supported by the implementation.
112
+GEIS_UNKNOWN_ERROR+::
113
A general catchall error: an error occurred that is not covered by any other
119
NOTE: This section is not complete.
121
A GEIS instance may be initialized by calling
124
GeisStatus geis_init(GeisWinInfo *win_info, GeisInstance *geis_instance);
127
+GEIS_SUCCESS+ is returned on success and _geis_instance_ is updated with an
128
instance value to be used in subsequent GEIS calls.
130
The definition of the +GeisWinInfo+ fields is entirely dependant on the
131
implementation. For example, an X11-based gesture recognizer may specify the
132
_window_id_ as the _win_info_ argument.
134
Configuration and Control
135
~~~~~~~~~~~~~~~~~~~~~~~~~
137
A particular GEIS implementation may support a subset of standard configuarable
138
items and, in addition, zero or more implementation-specific configuration
139
items. The implementation-specific configuration items will be documented by
142
To determine of a confiuration item is supported, use the following call.
146
GeisStatus geis_configuration_supported(GeisInstance instance,
147
int configuration_item);
150
This function will return +GEIS_STATUS_SUCCESS+ if the _configuration_item_ is
151
supported by the implementation, +GEIS_STATUS_NOT_SUPPORTED+ otherwise.
153
The following standard configuration items must be available.
154
.Input Standard Configuration Items
155
[width="60%",cols="<,3d",frame="topbot",options="header"]
157
|+configuration item+ | description
158
|GEIS_CONFIG_UNIX_FD | A posix descriptor for event loop synchronization is available.
161
Configuration-specifc values may be set and retrieved using the following calls.
165
GeisStatus geis_configuration_get_value(GeisInstance instance,
166
int configuration_item,
169
GeisStatus geis_configuration_set_value(GeisInstance instance,
170
int configuration_item,
174
The actual type and meaning of the _value_ argument depends on the
175
_configuration_item_. Standard configuration item types are described in the
178
.Input Standard Configuration Item Types
179
[width="60%",cols="<,<,2d",frame="topbot",options="header"]
181
|+configuration item+ | type | description
182
|GEIS_CONFIG_UNIX_FD | int | A posix file descriptor
186
Integration with the native event loop is through an implementation-specific
187
mechanism (likely obtained through the configuration calls above, but documented
188
more thoroughly in the implementation documentation) combined with a call to the
189
GEIS dispatch mechanism.
192
GeisStatus geis_event_dispatch(geisInstance instance);
198
Gestures are associated with input devices (a gesture must be input on a
199
device). Client software may subscribe to gestures that occur on all input
200
devices or on only a subset of input devices. For that to be possible, the
201
client needs to enumerate all available input devices. In addition, many input
202
devices have a dynamic lifetime -- they may be added or removed asynchronously.
203
the client software needs to be made aware that new input devices have become
204
available or existing devices have become unavailable.
206
GEIS input device enumeration and availability notification is performed through
207
the following interface.
211
typedef unsigned int GeisInputDeviceId;
213
#define GEIS_ALL_INPUT_DEVICES ((GeisInputDeviceId)0)
215
typedef void (*GeisInputCallback)(void *cookie,
216
GeisInputDeviceId device_id,
219
typedef struct GeisInputFuncs
221
GeisInputCallback added; /**< Receives new input device notices */
222
GeisInputCallback changed; /**< Receives modified input device notices */
223
GeisInputCallback removed; /**< Receives removes input device notices */
227
GeisStatus geis_input_devices(GeisInstance geis_instance,
228
GeisInputFuncs funcs,
232
The API provides a list of available input devices one at a time through the
233
client-supplied _added_ callback function.
235
The _changed_ callback function or the _removed_ callback function may be
236
invoked at any time after *geis_input_devices* is called and before
237
*geis_finish* is called to tear down the +GeisInstance+ or *geis_input_devices*
238
is called again to replace the callback function. This can occur when input
239
devices are, for example, physically connected to or disconnected from the
242
The _cookie_ value passed to *geis_input_devices* is passed unmodified to
243
callback function. Client programs may use this for passing context-specific
244
information into the callback.
246
The suggested behaviour of an implementation is to invoke the _callback_ for
247
each input device known at call time _before_ returning from the
248
*geis_input_devices* call.
250
Subscribing to Gestures
251
~~~~~~~~~~~~~~~~~~~~~~~
253
Gestures are specific to a +GeisInstance+ and set of input devices. The
254
+GeisInstance+ must be informed of the set of gestures (and input devices) of
259
typedef unsigned int GeisGestureType;
260
typedef unsigned int GeisGestureId;
262
#define GEIS_ALL_GESTURES ((GeisGestureType)0)
263
#define GEIS_NO_GESTURE_ID ((GeisGestureId)0)
265
typedef void (*GeisGestureCallback)(void *cookie,
266
GeisGestureType gesture_type,
267
GeisGestureId gesture_id,
269
GeisGestureAttr *attrs);
271
typedef struct GeisGestureFuncs
273
GeisGestureCallback added;
274
GeisGestureCallback removed;
275
GeisGestureCallback start;
276
GeisGestureCallback update;
277
GeisGestureCallback finish;
280
GeisStatus geis_subscribe(GeisInstance geis_instance,
281
GeisInputDeviceId *input_list,
282
const char* *gesture_list,
283
GeisGestureFuncs funcs,
286
GeisStatus geis_unsubscribe(GeisInstance geis_instance,
287
GeisGestureType *gesture_list);
290
The client supplies a list of input devices (or the constant
291
+GEIS_ALL_INPUT_DEVICES+) and a +NULL+ terminated list of C-style strings naming
292
the gestures to be recognized. The constant +GEIS_ALL_GESTURES+ indicates all
293
available gestures should be detected.
295
GEIS provides a list of gestures available in the desired window and input
296
device(s) one at a time through the client-supplied _added_ callback function
297
with the +GEIS_GESTURE_TYPE_ADDED+ action. This allows the client to build a
298
map of gesture names to +GeisGestureType+. If the recognition engine does not
299
support a named gesture type passed to *geis_subscribe* then no
300
+GeisGestureType+ is passed to the callback function for the named gesture.
302
The _cookie_ value passed to *geis_subscribe* is passed unmodified to
303
_callback_. Client programs may use this for passing context-specific
304
information into the callback.
309
One of the gesture event callback functions may be invoked at any time after
310
*geis_input_devices* is called and before *geis_finish* is called to tear down
311
the +GeisInstance+ or *geis_input_devices* is called again to replace the
312
_callback_ function. This can occur when input devices are, for example,
313
physically connected to or disconnected from the system.
315
Most gestures will result in a _start_ callback, zero or more _update_
316
callbacks, and a _finish_ callback. Some gestures such as _tap_ gestures may
317
result in only a single _update_ callback. This behaviour is dependent on the
318
underlying gesture recognition engine
320
Once a gesture is recognized, a +GEIS_GESTURE_STARTED+ action is sent. A set of
321
zero or more attributes will be returned. These attributes are specific to the
322
gesture. Depending on the nature of the gesture, one or more
323
+GEIS_GESTURE_UPDATED+ actions may be sent, and finally a
324
+GEIS_GESTURE_FINISHED+ action will be sent. Each of these may or may not have
325
a set of attributes associated.
327
A gesture or gesture type action is often associated with a set of attributes.
328
These attributes are delivered to the callback function as a read-only array of
329
_GeisGestureAttr_ type, defined below.
333
typedef struct GeisGestureAttr
339
GeisBoolean boolean_val;
341
GeisInteger integer_val;
342
GeisString string_val;
350
Teardown of the gesture recognition session is accomplished by the *geis_finish*
355
GeisStatus geis_finish(GeisInstance *geis_instance);
358
This function frees any allocated resources associated with _geis_instance_. It
359
does not affect other instances.
361
All resources are expected to be freed automatically on process termination.
362
The *geis_finish* function is not expected to return any status value other than
368
A limited number of fundamental gestures are expected to be supplied with the
369
API. All implementations are expected to support at least this set of
370
predefined gestures. Additional predefined gestures and user- or
371
application-defined gestures are beyond the scope of this specification but are
372
expected to be made available by the implementation.
375
[width="60%",cols="<,2d,2d",frame="topbot",options="header"]
376
|========================================================
377
|gesture name |symbolic name |description
378
| Drag | GEIS_GESTURE_DRAG |
379
| Pinch | GEIS_GESTURE_PINCH |
380
| Rotate | GEIS_GESTURE_ROTATE |
381
| Tap | GEIS_GESTURE_TAP |
382
|=========================================================
387
All standard gestures provide a common set of attributes.
389
.Common Gesture Attributes
390
[width="60%",cols="3<,m,d",frame="topbot",options="header"]
391
|=========================================================
392
|name |type |description
393
| GEIS_GESTURE_ATTRIBUTE_DEVICE_ID | GeisInteger |
394
| GEIS_GESTURE_ATTRIBUTE_TIMESTAMP | GeisInteger |
395
| GEIS_GESTURE_ATTRIBUTE_ROOT_WINDOW_ID | GeisInteger |
396
| GEIS_GESTURE_ATTRIBUTE_EVENT_WINDOW_ID | GeisInteger |
397
| GEIS_GESTURE_ATTRIBUTE_CHILD_WINDOW_ID | GeisInteger |
398
| GEIS_GESTURE_ATTRIBUTE_FOCUS_X | GeisFloat |
399
| GEIS_GESTURE_ATTRIBUTE_FOCUS_Y | GeisFloat |
400
| GEIS_GESTURE_ATTRIBUTE_GESTURE_NAME | GeisString |
401
| GEIS_GESTURE_ATTRIBUTE_FINGERS | GeisInteger |
402
|=========================================================
407
NOTE: This section is not complete.
409
.Pan Gesture Attributes
410
[width="60%",cols="3<,m,d",frame="topbot",options="header"]
411
|=========================================================
412
|name |type |description
413
| GEIS_GESTURE_ATTRIBUTE_DELTA_X | GeisFloat |
414
| GEIS_GESTURE_ATTRIBUTE_DELTA_Y | GeisFloat |
415
| GEIS_GESTURE_ATTRIBUTE_VELOCITY_X | GeisFloat |
416
| GEIS_GESTURE_ATTRIBUTE_VELOCITY_Y | GeisFloat |
417
| GEIS_GESTURE_ATTRIBUTE_POSITION_X | GeisFloat |
418
| GEIS_GESTURE_ATTRIBUTE_POSITION_Y | GeisFloat |
419
|=========================================================
424
NOTE: This section is not complete.
426
. Pinch Gesture Attributes
427
[width="60%",cols="3<,m,d",frame="topbot",options="header"]
428
|=========================================================
429
|name |type |description
430
| GEIS_GESTURE_ATTRIBUTE_RADIUS_DELTA | GeisFloat |
431
| GEIS_GESTURE_ATTRIBUTE_RADIAL_VELOCITY | GeisFloat |
432
| GEIS_GESTURE_ATTRIBUTE_RADIUS | GeisFloat |
433
| GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X1 | GeisFloat |
434
| GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y1 | GeisFloat |
435
| GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X2 | GeisFloat |
436
| GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y2 | GeisFloat |
437
|=========================================================
442
NOTE: This section is not complete.
444
. Swipe Gesture Attributes
445
[width="60%",cols="3<,m,d",frame="topbot",options="header"]
446
|=========================================================
447
|name |type |description
448
| GEIS_GESTURE_ATTRIBUTE_ANGLE_DELTA | GeisFloat |
449
| GEIS_GESTURE_ATTRIBUTE_ANGULAR_VELOCITY | GeisFloat |
450
| GEIS_GESTURE_ATTRIBUTE_ANGLE | GeisFloat |
451
|=========================================================
456
NOTE: This section is not complete.
458
.Tap Gesture Attributes
459
[width="60%",cols="3<,m,d",frame="topbot",options="header"]
460
|=========================================================
461
|name |type |description
462
| GEIS_GESTURE_ATTRIBUTE_POSITION_X | GeisFloat |
463
| GEIS_GESTURE_ATTRIBUTE_POSITION_Y | GeisFloat |
464
|=========================================================
467
GEIS Versioning, Header Files, and Constants
468
--------------------------------------------
470
Each published version of GEIS supports the specified client API of that
471
version and all prior versions of those APIs (backwards compatibility).
476
The GEIS specification defines an ISO C language binding. The GEIS header file
477
+<geis/geis.h>+ provides prototypes for all GEIS entry points and C preprocessors
478
for all GEIS tokens, for use both by client code and implementers.
480
Languages other than C and C++ will define GEIS interfaces using other methods
481
outside the scope of this specification.
483
Compile-time Version Detection
484
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486
To allow code to be written portably against future GEIS versions, the
487
compile-time environment must make it possible to determine which GEIS version
488
interface are available. For C and C++ code the +<geis/geis.h>+ header defined C
489
preprocessor symbols corresponding to all versions of GEIS supported by the
494
#define GEIS_VERSION_1_0 1
496
Future versions of GEIS will define additional preprocessor symbols
497
corresponding to the major and minor numbers of those versions.
499
Constants and Implementation-Supplied Values
500
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
502
Constants and enumerator values for GEIS tokens defined in this specification are
503
required to be common across all implementations. A reference version of the
504
+geis.h+ header file can be downloaded from *to be determined*.
506
All implementation-specific types, values, and macros used in +geis.h+ are
507
partitioned into an implementation header, +geisimpl.h+, which is automatically6
508
included by +geis.h+. Implementers should need only modify +geisimpl.h+, never
511
Conformance Testing for Implementers
512
------------------------------------
514
NOTE: This section is not complete.
added
removed
doc/geisspec-1.0.asc
