README.touch
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Mon, 29 Apr 2013 23:41:49 +0200
changeset 7127 5011ddf43295
parent 6987 7084af936d82
permissions -rw-r--r--
Corrected names in README file.
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: 
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
     8
The Mac and iPhone APIs 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.
4690
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.
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    24
event.tfinger.x        - the x coordinate of the touch (0..1)
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    25
event.tfinger.y        - the y coordinate of the touch (0..1)
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    26
event.tfinger.pressure - the pressure of the touch (0..1)
4689
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:
7127
5011ddf43295 Corrected names in README file.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 6987
diff changeset
    31
Same as SDL_FINGERDOWN but with additional:
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    32
event.tfinger.dx       - change in x coordinate during this motion event.
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    33
event.tfinger.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
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    35
SDL_FINGERUP:
4689
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:
7127
5011ddf43295 Corrected names in README file.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 6987
diff changeset
    38
Same as SDL_FINGERDOWN.
4689
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
===========================================================================
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    44
SDL provides the ability to access the underlying Finger structures.
4689
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
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    47
The following functions are included from SDL_touch.h
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    48
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    49
To get a SDL_TouchID call SDL_GetTouchDevice(index).
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    50
This returns a SDL_TouchID.
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    51
IMPORTANT: If the touch has been removed, or there is no touch with the given ID, SDL_GetTouchID will return 0. Be sure to check for this!
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    52
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    53
The number of touch devices can be queried with SDL_GetNumTouchDevices().
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    54
7127
5011ddf43295 Corrected names in README file.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 6987
diff changeset
    55
A SDL_TouchID may be used to get pointers to SDL_Finger.
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    56
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    57
SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    58
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    59
The most common reason to access SDL_Finger is to query the fingers outside the event. In most cases accessing the fingers is using the event. 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
    60
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    61
      float x = event.tfinger.x;
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    62
      float y = event.tfinger.y;
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    63
4689
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
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    66
To get a SDL_Finger, call SDL_GetTouchFinger(touchID,index), where touchID is a SDL_TouchID, and index is the requested finger.
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    67
This returns a SDL_Finger*, or NULL if the finger does not exist, or has been removed.
7127
5011ddf43295 Corrected names in README file.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 6987
diff changeset
    68
A 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 SDL_FINGERUP event is polled.
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    69
As a result, be very careful to check for NULL return values.
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    70
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    71
A SDL_Finger has the following fields:
4689
f9ab8df6d45a Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture
Jim Grandpre <jim.tla@gmail.com>
parents:
diff changeset
    72
>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
    73
	The current coordinates of the touch.
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    74
>pressure:
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    75
	The pressure of the touch.
4690
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    76
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    77
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    78
Notes
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    79
===========================================================================
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    80
For a complete example see test/testgesture.c
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    81
baf8195aeb92 Updated README's
Jim Grandpre <jim.tla@gmail.com>
parents: 4689
diff changeset
    82
Please direct questions/comments to:
4693
2ede56a19f2f Fixed some typos in the documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4690
diff changeset
    83
   jim.tla+sdl_touch@gmail.com
6987
7084af936d82 Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
Sam Lantinga <slouken@libsdl.org>
parents: 4693
diff changeset
    84
   (original author, API was changed since)