VRPN 06.04

VRPN from the application's point of view

An application uses one or more VRPN devices by creating one or more VRPN application objects. Examples and descriptions of currently-implemented client-side application objects include vrpn_Tracker_Remote, vrpn_Poser_Remote, vrpn_Button_Remote, vrpn_Analog_Remote, vrpn_Analog_Output_Remote, vrpn_Dial_Remote, vrpn_ForceDevice_Remote, and vrpn_Sound_Remote. Each type of object has its own include file (vrpn_Tracker.h and so on), but all are found in the VRPN library (libvrpn.a on unix systems). You can follow the links to each object type above for a detailed description of using that object type. General information is provided below.

The name of application (client) objects all begin with vrpn_ and all end with _Remote. The base class for the object (from which both client and server objects are derived) lacks the _Remote. Server objects have names specific to the device or class of devices that they serve (for example, _Fastrak for a certain kind of tracker).

Objects of each type are normally created by calling their constructor and passing the name of the device you wish to open. The name includes the local name and the name of the machine on which the device is found. For example, to open the device called Tracker0 on the machine ioceiling.cs.unc.edu, you would do the following:

#include <vrpn_Tracker.h>

vrpn_Tracker_Remote	myTracker("Tracker0@ioglab.cs.unc.edu");

For object types vrpn_Tracker_Remote, vrpn_Analog_Remote, vrpn_Dial_Remote, and vrpn_Button_Remote the application defines a callback function to the object. This function is called whenever a new data value is received from the device. For trackers, this callback records new tracker reports. For buttons, it reports when a button is pressed or released. Each update includes (by default) the local time at which the value changed (see clock synchronization in VRPN for more details).

For object types vrpn_Analog_Output_Remote, vrpn_Poser_Remote, vrpn_ForceDevice_Remote, and vrpn_Sound_Remote, the application calls member functions to provide commands to the remote device. VRPN handles packaging the requests and sending them to the remote device.

Example programs:

Examples of using each type of remote device listed above can be found on the pages describing the device itself.

John Stone from the Beckman Institute provided several examples of using a Phantom (vrpn_Tracker, vrpn_Button, vrpn_ForceDevice), including hooking these to openGL programs under Irix. These can be found in the client_src/haptic directory of the source code tree.

mainloop() -- important to call this!

For all object types, the code should call the object's mainloop() member function once each time through the program's main loop. It is at this time that the incoming network buffers are checked and application callbacks are called, once for each incoming message. Also, for outgoing network connections, this is when the data are actually put on the wire.

In the future, shared-memory or multi-threaded VRPN connections may be created. For these, the callbacks may be called in the remote system as soon as the member function is called on the local system. For this reason, the semantics of the callback handlers is that they will be called sometime from when the member function creating the message is called until the next time mainloop() finishes on the object.

Text messages

See the vrpn text message page for a description of how to change or turn off the printing of VRPN text messages.