README.touch
author Sam Lantinga <slouken@libsdl.org>
Thu, 25 Apr 2013 00:26:17 -0700
changeset 7110 2a98852fd58d
parent 6987 7084af936d82
child 7127 5011ddf43295
permissions -rw-r--r--
Fixed bug 1582 - Allow disabling SDL_VIDEO_DRIVER_WINDOWS

Marcus von Appen

Trying to build SDL 2.x (HG) on Win32 platforms with either VS.NET or MinGW requires one to have the video subsystem and SDL_VIDEO_DRIVER_WINDOWS flag enabled due to the helper window creation routines.

The attached patch changes the helper window creation behaviour, so that one can build SDL2 without the video subsystem or Windows video drivers on Win32 platforms.
jim@4690
     1
===========================================================================
jim@4690
     2
System Specific Notes
jim@4690
     3
===========================================================================
jim@4690
     4
Linux:
jim@4690
     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.
jim@4690
     6
jim@4690
     7
Mac: 
slouken@6987
     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.
jim@4690
     9
jim@4690
    10
iPhone: 
jim@4690
    11
Works out of box.
jim@4690
    12
slouken@4693
    13
Windows:
jim@4690
    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
jim@4690
    15
jim@4689
    16
===========================================================================
jim@4689
    17
Events
jim@4689
    18
===========================================================================
jim@4689
    19
SDL_FINGERDOWN:
jim@4689
    20
Sent when a finger (or stylus) is placed on a touch device.
jim@4689
    21
Fields:
jim@4689
    22
event.tfinger.touchId  - the Id of the touch device.
jim@4689
    23
event.tfinger.fingerId - the Id of the finger which just went down.
slouken@6987
    24
event.tfinger.x        - the x coordinate of the touch (0..1)
slouken@6987
    25
event.tfinger.y        - the y coordinate of the touch (0..1)
slouken@6987
    26
event.tfinger.pressure - the pressure of the touch (0..1)
jim@4689
    27
jim@4689
    28
SDL_FINGERMOTION:
jim@4689
    29
Sent when a finger (or stylus) is moved on the touch device.
jim@4689
    30
Fields:
jim@4689
    31
Same as FINGERDOWN but with additional:
slouken@6987
    32
event.tfinger.dx       - change in x coordinate during this motion event.
slouken@6987
    33
event.tfinger.dy       - change in y coordinate during this motion event.
jim@4689
    34
slouken@6987
    35
SDL_FINGERUP:
jim@4689
    36
Sent when a finger (or stylus) is lifted from the touch device.
jim@4689
    37
Fields:
jim@4689
    38
Same as FINGERDOWN.
jim@4689
    39
jim@4689
    40
jim@4689
    41
===========================================================================
jim@4689
    42
Functions
jim@4689
    43
===========================================================================
slouken@6987
    44
SDL provides the ability to access the underlying Finger structures.
jim@4689
    45
These structures should _never_ be modified.
jim@4689
    46
slouken@6987
    47
The following functions are included from SDL_touch.h
jim@4689
    48
slouken@6987
    49
To get a SDL_TouchID call SDL_GetTouchDevice(index).
slouken@6987
    50
This returns a SDL_TouchID.
slouken@6987
    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!
jim@4690
    52
slouken@6987
    53
The number of touch devices can be queried with SDL_GetNumTouchDevices().
jim@4689
    54
slouken@6987
    55
A SDL_Touch may be used to get pointers to SDL_Finger.
jim@4689
    56
slouken@6987
    57
SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
jim@4689
    58
slouken@6987
    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:
jim@4689
    60
slouken@6987
    61
      float x = event.tfinger.x;
slouken@6987
    62
      float y = event.tfinger.y;
jim@4690
    63
jim@4689
    64
jim@4689
    65
slouken@6987
    66
To get a SDL_Finger, call SDL_GetTouchFinger(touchID,index), where touchID is a SDL_TouchID, and index is the requested finger.
slouken@6987
    67
This returns a SDL_Finger*, or NULL if the finger does not exist, or has been removed.
slouken@6987
    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.
slouken@6987
    69
As a result, be very careful to check for NULL return values.
jim@4689
    70
slouken@6987
    71
A SDL_Finger has the following fields:
jim@4689
    72
>x,y,pressure:
jim@4689
    73
	The current coordinates of the touch.
slouken@6987
    74
>pressure:
slouken@6987
    75
	The pressure of the touch.
jim@4690
    76
jim@4690
    77
===========================================================================
jim@4690
    78
Notes
jim@4690
    79
===========================================================================
jim@4690
    80
For a complete example see test/testgesture.c
jim@4690
    81
jim@4690
    82
Please direct questions/comments to:
slouken@4693
    83
   jim.tla+sdl_touch@gmail.com
slouken@6987
    84
   (original author, API was changed since)