IupTuioClient (since 3.3)

Implements a TUIO protocol client that allows the use of multi-touch devices. It can use any TUIO server, but it was tested with the Community Core Vision (CCV) from the NUI Group.

Initialization and usage

The IupTuioOpen function must be called after a IupOpen, so that the control can be used. The iuptuio.h file must also be included in the source code. The program must be linked to the controls library (iuptuio). There is no external dependencies, the TUIO client library is already included.

To make the control available in Lua use require"iupluatuio" or manually call the initialization function in C, iuptuiolua_open, after calling iuplua_open. When manually calling the function the iupluatuio.h file must also be included in the source code and the program must be linked to the respective Lua control library (iupluatuio).

Creation

Ihandle* IupTuioClient(int port); [in C]
iup.tuioclient{[port: number]} -> (ih: ihandle) [in Lua]
tuioclient(port) [in LED]

port: the UDP port used to connect to the TUIO server. If 0 is specified then the default value of 3333 will be used (in Lua it can be simply omitted).

Returns: the identifier of the created element, or NULL if an error occurs.

Attributes

CONNECT: connects (YES) or disconnects (NO) to the TUIO server. Returns the connected state. If LOCKED is used when connected the IupSetAttribute will not return until it is disconnected (not recommended).

DEBUG: when set will enable a print a log of TUIO cursor messages on standard output.

TARGETCANVAS: name of a handle to an IupCanvas that will be used to receive the events.

Callbacks

TOUCH_CB: Action generated when a touch event occurred. Multiple touch events will trigger several calls.

int function(Ihandle* ih, int id, int x, int y, char* state); [in C]
ih:touch_cb(id, x, y: number, state: string) -> (ret: number) [in Lua]

ih: identifies the element that activated the event. If TARGETCANVAS is not defined then it is the IupTuioClient control.
id: identifies the touch point.
x
, y: position in pixels, relative to the top-left corner of the canvas, or the screen if TARGETCANVAS is not defined.
state: the touch point state. Can be: DOWN, MOVE or UP. If the point is a "primary" point then "-PRIMARY" is appended to the string.

Returns: IUP_CLOSE will be processed.

MULTITOUCH_CB: Action generated when multiple touch events occurred.

int function(Ihandle *ih, int count, int* pid, int* px, int* py, int* pstate) [in C]
ih:multitouch_cb(count: number, pid, px, py, pstate: table) -> (ret: number) [in Lua]

ih: identifier of the element that activated the event. If TARGETCANVAS is not defined then it is the IupTuioClient control.
count: Number of touch points in the array.
pid: Array of touch point ids.
px: Array of touch point x coordinates in pixels, relative to the top-left corner of the canvas, or the screen if TARGETCANVAS is not defined.
py: Array of touch point y coordinates in pixels, relative to the top-left corner of the canvas, or the screen if TARGETCANVAS is not defined.
pstate: Array of touch point states. Can be 'D' (DOWN), 'U' (UP) or 'M' (MOVE).

Returns: IUP_CLOSE will be processed.

Notes

The cursor ID used in the callbacks is the session ID. In TUIO when a cursor is destroyed another cursor can be created with the same ID, the difference between them is the session ID that is always incremented every time a cursor is added or removed. We consider the primary cursor the existing cursor with the smaller session ID.

The native support for multi-touch in Windows 7 uses the same callbacks described here without the need of a IupTuioClient control. So the application will work without change. But the attribute TOUCH=YES must be set on the IupCanvas, and coordinates will be always relative to the top-left corner of the canvas.

The IupTuioClient does not emulates a mouse for single touch events. But as you can see from the example a mouse emulator can be easily implemented.

To learn more about TUIO:

http://www.tuio.org

Examples

Browse for Example Files (see canvas1.c)