docs/README-touch.md
author Ryan C. Gordon <icculus@icculus.org>
Mon, 29 Oct 2018 20:00:03 -0400
changeset 12369 68c87b40b434
parent 10486 5bf595c48fd4
permissions -rw-r--r--
winmain: Don't use SDL_malloc (or SDL_stack_alloc, which might be malloc).

Otherwise, we are using the allocator before the app can set up its own hooks.

Now we use VirtualAlloc, and WideCharToMultiByte (because SDL_iconv uses
SDL_malloc, too!) to get ready to call into SDL_main.

This also makes console_wmain() call into the same routines as everything
else, so we don't have to deal with those allocations, too. Hopefully we
end up with the same results from GetCommandLine() as we do in wargv.

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