README.gesture
author Sam Lantinga <slouken@libsdl.org>
Sun, 09 Jan 2011 08:35:18 -0800
changeset 4968 379361d5e425
parent 4693 2ede56a19f2f
child 6987 7084af936d82
permissions -rw-r--r--
Jcw87 to Sam

The project files for VS 2005 are still outdated/messed up. I have a patch that will bring the VS 2005 project files up to date with the VS 2008 project files, add the x64 platform to the VS 2005 project files, fix a few issues with x64 in VS 2008, and a few other misc changes that don't really change the output at all.
jim@4689
     1
===========================================================================
jim@4689
     2
Dollar Gestures
jim@4689
     3
===========================================================================
jim@4689
     4
SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
jim@4689
     5
jim@4689
     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. 
jim@4689
     7
jim@4690
     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.
jim@4689
     9
jim@4689
    10
Recording:
jim@4689
    11
----------
jim@4689
    12
To begin recording on a touch device call:
jim@4689
    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.
jim@4689
    14
jim@4689
    15
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
jim@4689
    16
A SDL_DOLLARRECORD event is a dgesture with the following fields:
jim@4689
    17
jim@4689
    18
event.dgesture.touchId   - the Id of the touch used to record the gesture.
jim@4689
    19
event.dgesture.gestureId - the unique id of the recoreded gesture.
jim@4689
    20
jim@4689
    21
jim@4689
    22
Performing:
jim@4689
    23
-----------
jim@4689
    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:
jim@4689
    25
jim@4689
    26
event.dgesture.touchId    - the Id of the touch which performed the gesture.
jim@4689
    27
event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
jim@4689
    28
event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
jim@4689
    29
event.dgesture.numFingers - the number of fingers used to draw the stroke.
jim@4689
    30
jim@4689
    31
Most programs will want to define an appropriate error threshold and check to be sure taht the error of a gesture is not abnormally high (an indicator that no gesture was performed). 
jim@4689
    32
jim@4689
    33
jim@4689
    34
jim@4689
    35
Saving:
jim@4689
    36
-------
jim@4689
    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.
jim@4689
    38
slouken@4693
    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.
jim@4689
    40
jim@4689
    41
Both functions return the number of gestures sucessfully saved.
jim@4689
    42
jim@4689
    43
jim@4689
    44
Loading:
jim@4689
    45
--------
jim@4689
    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. 
jim@4689
    47
jim@4689
    48
SDL_LoadDollarTemplates returns the number of templates sucessfully loaded. 
jim@4689
    49
jim@4689
    50
jim@4689
    51
jim@4689
    52
===========================================================================
jim@4689
    53
Multi Gestures
jim@4689
    54
===========================================================================
jim@4690
    55
SDL provides simple support for pinch/rotate/swipe gestures. 
jim@4689
    56
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
jim@4689
    57
jim@4689
    58
event.mgesture.touchId - the Id of the touch on which the gesture was performed.
jim@4689
    59
event.mgesture.x       - the normalized x cooridinate of the gesture. (0..1)
jim@4689
    60
event.mgesture.y       - the normalized y cooridinate of the gesture. (0..1)
jim@4689
    61
event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
jim@4689
    62
event.mgesture.dDist   - the amount that the fingers pinched during this motion.
jim@4689
    63
event.mgesture.numFingers - the number of fingers used in the gesture.
jim@4689
    64
jim@4689
    65
jim@4689
    66
===========================================================================
jim@4689
    67
Notes
jim@4689
    68
===========================================================================
jim@4689
    69
For a complete example see test/testgesture.c
jim@4689
    70
jim@4689
    71
Please direct questions/comments to:
slouken@4693
    72
   jim.tla+sdl_touch@gmail.com