2 March 1995 updated April 1996 Wes Bethel Lawrence Berkeley National Laboratory Berkeley CA USA 94720 VRModules and Support for the Spaceball in AVS5 - version 2 * - new since March 95 release * - Support for Fastrak magnetic trackers via the Division, Inc. Integrated Peripheral Unit (SGI-IRIX 5.3 only) For more information, check http://blondie.lbl.gov/projects/VRModules/ README file This distribution contains source code for modules and device drivers which implement "virtual reality" in AVS version 5.0.2. There are no plans at this point to port to AVS/Express, as we don't have that product at our site. Two (*three) archive files comprise the distribution for the VRModules module library and support for the Spaceball (*and Fastrak trackers). They are available via anonymous ftp from the International AVS Center at avs.ncsc.org in the directory avs.ncsc.org:~ftp/avs_tarfiles/vr_modules (thanks to Chuck Mosher and the avsfolks for making this happen so quickly). * - The file fastrak.tar.Z contains low level code for decoding packets sent from the Polhemus fastrak peripherals unit. While our implementation is based upon Division IPU device, the fastrak data packets are the same. The Division IPU comes with a 3d Mouse. The mouse has a bunch of buttons on it, along with a tracker- receiver hidden inside. In the Polhemus model, all of the trackers information is multiplexed into a single stream of data which comes into a serial port. The button events (this is what Division Inc added to the trackers, along with a nice ergonomic package) are multiplexed into a second data stream, which comes in to a second serial port. Our fastrak code has been in use and tested ONLY with an Onyx running IRIX5.3. The VRModules.tar.Z file contains all the source code for the AVS Modules. The Spaceball.tar.Z file contains all of the necessary files to build the Spaceball libraries needed by the AVS Modules. At present, the modules have been used extensively on the following platforms: Sparc, Solaris 2.X MIPS, Irix 4.X Alpha, OSF1 V1.X, V2.0, V3.0 (Note: major difficulties under OSFV2.0) * The fastrak.tar code has been tested only on an Onyx running IRIX 5.3. The tarfiles are not organized into the usual format for AVS Modules at the IAC. The primary reason for complicating the distribution is because there are a number of related modules, and they all make use of non-AVS archive libraries. Thus, you really need to grab the tarfiles, two of which are for the input devices and one contains AVS modules. The input device code is dependent upon header files in the source code for the AVS modules. Sorry about the complications, but it's really for your own good. ;-) Furthermore, the pathnames in the Makefiles are unnecessarily complex, and reflect the organization of software at our site. I apologize for this, but trust that it will be straightforward for a persistent and patient user to change. Now, after all of that, why should you bother with obtaining this source code? For starters, surf to http://blondie.lbl.gov and check out the web-based version of our paper that will be in the AVS 95 proceedings. It describes in extensive detail how a VR input device can be used on the desktop to interface to a wide variety of computing tasks in a way that makes use of the power of modular visualization environments. We have had extensive user testing of this software and the usage-methodologies. The response has been overwhelmingly positive. Furthermore, it is expected that this software will lay the groundwork for integration of additional VR input devices into AVS. Integration of output devices is another matter entirely, and you probably won't see that for some time to come. The organization of the software in the tarfiles is roughly thus: Spaceball: lib.dao.osf3/Makefile lib.mips.irix4/Makefile lib.sun4.sos5/Makefile src/[lots of .c and .h files] architecture specific Makeinclude files In the above lib* directories will be created the spaceball libraries needed by the AVS modules below. In addition to the archive files, a standalone executable is created which you can run from the command line that will indicate if your spaceball is working (this puppy is handy to have!). VRModules: bin.dao.osf3/Makefile bin.mips.irix4/Makefile bin.sun4.sos5/Makefile src/[lots of .c and .h files] Makeinclude script that builds AVS Module Libraries, installs it on your system, builds .topics files, etc. helpfiles/[lots of .txt files] paper/ postscript copy of paper for AVS 95 describing some of the theory, and how to use these tools. * NOTE: the vr_util.h file has undergone evolution since the last release of the code. In addition, some new modules which implement "gating" of events based upon button pushes and so forth have been included. * - Fastrak lib.mips.irix5/Makefile src/[a couple of .c and .h files] This code compiles into a libfastrak.a which is used only by the VRModule named "division ipu". There is also a standalone program, ftest, which will spew out packet info from the device. This is useful to verify that the device is properly functioning. This is a complete developer's environment for VR input devices. Please don't expect that you can yank a single module out of this release and compile it without compiling the libraries first. I apologize for the complexity of the software tree. However, I am required to maintain this software on three architectures simultaneously, and this works ok for me. Acknowledgements and a tip of the hat to Jim Wick of SpaceTec, Inc. who kindly granted permission to release portions of the Spaceball code so that people can use the code on their machines. * - The fastrak source code is a derivative work of some example code I received from Division Inc. Mike Harrison of Division, Inc. (Redwood City, CA) has granted permission for this file to be redistributed, and I have slapped a LBL copyright notice on it to maintain a copyright status. Finally, please send comments, bug fixes, etc to me at ewbethel@lbl.gov. ------------------------------------------------------------------------ Installation Instructions: 1. Download all tarfiles. You'll need the VRModules.v2.tar.Z file. If you want support for the spaceball, grab spaceball.v2.tar.Z. If you want support for the Division IPU, grab the fastrak.tar.Z file. 2. I suggest creating a directory structure that looks kind of like mine. $(DISK)/VRModules -> home for VRModules.v2.tar.Z $(DISK)/vr_devices/spaceball -> home for spaceball.v2.tar.Z $(DISK)/vr_devices/fastrak -> home for fastrak.tar.Z then uncompress & untar everything. 3. Do builds for each of the devices. You'll need to update some directory path pointers in the Makefiles to reflect filesystem organization at your site. 4. Do builds for the VRModules. Likewise, update directory path pointers in the Makefiles. NOTE: 1. make - just builds the module executables 2. make INSTALL - copies the module executables to some some distribution point in your system..somewhere that users can get to them. 3. make LIBRARY - builds the "compiled" AVS module libaray. 4. make HELPFILES - copies all the helpfiles into a place where users can get to them as well as so that avs itself can read them at runtime. 5. You may want to modify your avsrc file so that HelpPath includes the helpfiles that come with these modules. You will want to modify your avsrc file to include the module library created by the Makefile in VRModules.