Beckman Institute            University of Illinois at Urbana-Champaign              University of Illinois at Urbana-Champaign

Syzygy Documentation: Input Framework

Integrated Systems Lab
01/02/2007

Documentation Table of Contents

This chapter starts with practical examples of setting up Syzygy's input event processing software, and follows with an overview of the internals of Syzygy's input framework.

See also Supported Input Devices.

Syzygy Input Framework: Practical Examples

The Syzygy input framework has two programs that produce input events, DveiceServer and inputsimulator. The first serves as a front end for dynamically loaded device driver libraries, and the second is a GUI intended to allow the generation of VR input events. Both programs make their input events available over the network. Syzygy VR framework programs can connect to get these events, as can any other client. For instance, DeviceClient can attach and print out, 10 times a second, the data it has received. We now explain how to set up a DeviceServer and test its behavior using DeviceClient. 

  DeviceServer -s [-netinput] driver_name input_slot [pforth_program_name]

The "-s" flag causes the program to run in "simple" mode. Instead of trying to load an entire input node configuration, it just loads the device driver given by driver_name. If pforth_program_name is specified, this program will try to load the text stored in the global parameter of that name as a PForth program and apply it to the input events from the driver. The input slot (integer) on which this program transmits events is specified by input_slot, and, if the -netinput flag is specified, it tries to connect to input_slot+1 to receive events from the network. 

  DeviceServer [-netinput] node_config_name input_slot [pforth_program_name]

The same operation as above, except that the program configures itself according to the input node configuration in the global parameter node_config_name.

We now describe how to send joystick events from one computer to another. First, plug a joystick into a computer in your cluster, dlogin on that computer, and type: 

    DeviceServer -s arJoystickDriver 0

If you (in your Syzygy user identity) are not already transmitting on input slot 0 elsewhere in the cluster and your joystick is supported, DeviceServer will start running and not return. Subsequently, open a new shell on that computer and type: 

    DeviceClient 0

The raw event data from the joystick should now be printed at 10 second intervals. Try pressing some buttons and wriggling some axes. You should see the numbers change. If not, see the troubleshooting section. You can also run "DeviceClient 0" on other computers in the cluster where you are dlogin'ed as the same Syzygy user. The additional copies will print out input information from the DeviceServer. Once this is working, you can experiment with using PForth programs to filter the data. The following global parameter can be entered in a dbatch file (see Syzgy Input Device Configuration). 

  <param>
    <name> joystick_test </name>
    <value>
      define filter_axis_0
        getCurrentEventAxis 0.000031 * setCurrentEventAxis
      enddef
      define filter_axis_1
        getCurrentEventAxis -0.000031 * setCurrentEventAxis
      enddef
    </value>
  </param>

Kill the DeviceServer you ran before. DeviceClient can keep running. After typing the following, note how the values printed by DeviceClient change. 

    DeviceServer -s arJoystickDriver 0 joystick_test

Finally, we explain the input node configuration format. Two samples follow, as they might appear in a "complex" dbatch file. 

   <param>
    <name> cube_tracker </name>
    <value>
      <szg_device>
        <input_sources> arMotionstarDriver </input_sources>
        <input_sinks></input_sinks>
        <input_filters> arTrackCalFilter </input_filters>
        <pforth>
  	  matrix inputMatrix
  	  matrix outputMatrix
  	  matrix correctXRotMatrix
  	  matrix correctYRotMatrix
  	  matrix correctZRotMatrix
  	  matrix correctHeadRotMatrix
  	  -30 0 correctXRotMatrix rotationMatrix
  	  6 1 correctYRotMatrix rotationMatrix
  	  -1 2 correctZRotMatrix rotationMatrix
  	  correctYRotMatrix correctZRotMatrix correctHeadRotMatrix matrixMultiply
  	  define filter_matrix_0
  	    inputMatrix getCurrentEventMatrix
  	    inputMatrix correctHeadRotMatrix outputMatrix matrixMultiply
  	    outputMatrix setCurrentEventMatrix
  	  enddef
        </pforth>
      </szg_device>
    </value>
    </param>


    <param>
    <name> idesk_tracker </name>
    <value>
      <szg_device>
        <input_sources> arSpacepadDriver arJoystickDriver </input_sources>
        <input_sinks></input_sinks>
        <input_filters></input_filters>
        <pforth></pforth>
      </szg_device>
    </value>
    </param>

The configuration records for DeviceServer refer to the names of loadable modules. These must exist on the SZG_EXEC/path for Syzygy to find them. Assuming you have set this parameter correctly and have entered the global parameters listed above into the database, you could type the following command on a computer with both a spacepad and joystick connected: 

    DeviceServer idesk_tracker 0

When this DeviceServer starts up, it reads the configuration information given by the global parameter "idesk_tracker". In the "input_sources" field, it finds a list of module names (leaving off the trailing .so or .dll for portability) which it will try to dynamically load as input sources. Recall again that these modules must live on the SZG_EXEC/path to be loaded by DeviceServer. Likewise, the "input_sinks" field gives a list of input sinks (subclasses of arInputSink) to be dynamically loaded, and the "input_filters" field gives a list of input filters (subclasses of arIOFilter) to be dynamically loaded. Finally, if the "pforth" field is nonempty, it contains a PForth program to be applied to the data gathered from the defined input sources before it goes into the chain of input filters and finally into the input sinks.

Syzygy Input Framework: Overview

Input data in Syzygy comes in the form of arInputEvents. There are currently three types of events. Matrix events, which usually represent the position and orientation (referred to in combination as the placement) of a tracking sensor. Axis events contain a floating-point number representing the state of a continuously-varying input. Button events contain an integer, usually representing a binary on-off input device. Within each class, events are identified by a 0-based index; in applications, a particular event type and index is generally associated with a particular function, for example matrix event #0 is generally assumed to represent the position and orientation of the sensor attached to the user's head. All three event types have a default value that will be returned whenever an application requests an event outside the range of existing indices; for matrices this is the identity matrix, for the other two types it is 0.

For purposes of transmission and storage, arInputEvents are packed into arStructuredData records. Syzygy provides functions for converting data between these two formats. arStructuredData records themselves come in two formats, the native binary format for network transmission and an ascii XML format for storage on and retrieval from disk. Syzygy also provides routines for I/O to and from XML-format files.

The transmission of input events is organized into trees; these trees are created and managed by a number of input object classes. Input events coming in from separate devices on separate branches can integrated into a single event stream, corresponding to a compound virtual input device. In addition, events can be transformed, added, or deleted by filters at each node of the tree. These filters can be either written in C++ or, for simple but flexible filters, in the provided PForth language.

Input events currently originate either in a device driver or the 6DOF head & wand tracking + joystick simulator program, <span style="font-style: italic;">inputsimulator. All device drivers are managed by the DeviceServer executable, with a separate instance of this program running on each machine connected to a hardware input device. Each instance of DeviceServer has a service name, corresponding to a group of Syzygy database parameters, that is determined by the device driver it is running. An application checks this group of database parameters for the IP address and port number to connect to in order to receive input from that device. Here is a list of supported input devices.

Recognizing that many virtual worlds require similar navigational functionality, the input framework includes support for standard navigational methods that can be easily deployed in user programs. These methods are integrated with the two Syzygy application frameworks.

Finally, Syzygy also provides classes and functions to simplify the handling of interactions between the user and virtual world objects. Grabbing and dragging can be handled with minimal effort different kinds of drag behaviors can easily be added, and hooks are provided for implementing other kinds of user-initiated object state changes.

[Schedule] [Labs] [Beckman Meeting Rooms] [Equipment] [Projects] [CUBE Projects] [Syzygy] [VSS] [People] [Events] [Publications]