README-gesture.txt
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Sat, 01 Jun 2013 21:09:36 +0200
changeset 7252 8ecb54eeaeec
parent 7241 28602f5ca96d
child 7900 cc2289c332eb
permissions -rw-r--r--
Corrected indentation of license.
slouken@7222
     1
===========================================================================
slouken@7222
     2
Dollar Gestures
slouken@7222
     3
===========================================================================
slouken@7222
     4
SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
slouken@7222
     5
slouken@7222
     6
Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up. 
slouken@7222
     7
slouken@7222
     8
Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
slouken@7222
     9
slouken@7222
    10
Recording:
slouken@7222
    11
----------
slouken@7222
    12
To begin recording on a touch device call:
slouken@7222
    13
SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch device you wish to record on, or -1 to record on all connected devices.
slouken@7222
    14
slouken@7222
    15
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
slouken@7222
    16
A SDL_DOLLARRECORD event is a dgesture with the following fields:
slouken@7222
    17
slouken@7222
    18
event.dgesture.touchId   - the Id of the touch used to record the gesture.
slouken@7222
    19
event.dgesture.gestureId - the unique id of the recorded gesture.
slouken@7222
    20
slouken@7222
    21
slouken@7222
    22
Performing:
slouken@7222
    23
-----------
slouken@7222
    24
As long as there is a dollar gesture assigned to a touch, every finger-up event will also cause an SDL_DOLLARGESTURE event with the following fields:
slouken@7222
    25
slouken@7222
    26
event.dgesture.touchId    - the Id of the touch which performed the gesture.
slouken@7222
    27
event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
slouken@7222
    28
event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
slouken@7222
    29
event.dgesture.numFingers - the number of fingers used to draw the stroke.
slouken@7222
    30
philipp@7241
    31
Most programs will want to define an appropriate error threshold and check to be sure that the error of a gesture is not abnormally high (an indicator that no gesture was performed).
slouken@7222
    32
slouken@7222
    33
slouken@7222
    34
slouken@7222
    35
Saving:
slouken@7222
    36
-------
slouken@7222
    37
To save a template, call SDL_SaveDollarTemplate(gestureId, src) where gestureId is the id of the gesture you want to save, and src is an SDL_RWops pointer to the file where the gesture will be stored.
slouken@7222
    38
slouken@7222
    39
To save all currently loaded templates, call SDL_SaveAllDollarTemplates(src) where source is an SDL_RWops pointer to the file where the gesture will be stored.
slouken@7222
    40
slouken@7222
    41
Both functions return the number of gestures successfully saved.
slouken@7222
    42
slouken@7222
    43
slouken@7222
    44
Loading:
slouken@7222
    45
--------
slouken@7222
    46
To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file. 
slouken@7222
    47
slouken@7222
    48
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
slouken@7222
    49
slouken@7222
    50
slouken@7222
    51
slouken@7222
    52
===========================================================================
philipp@7241
    53
Multi Gestures
slouken@7222
    54
===========================================================================
slouken@7222
    55
SDL provides simple support for pinch/rotate/swipe gestures. 
slouken@7222
    56
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
slouken@7222
    57
slouken@7222
    58
event.mgesture.touchId - the Id of the touch on which the gesture was performed.
slouken@7222
    59
event.mgesture.x       - the normalized x coordinate of the gesture. (0..1)
slouken@7222
    60
event.mgesture.y       - the normalized y coordinate of the gesture. (0..1)
slouken@7222
    61
event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
slouken@7222
    62
event.mgesture.dDist   - the amount that the fingers pinched during this motion.
slouken@7222
    63
event.mgesture.numFingers - the number of fingers used in the gesture.
slouken@7222
    64
slouken@7222
    65
slouken@7222
    66
===========================================================================
slouken@7222
    67
Notes
slouken@7222
    68
===========================================================================
slouken@7222
    69
For a complete example see test/testgesture.c
slouken@7222
    70
slouken@7222
    71
Please direct questions/comments to:
slouken@7222
    72
   jim.tla+sdl_touch@gmail.com