README-touch.txt
author Sam Lantinga <slouken@libsdl.org>
Sun, 26 May 2013 11:06:17 -0700
changeset 7222 2435b221d77d
parent 7127 README.touch@5011ddf43295
child 7241 28602f5ca96d
permissions -rw-r--r--
Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Updated Makefile.in so "make dist" includes everything necessary for release.
slouken@7222
     1
===========================================================================
slouken@7222
     2
System Specific Notes
slouken@7222
     3
===========================================================================
slouken@7222
     4
Linux:
slouken@7222
     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.
slouken@7222
     6
slouken@7222
     7
ac: 
slouken@7222
     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.
slouken@7222
     9
slouken@7222
    10
iPhone: 
slouken@7222
    11
Works out of box.
slouken@7222
    12
slouken@7222
    13
Windows:
slouken@7222
    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
slouken@7222
    15
slouken@7222
    16
===========================================================================
slouken@7222
    17
Events
slouken@7222
    18
===========================================================================
slouken@7222
    19
SDL_FINGERDOWN:
slouken@7222
    20
Sent when a finger (or stylus) is placed on a touch device.
slouken@7222
    21
Fields:
slouken@7222
    22
event.tfinger.touchId  - the Id of the touch device.
slouken@7222
    23
event.tfinger.fingerId - the Id of the finger which just went down.
slouken@7222
    24
event.tfinger.x        - the x coordinate of the touch (0..1)
slouken@7222
    25
event.tfinger.y        - the y coordinate of the touch (0..1)
slouken@7222
    26
event.tfinger.pressure - the pressure of the touch (0..1)
slouken@7222
    27
slouken@7222
    28
SDL_FINGERMOTION:
slouken@7222
    29
Sent when a finger (or stylus) is moved on the touch device.
slouken@7222
    30
Fields:
slouken@7222
    31
Same as SDL_FINGERDOWN but with additional:
slouken@7222
    32
event.tfinger.dx       - change in x coordinate during this motion event.
slouken@7222
    33
event.tfinger.dy       - change in y coordinate during this motion event.
slouken@7222
    34
slouken@7222
    35
SDL_FINGERUP:
slouken@7222
    36
Sent when a finger (or stylus) is lifted from the touch device.
slouken@7222
    37
Fields:
slouken@7222
    38
Same as SDL_FINGERDOWN.
slouken@7222
    39
slouken@7222
    40
slouken@7222
    41
===========================================================================
slouken@7222
    42
Functions
slouken@7222
    43
===========================================================================
slouken@7222
    44
SDL provides the ability to access the underlying Finger structures.
slouken@7222
    45
These structures should _never_ be modified.
slouken@7222
    46
slouken@7222
    47
The following functions are included from SDL_touch.h
slouken@7222
    48
slouken@7222
    49
To get a SDL_TouchID call SDL_GetTouchDevice(index).
slouken@7222
    50
This returns a SDL_TouchID.
slouken@7222
    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!
slouken@7222
    52
slouken@7222
    53
The number of touch devices can be queried with SDL_GetNumTouchDevices().
slouken@7222
    54
slouken@7222
    55
A SDL_TouchID may be used to get pointers to SDL_Finger.
slouken@7222
    56
slouken@7222
    57
SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
slouken@7222
    58
slouken@7222
    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:
slouken@7222
    60
slouken@7222
    61
      float x = event.tfinger.x;
slouken@7222
    62
      float y = event.tfinger.y;
slouken@7222
    63
slouken@7222
    64
slouken@7222
    65
slouken@7222
    66
To get a SDL_Finger, call SDL_GetTouchFinger(touchID,index), where touchID is a SDL_TouchID, and index is the requested finger.
slouken@7222
    67
This returns a SDL_Finger*, or NULL if the finger does not exist, or has been removed.
slouken@7222
    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.
slouken@7222
    69
As a result, be very careful to check for NULL return values.
slouken@7222
    70
slouken@7222
    71
A SDL_Finger has the following fields:
slouken@7222
    72
>x,y,pressure:
slouken@7222
    73
	The current coordinates of the touch.
slouken@7222
    74
>pressure:
slouken@7222
    75
	The pressure of the touch.
slouken@7222
    76
slouken@7222
    77
===========================================================================
slouken@7222
    78
Notes
slouken@7222
    79
===========================================================================
slouken@7222
    80
For a complete example see test/testgesture.c
slouken@7222
    81
slouken@7222
    82
Please direct questions/comments to:
slouken@7222
    83
   jim.tla+sdl_touch@gmail.com
slouken@7222
    84
   (original author, API was changed since)