Mercurial > sdl-ios-xcode

annotate README.touch @ 4694:c24ba2cc9583

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged Jim's Google Summer of Code work from SDL-gsoc2010_gesture
author Sam Lantinga <slouken@libsdl.org>
date Sun, 22 Aug 2010 12:07:55 -0700
parents 2ede56a19f2f
children
rev   line source
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
4693
2ede56a19f2f Fixed some typos in the documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4690
diff changeset
13 Windows:
4690
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:
4693
2ede56a19f2f Fixed some typos in the documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4690
diff changeset
101 jim.tla+sdl_touch@gmail.com