README.gesture
author Sam Lantinga <slouken@libsdl.org>
Thu, 16 May 2013 00:43:22 -0700
changeset 7180 3733e68edbc3
parent 6987 7084af936d82
permissions -rw-r--r--
Fixed bug 1846 - _allmul implementation in SDL_stdlib.c doesn't clean up the stack

Colin Barrett

I see this manifest itself (VS2012 x86) as:

"Run-Time Check Failure #0 - The value of ESP was not properly saved across a function call. This is usually a result of calling a function declared with one calling convention with a function pointer declared with a different calling convention."

in the first call to SDL_GetTicks in my application. The disassembly at the problem line is:

hires_now.QuadPart *= 1000;
00AD0792 push 0
00AD0794 push 3E8h
00AD0799 mov eax,dword ptr [ebp-10h]
00AD079C push eax
00AD079D mov ecx,dword ptr [hires_now]
00AD07A0 push ecx
00AD07A1 call _allmul (0AE7D40h)
00AD07A6 mov dword ptr [hires_now],eax
00AD07A9 mov dword ptr [ebp-10h],edx

Apparently _allmul should be popping the stack but isn't (other similar functions in SDL_stdlib.c - _alldiv and whatnot - DO pop the stack).

A 'ret 10h' at the end of _allmul appears to do the trick
     1 ===========================================================================
     2 Dollar Gestures
     3 ===========================================================================
     4 SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
     5 
     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. 
     7 
     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.
     9 
    10 Recording:
    11 ----------
    12 To begin recording on a touch device call:
    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.
    14 
    15 Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
    16 A SDL_DOLLARRECORD event is a dgesture with the following fields:
    17 
    18 event.dgesture.touchId   - the Id of the touch used to record the gesture.
    19 event.dgesture.gestureId - the unique id of the recorded gesture.
    20 
    21 
    22 Performing:
    23 -----------
    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:
    25 
    26 event.dgesture.touchId    - the Id of the touch which performed the gesture.
    27 event.dgesture.gestureId  - the unique id of the closest gesture to the performed stroke.
    28 event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
    29 event.dgesture.numFingers - the number of fingers used to draw the stroke.
    30 
    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).
    32 
    33 
    34 
    35 Saving:
    36 -------
    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.
    38 
    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.
    40 
    41 Both functions return the number of gestures successfully saved.
    42 
    43 
    44 Loading:
    45 --------
    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. 
    47 
    48 SDL_LoadDollarTemplates returns the number of templates successfully loaded.
    49 
    50 
    51 
    52 ===========================================================================
    53 Multi Gestures
    54 ===========================================================================
    55 SDL provides simple support for pinch/rotate/swipe gestures. 
    56 Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
    57 
    58 event.mgesture.touchId - the Id of the touch on which the gesture was performed.
    59 event.mgesture.x       - the normalized x coordinate of the gesture. (0..1)
    60 event.mgesture.y       - the normalized y coordinate of the gesture. (0..1)
    61 event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
    62 event.mgesture.dDist   - the amount that the fingers pinched during this motion.
    63 event.mgesture.numFingers - the number of fingers used in the gesture.
    64 
    65 
    66 ===========================================================================
    67 Notes
    68 ===========================================================================
    69 For a complete example see test/testgesture.c
    70 
    71 Please direct questions/comments to:
    72    jim.tla+sdl_touch@gmail.com