README.touch
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:
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     1
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     2
System Specific Notes
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     3
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     4
Linux:
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     5
The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at jim.tla+sdl_touch@gmail.com and I will help you get support for it.
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     6
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     7
Mac: 
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     8
The Mac and Iphone API's are pretty. If your touch device supports them then you'll be fine. If it doesn't, then there isn't much we can do.
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
     9
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    10
iPhone: 
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    11
Works out of box.
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    12
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    13
Winows:
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    14
Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at jim.tla+sdl_touch@gmail.com
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    15
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    16
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    17
Events
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    18
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    19
SDL_FINGERDOWN:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    20
Sent when a finger (or stylus) is placed on a touch device.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    21
Fields:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    22
event.tfinger.touchId  - the Id of the touch device.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    23
event.tfinger.fingerId - the Id of the finger which just went down.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    24
event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    25
event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    26
event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    27
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    28
SDL_FINGERMOTION:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    29
Sent when a finger (or stylus) is moved on the touch device.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    30
Fields:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    31
Same as FINGERDOWN but with additional:
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    32
event.tfginer.dx       - change in x coordinate during this motion event.
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    33
event.tfginer.dy       - change in y coordinate during this motion event.
4689
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
SDL_FINGERMOTION:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    36
Sent when a finger (or stylus) is lifted from the touch device.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    37
Fields:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    38
Same as FINGERDOWN.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    39
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
===========================================================================
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    42
Functions
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
SDL provides the ability to access the underlying Touch and Finger structures.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    45
These structures should _never_ be modified.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    46
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    47
The following functions are included from SDL_Touch.h
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    48
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    49
To get a SDL_Touch device call SDL_GetTouch(touchId). 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    50
This returns an SDL_Touch*. 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    51
IMPORTANT: If the touch has been removed, or there is no touch with the given ID, SDL_GetTouch will return null. Be sure to check for this!
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
An SDL_Touch has the following fields:
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    54
>xres,yres,pressures:
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    55
	The resolution at which x,y, and pressure values are reported. Currently these will always be equal to 2^15, but this may not always be the case. 
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    56
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    57
>pressure_max, pressure_min, x_max, x_min, y_max, y_min
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    58
	Which give, respectively, the maximum and minumum values that the touch digitizer can return for pressure, x coordiniate, and y coordinate AS REPORTED BY THE OPERATING SYSTEM.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    59
On Mac/iPhone systems _max will always be 0, and _min will always be 1. 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    60
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    61
>native_xres,native_yres,native_pressureres:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    62
	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    63
On Mac/iPhone systems these will always be 1.
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
>num_fingers:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    66
	The number of fingers currently down on the device.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    67
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    68
>fingers:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    69
	An array of pointers to the fingers which are on the device.
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
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    72
The most common reason to access a touch device is to normalize inputs. This would be accomplished by code like the following:
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    73
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    74
      SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    75
      if(inTouch == NULL) continue; //The touch has been removed
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    76
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    77
      float x = ((float)event.tfinger.x)/inTouch->xres;
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    78
      float y = ((float)event.tfinger.y)/inTouch->yres;
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    79
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    80
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    81
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    82
To get an SDL_Finger, call SDL_GetFinger(touch,fingerId), where touch is a pointer to an SDL_Touch device, and fingerId is the id of the requested finger.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    83
This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    84
An SDL_Finger is guaranteed to be persistent for the duration of a touch, but it will be de-allocated as soon as the finger is removed. This occurs when the SDL_FINGERUP event is _added_ to the event queue, and thus _before_ the FINGERUP event is polled. 
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    85
As a result, be very careful to check for null return values.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    86
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    87
An SDL_Finger has 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
    88
>x,y,pressure:
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    89
	The current coordinates of the touch.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    90
>xdelta,ydelta: 
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    91
	The change in position resulting from the last finger motion.
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    92
>last_x, last_y, last_pressure:
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    93
	 The previous coordinates of the touch.
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    94
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    95
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    96
Notes
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    97
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    98
For a complete example see test/testgesture.c
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    99
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
   100
Please direct questions/comments to:
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
   101
   jim.tla+sdl_touch@gmail.com