doc/README-gesture.md
author Gabriel Jacobo
Tue, 29 Jul 2014 09:20:12 -0300
changeset 9023 276802355854
permissions -rw-r--r--
Rearrange documentation

1) Moves all READMEs to docs/
2) Renames them to *.md, adds some Markdown with the idea to add a lot more
3) Moves the doxyfile config to doc/ and makes it parse the headers at ../include as well as the md files in docs.
4) Skips SDL_opengl*.h headers from the docs
5) Minor fixes to doxyfile
gabomdq@9023
     1
Dollar Gestures
gabomdq@9023
     2
===========================================================================
gabomdq@9023
     3
SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
gabomdq@9023
     4
gabomdq@9023
     5
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. 
gabomdq@9023
     6
gabomdq@9023
     7
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.
gabomdq@9023
     8
gabomdq@9023
     9
Recording:
gabomdq@9023
    10
----------
gabomdq@9023
    11
To begin recording on a touch device call:
gabomdq@9023
    12
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.
gabomdq@9023
    13
gabomdq@9023
    14
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
gabomdq@9023
    15
A SDL_DOLLARRECORD event is a dgesture with the following fields:
gabomdq@9023
    16
gabomdq@9023
    17
event.dgesture.touchId   - the Id of the touch used to record the gesture.
gabomdq@9023
    18
event.dgesture.gestureId - the unique id of the recorded gesture.
gabomdq@9023
    19
gabomdq@9023
    20
gabomdq@9023
    21
Performing:
gabomdq@9023
    22
-----------
gabomdq@9023
    23
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:
gabomdq@9023
    24
gabomdq@9023
    25
event.dgesture.touchId    - the Id of the touch which performed the gesture.
gabomdq@9023
    26
event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
gabomdq@9023
    27
event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
gabomdq@9023
    28
event.dgesture.numFingers - the number of fingers used to draw the stroke.
gabomdq@9023
    29
gabomdq@9023
    30
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).
gabomdq@9023
    31
gabomdq@9023
    32
gabomdq@9023
    33
gabomdq@9023
    34
Saving:
gabomdq@9023
    35
-------
gabomdq@9023
    36
To save a template, call SDL_SaveDollarTemplate(gestureId, dst) where gestureId is the id of the gesture you want to save, and dst is an SDL_RWops pointer to the file where the gesture will be stored.
gabomdq@9023
    37
gabomdq@9023
    38
To save all currently loaded templates, call SDL_SaveAllDollarTemplates(dst) where dst is an SDL_RWops pointer to the file where the gesture will be stored.
gabomdq@9023
    39
gabomdq@9023
    40
Both functions return the number of gestures successfully saved.
gabomdq@9023
    41
gabomdq@9023
    42
gabomdq@9023
    43
Loading:
gabomdq@9023
    44
--------
gabomdq@9023
    45
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. 
gabomdq@9023
    46
gabomdq@9023
    47
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
gabomdq@9023
    48
gabomdq@9023
    49
gabomdq@9023
    50
gabomdq@9023
    51
===========================================================================
gabomdq@9023
    52
Multi Gestures
gabomdq@9023
    53
===========================================================================
gabomdq@9023
    54
SDL provides simple support for pinch/rotate/swipe gestures. 
gabomdq@9023
    55
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
gabomdq@9023
    56
gabomdq@9023
    57
event.mgesture.touchId - the Id of the touch on which the gesture was performed.
gabomdq@9023
    58
event.mgesture.x       - the normalized x coordinate of the gesture. (0..1)
gabomdq@9023
    59
event.mgesture.y       - the normalized y coordinate of the gesture. (0..1)
gabomdq@9023
    60
event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
gabomdq@9023
    61
event.mgesture.dDist   - the amount that the fingers pinched during this motion.
gabomdq@9023
    62
event.mgesture.numFingers - the number of fingers used in the gesture.
gabomdq@9023
    63
gabomdq@9023
    64
gabomdq@9023
    65
===========================================================================
gabomdq@9023
    66
Notes
gabomdq@9023
    67
===========================================================================
gabomdq@9023
    68
For a complete example see test/testgesture.c
gabomdq@9023
    69
gabomdq@9023
    70
Please direct questions/comments to:
gabomdq@9023
    71
   jim.tla+sdl_touch@gmail.com