author Jim Grandpre <>
Sun, 15 Aug 2010 00:36:28 -0400
changeset 4689 f9ab8df6d45a
child 4690 baf8195aeb92
permissions -rw-r--r--
Added README.touch and README.gesture. Moved touchtest/gestureSDLTest to test/testgesture

Sent when a finger (or stylus) is placed on a touch device.
event.tfinger.touchId  - the Id of the touch device.
event.tfinger.fingerId - the Id of the finger which just went down.
event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)

Sent when a finger (or stylus) is moved on the touch device.
Same as FINGERDOWN but with additional:
event.tfginer.dx       - chagne in x coordinate during this motion event.
event.tfginer.dy       - chagne in y coordinate during this motion event.

Sent when a finger (or stylus) is lifted from the touch device.

SDL provides the ability to access the underlying Touch and Finger structures.
These structures should _never_ be modified.

The following functions are included from SDL_Touch.h

To get a SDL_Touch device call SDL_GetTouch(touchId). 
This returns an SDL_Touch*. 
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!

An SDL_Touch has the following fields:
>pressure_max, pressure_min, x_max, x_min, y_max, y_min
	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.
On Mac/iPhone systems _max will always be 0, and _min will always be 1. 

	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. 

	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
On Mac/iPhone systems these will always be 1.

	The number of fingers currently down on the device.

	An array of pointers to the fingers which are on the device.

The most common reason to get a touch device is to normalize inputs. This would look something like:

      SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
      if(inTouch == NULL) continue;

      float x = ((float)event.tfinger.x)/inTouch->xres;
      float y = ((float)event.tfinger.y)/inTouch->yres;      

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.
This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
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 seen. 
As a result, be very careful to check for null return values.

An SDL_Finger has the following fields:
	The current coordinates of the touch.
	The change in position resulting from the last finger motion.
>last_x, last_y, last_pressure:
	 The previous coordinates of the touch.