README.gesture
author Jim Grandpre <jim.tla@gmail.com>
Thu, 19 Aug 2010 13:47:12 -0400
changeset 4690 baf8195aeb92
parent 4689 f9ab8df6d45a
child 4693 2ede56a19f2f
permissions -rw-r--r--
Updated README's
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     1
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     2
Dollar Gestures
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     3
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     4
SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     5
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     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. 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     7
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     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.
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
     9
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    10
Recording:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    11
----------
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    12
To begin recording on a touch device call:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    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.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    14
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    15
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    16
A SDL_DOLLARRECORD event is a dgesture with the following fields:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    17
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    18
event.dgesture.touchId   - the Id of the touch used to record the gesture.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    19
event.dgesture.gestureId - the unique id of the recoreded gesture.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    20
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    21
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    22
Performing:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    23
-----------
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    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:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    25
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    26
event.dgesture.touchId    - the Id of the touch which performed the gesture.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    27
event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    28
event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    29
event.dgesture.numFingers - the number of fingers used to draw the stroke.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    30
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    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). 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    32
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    33
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    34
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    35
Saving:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    36
-------
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    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.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    38
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    39
To save all currently loaded templatesm, call SDL_SaveAllDollarTemplates(src) where source is an SDL_RWops pointer to the file where the gesture will be stored.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    40
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    41
Both functions return the number of gestures sucessfully saved.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    42
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    43
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    44
Loading:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    45
--------
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    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. 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    47
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    48
SDL_LoadDollarTemplates returns the number of templates sucessfully loaded. 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    49
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    50
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    51
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    52
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    53
Multi Gestures
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    54
===========================================================================
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    55
SDL provides simple support for pinch/rotate/swipe gestures. 
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    56
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    57
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    58
event.mgesture.touchId - the Id of the touch on which the gesture was performed.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    59
event.mgesture.x       - the normalized x cooridinate of the gesture. (0..1)
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    60
event.mgesture.y       - the normalized y cooridinate of the gesture. (0..1)
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    61
event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    62
event.mgesture.dDist   - the amount that the fingers pinched during this motion.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    63
event.mgesture.numFingers - the number of fingers used in the gesture.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    64
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    65
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    66
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    67
Notes
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    68
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    69
For a complete example see test/testgesture.c
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    70
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    71
Please direct questions/comments to:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    72
   jim.tla+sdl_touch@gmail.com