docs/README-gesture.md
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Wed, 17 Aug 2016 21:04:50 +0200
changeset 10275 ba7dc3ebb81e
parent 9464 ae7a6c8cc189
permissions -rw-r--r--
Emscripten: Fixed opening previously closed joystick.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     1
Dollar Gestures
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     2
===========================================================================
9464
ae7a6c8cc189 Fixed typo in gesture README.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9066
diff changeset
     3
SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     4
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     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. 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     6
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     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.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     8
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     9
Recording:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    10
----------
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    11
To begin recording on a touch device call:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    13
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    14
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    15
A SDL_DOLLARRECORD event is a dgesture with the following fields:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    16
9066
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    17
* event.dgesture.touchId   - the Id of the touch used to record the gesture.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    18
* event.dgesture.gestureId - the unique id of the recorded gesture.
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    19
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    20
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    21
Performing:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    22
-----------
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    24
9066
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    25
* event.dgesture.touchId    - the Id of the touch which performed the gesture.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    26
* event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    27
* event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    28
* event.dgesture.numFingers - the number of fingers used to draw the stroke.
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    29
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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).
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    31
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    32
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    33
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    34
Saving:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    35
-------
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    37
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    39
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    40
Both functions return the number of gestures successfully saved.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    41
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    42
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    43
Loading:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    44
--------
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    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. 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    46
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    47
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    48
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    49
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    50
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    51
===========================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    52
Multi Gestures
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    53
===========================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    54
SDL provides simple support for pinch/rotate/swipe gestures. 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    55
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    56
9066
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    57
* event.mgesture.touchId - the Id of the touch on which the gesture was performed.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    58
* event.mgesture.x       - the normalized x coordinate of the gesture. (0..1)
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    59
* event.mgesture.y       - the normalized y coordinate of the gesture. (0..1)
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    60
* event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    61
* event.mgesture.dDist   - the amount that the fingers pinched during this motion.
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    62
* event.mgesture.numFingers - the number of fingers used in the gesture.
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    63
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    64
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    65
===========================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    66
Notes
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    67
===========================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    68
For a complete example see test/testgesture.c
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    69
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    70
Please direct questions/comments to:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    71
   jim.tla+sdl_touch@gmail.com