instantreality 1.0

Introduction

This tutorial should help you to write, build and install an InstantIO C++-Plugin for your own device, device-system, filter or whatever you would like to be a Node in the InstantIO network. You can also write plugins in pure Java but this is not the topic of this how-to. Further information and the reference documentation is available in the InstantIO-section of the instantReality page.

Requirements

Warning: For Windows you need to use the Visual Studio 2005 compiler!

You need a C++ compiler and the InstantIO-SDK, i.e. for Linux and Mac use the current commandline g++ or XCode compiler, and on Windows you need the Visual Studio 2005 release. The InstantIO-SDK is included in every InstantPlayer package which you can download from the instantReality download page. You probably have it already installed if you read this document.

Write a Plugin

You only need to write a single class to get a new IO-Node. Use the included FooNode.h and FooNode.cpp files as a template.

Nodes in the IO-subsystem are described by a type, have fields for attributes and In/Out-Slots for communication. You can use Routes to connect In-/Out-Slot of the same type (e.g. SFVec3f) to transfer data between Nodes.

The concept is very similar to X3D nodes however there are some main differences in the IO-subsystem.

First of all the Routes can connect local nodes or different applications running on the same or a network-connected machine. X3D-Routes only connect nodes inside of a single application. Second, routes can connect not just a single In-/Out-Slot, like in X3D, but any number with the help of a flexible wildcard-system. Last but not least, IO-Nodes have different states than X3D-nodes and they are only active if at least one slot is connected.

To implement you own InstantIO-Node you only really have to know the states and fill some handler methods. For further explanation look at the manual in the InstantIO-section.

IO-Node states

• SLEEPING The Node is constructed and all fields and field-values are available and set.
• RUNNING The Node is connected to another Node and the data-read/write thread-code is running.
• ERROR Some ERROR occurred. Look e.g. at the web-interface to get more detail.
• DISABLED The Node is disabled from outside.

To handle this state changes and to read/write data from/to your node you have to implement the following functions in your Node.

IO-State handler

• initialize Use the field-values to initialize your Node and build dynamic In/Out-Slots from your current device/system configuration.
• processData Somebody connected a Route and the worker-thread for the Node has been started. Every Node has a single thread as worker-thread to read and write the data. The processData() method is called by the worker-thread and has to open the device/system and read/write data to/from the Slots
• shutdown This method is called when the node is dismissed your Node. Delete all dynamic In/Out-Slots and do other cleanups.

This should help you to get a first idea. Look at the code and the ADDCODE-comments and really look at the online documentation.

Build, test and install

Now you have to compile, test and install your plugin. The PluginName must be the node-name plus an ".iio" (for InstantIO) suffix.

Use the included test.x3d or test.x3dv to run your plugin. The test plugin produces some random vec3f and rotation data. The test.x3d/x3dv example prints the received values on the screen. If the plugin is not loaded you get a simple Pos: undef, Rot: undef text

If you successfully compiled and installed the plugin you will get the random values printed to your screen.

Windows

For using Microsofts Visual Studio 2005 as your Developing Suite you can simply open the providet Solution as an example.

The primary configuration is to use the \Instant Player\Include as Include Directorie and \Instant Player\lib as Library search Path. The Linkage to the InstantIO Library is done via a #pragma comment (lib, "InstantIO.lib") directive inside the InstantIO/InstantIODef.h header so there is no need of seting any library depencies.

In difference to other dynamic Librarys, the file-ending of the created Library is ".iio" insted of ".dll". After compiling, just copy the created FooNode.iio file to your \Instant Player\bin directory and start the Instant Player with the test.x3d File.

OSX

For development on Mac OS X there is a project file available: double click it and fire up XCode. Select either Debug or Release mode and click on the Build button to compile the code. The resulting library file can be found in the subdirectory build/Release or build/Debug respectively.

If your InstantPlayer application is, however, not in the default path in /Applications, you'll have to change some settings and tell XCode were to find the InstantIO header files. Open up your XCode and click on the project Info button on the upper right. You will find yourself in the project configuration. Select the Build tab, go to the Search Paths section and add the new path to your headers under Headers Search Paths. Remember to do this for all configurations, i.e. Debug and Release!

After the build, open up your Finder, go to Applications, Ctrl+click on the InstantPlayer app and select Show Package Contents. Now copy over the library file Foo.iio to Contents/MacOS and run the accompanying test.x3d to see if your newly created InstantIO plugin does indeed work.

Voila, you're all set up and good to go.

Linux

For Linux systems use the simple Makefile. If the instantReality system is not in installed in /opt/instantReality set the IR_ROOT variable in the Makefile.

Afterwards just run 'make' to create the plugin.

To test the plugin just add the current directory to you LD_LIBRARY_PATH (e.g. export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.) and run the test.x3dv.

To install the plugin for all users just type 'make install' with root/sudo rights.

Files:

• instantIOPlugin.zip