README.touch
changeset 6987 7084af936d82
parent 4693 2ede56a19f2f
child 7127 5011ddf43295
equal deleted inserted replaced
6986:bc887debed9b 6987:7084af936d82
     3 ===========================================================================
     3 ===========================================================================
     4 Linux:
     4 Linux:
     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.
     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.
     6 
     6 
     7 Mac: 
     7 Mac: 
     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.
     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.
     9 
     9 
    10 iPhone: 
    10 iPhone: 
    11 Works out of box.
    11 Works out of box.
    12 
    12 
    13 Windows:
    13 Windows:
    19 SDL_FINGERDOWN:
    19 SDL_FINGERDOWN:
    20 Sent when a finger (or stylus) is placed on a touch device.
    20 Sent when a finger (or stylus) is placed on a touch device.
    21 Fields:
    21 Fields:
    22 event.tfinger.touchId  - the Id of the touch device.
    22 event.tfinger.touchId  - the Id of the touch device.
    23 event.tfinger.fingerId - the Id of the finger which just went down.
    23 event.tfinger.fingerId - the Id of the finger which just went down.
    24 event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
    24 event.tfinger.x        - the x coordinate of the touch (0..1)
    25 event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
    25 event.tfinger.y        - the y coordinate of the touch (0..1)
    26 event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)
    26 event.tfinger.pressure - the pressure of the touch (0..1)
    27 
    27 
    28 SDL_FINGERMOTION:
    28 SDL_FINGERMOTION:
    29 Sent when a finger (or stylus) is moved on the touch device.
    29 Sent when a finger (or stylus) is moved on the touch device.
    30 Fields:
    30 Fields:
    31 Same as FINGERDOWN but with additional:
    31 Same as FINGERDOWN but with additional:
    32 event.tfginer.dx       - change in x coordinate during this motion event.
    32 event.tfinger.dx       - change in x coordinate during this motion event.
    33 event.tfginer.dy       - change in y coordinate during this motion event.
    33 event.tfinger.dy       - change in y coordinate during this motion event.
    34 
    34 
    35 SDL_FINGERMOTION:
    35 SDL_FINGERUP:
    36 Sent when a finger (or stylus) is lifted from the touch device.
    36 Sent when a finger (or stylus) is lifted from the touch device.
    37 Fields:
    37 Fields:
    38 Same as FINGERDOWN.
    38 Same as FINGERDOWN.
    39 
    39 
    40 
    40 
    41 ===========================================================================
    41 ===========================================================================
    42 Functions
    42 Functions
    43 ===========================================================================
    43 ===========================================================================
    44 SDL provides the ability to access the underlying Touch and Finger structures.
    44 SDL provides the ability to access the underlying Finger structures.
    45 These structures should _never_ be modified.
    45 These structures should _never_ be modified.
    46 
    46 
    47 The following functions are included from SDL_Touch.h
    47 The following functions are included from SDL_touch.h
    48 
    48 
    49 To get a SDL_Touch device call SDL_GetTouch(touchId). 
    49 To get a SDL_TouchID call SDL_GetTouchDevice(index).
    50 This returns an SDL_Touch*. 
    50 This returns a SDL_TouchID.
    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!
    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!
    52 
    52 
    53 An SDL_Touch has the following fields:
    53 The number of touch devices can be queried with SDL_GetNumTouchDevices().
    54 >xres,yres,pressures:
       
    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. 
       
    56 
    54 
    57 >pressure_max, pressure_min, x_max, x_min, y_max, y_min
    55 A SDL_Touch may be used to get pointers to SDL_Finger.
    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.
       
    59 On Mac/iPhone systems _max will always be 0, and _min will always be 1. 
       
    60 
    56 
    61 >native_xres,native_yres,native_pressureres:
    57 SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
    62 	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
       
    63 On Mac/iPhone systems these will always be 1.
       
    64 
    58 
    65 >num_fingers:
    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:
    66 	The number of fingers currently down on the device.
       
    67 
    60 
    68 >fingers:
    61       float x = event.tfinger.x;
    69 	An array of pointers to the fingers which are on the device.
    62       float y = event.tfinger.y;
    70 
       
    71 
       
    72 The most common reason to access a touch device is to normalize inputs. This would be accomplished by code like the following:
       
    73 
       
    74       SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
       
    75       if(inTouch == NULL) continue; //The touch has been removed
       
    76 
       
    77       float x = ((float)event.tfinger.x)/inTouch->xres;
       
    78       float y = ((float)event.tfinger.y)/inTouch->yres;
       
    79 
    63 
    80 
    64 
    81 
    65 
    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.
    66 To get a SDL_Finger, call SDL_GetTouchFinger(touchID,index), where touchID is a SDL_TouchID, and index is the requested finger.
    83 This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
    67 This returns a SDL_Finger*, or NULL if the finger does not exist, or has been removed.
    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. 
    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 FINGERUP event is polled.
    85 As a result, be very careful to check for null return values.
    69 As a result, be very careful to check for NULL return values.
    86 
    70 
    87 An SDL_Finger has the following fields:
    71 A SDL_Finger has the following fields:
    88 >x,y,pressure:
    72 >x,y,pressure:
    89 	The current coordinates of the touch.
    73 	The current coordinates of the touch.
    90 >xdelta,ydelta: 
    74 >pressure:
    91 	The change in position resulting from the last finger motion.
    75 	The pressure of the touch.
    92 >last_x, last_y, last_pressure:
       
    93 	 The previous coordinates of the touch.
       
    94 
    76 
    95 ===========================================================================
    77 ===========================================================================
    96 Notes
    78 Notes
    97 ===========================================================================
    79 ===========================================================================
    98 For a complete example see test/testgesture.c
    80 For a complete example see test/testgesture.c
    99 
    81 
   100 Please direct questions/comments to:
    82 Please direct questions/comments to:
   101    jim.tla+sdl_touch@gmail.com
    83    jim.tla+sdl_touch@gmail.com
       
    84    (original author, API was changed since)