TouchHooks2Tuio

The TouchHooks2Tuio program monitors Windows 8 touch events and resends them as /tuio/2Dcur messages for use by a TUIO-aware multitouch application.

Run Requirements:

• Windows 8 operating system.
• Multitouch hardware that generates Windows 8 touch events.
• A TUIO-aware client application.

Build Requirements:

• Microsoft Visual Studio 2013 Community Edtion https://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx
• Qt Framework version 5.4 (or higher) http://www.qt.io/download/
• Visual Studio Add-in 1.2.4 (or higher) for Qt 5 http://www.qt.io/download-open-source/#section-2

Acknowledgements:

1. TouchHooks2Tuio is based directly on the Touch2Tuio program written by Marc Herrlich and Benjamin Walther-Franks at the University of Bremen. Touch2Tuio source: https://github.com/vialab/Touch2Tuio Touch2Tuio binary: http://dm.tzi.de/en/touch2tuio/
2. For sending TUIO UDP messages on port 3333, TouchHooks2Tuio uses the TUIO_CPP server reference implementation from reacTIVision. http://www.tuio.org/ http://www.tuio.org/?software
3. For sending FLASH XML messages on port 3000, TouchHooks2Tuio uses an ofxTCPServer class borrowed from openFrameworks (but rebuilt for Visual Studio 2013), which in turn uses the POCO library. http://openframeworks.cc/ http://pocoproject.org/index.html

Overview:

TouchHooks2Tuio is based on the Touch2Tuio program, but uses a different hook strategy. The original Touch2Tuio program attached a hook to the window for a single multitouch app by entering the title for that window on the command line when Touch2Tuio starts up. TouchHooks2Tuio, on the other hand, uses a global hook that listens for Windows 8 touch events from all open windows. Therefore, the hook does not need to be released and then reattached each time a differenct multitouch app is fired up.

TouchHooks2Tuio also adds a GUI with a menubar and a text area for reporting the status of the TUIO servers (see the TouchHooks2Tuio-GUI.png file). The 3 TUIO servers use localhost (127.0.0.1), and can be operated in parallel:

TUIO UDP channel one on port 3333 (used by most TUIO-aware apps)
TUIO UDP channel two on port 3334
Flash XML TCP on port 3000 (older standard for Flash apps)

The Network menu can be used to toggle any of these channels on/off, and, if desired, the port numbers can be changed in a configuration file (look for the TouchHoos2TuioSettings.xml file in the Data/Settings subdirectory). To toggle the global hook on/off, use the Hooks menu. When the global hook is attached, it also intercepts and blocks the emulated mouse clicks that are generated by default from Windows 8 touch events.

Basic Usage:

1. Plug in your Windows 8 touch device (monitor, bezel, or whatever).
2. Double-click on TouchHooks2Tuio.exe.
3. Check the text area of the GUI to see that the servers started ok.
   The most likely cause of failure would be if a port number was already in use by another program.
4. For most TUIO-based multitouch apps, TUIO UDP on channel 1 (port 3333) should be turned on (use the Network menu if needed).
5. Start up a TUIO-based multitouch app.

Possible Configuration Issues:

1. In the Visual Studio 2013 Properties box for the TouchHooks2Tuio project, the Linker -> General -> Additional Library Directories box will show $(QTDIR)\lib, where QTDIR is the name of an environment variable that has the path "C:\Qt\Qt-5.4.1\5.4\msvc2013_opengl" on my machine. You will likely need to either create a QTDIR environment variable or simply replace "$(QTDIR)" with the actual path for your installation of the Qt framework libraries.

2. Another properties box setting that should be checked is Configuration Properties -> Debugging -> Working Directory. The value for Working Directory should be $(OutDir), not $(ProjectDir). Setting the working directory to the output directory (the top level Release or Debug directory) will matter when TouchHooks2Tuio is started up through Visual Studio. The output directory contains an XML configuration file, Data/Settings/TouchHooks2Tuio.xml that is read in at program startup. If the XML configuration file cannot be found, TouchHooks2Tuio will open up a warning box and then use default settings.

3. If you distribute a release version of TouchHooks2Tuio, you should copy the following Qt Framework dynamic library into the same directory as the executable, as you have no guarantee that these DLLs will be on a non-developer machine:

   platforms/qwindows.dll
   icudt53.dll
   icuin53.dll
   icuuc53.dll
   Qt5Core.dll
   Qt5Gui.dll
   Qt5Multimedia.dll
   Qt5Network.dll
   Qt5Widgets.dll
   Qt5Xml.dll
   

   Note that "qwindows.dll" must be in a subdirectory named "platforms".

License:

GNU General Public License, Version 3.0 http://www.gnu.org/licenses/gpl-3.0.en.html

Disclaimer:

TouchHooks2Tuio is a work in progress, and has only been tested on a few machines, so I cannot guarantee that it will work with your hardware setup. In legal terms: This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.