Libsball 1.0 -- Copyright 1999-2001, John E. Stone (johns@megapixel.com) ---------------------------------------------------------------------------- Version 1.0 Release Notes ------------------------- Libsball is a very simple implementation of a protocol driver that reads output from the Spaceball 6DOF 3-D controller manufactured by 3Dconnexion, Labtec, SpaceTec IMC, and other previous corporate owners. (see device description below if you are unfamiliar with the concept) Libsball provides a simple interface to the Spaceball on a Unix system through the use of POSIX compliant termios RS-232 serial communication routines. The main advantage of Libsball over the vendor-provided drivers is that it is free, open source, and can be built into an application even on platforms not supported by the vendor-provided drivers. Also, Libsball by its nature, does not require the use of windowing system services, so it can be used with software like VRPN that acts as a "network server". Libsball has been successfully used on OpenBSD, Solaris, IRIX, HP-UX, Tru64 Unix, AIX, and several flavors of Linux. Libsball has also been integrated into several popular visualization and rendering packages, and its core code has also been ported to various VR and tracker libraries such as the NCSA CAVE, FreeVR, and VRPN. Notes on compiling Libsball and running the test program on Unix systems ------------------------------------------------------------------------ The Makefile supplied with libsball assumes a generic ANSI C compiler on a POSIX compliant Unix system. If your C compiler is named something other than "cc" or you would like to alter compilation flags etc, go ahead and edit the Makefile appropriately. Please send the author any patches required for building and running libsball on new systems. To build a static link library "libsball.a" and a "testsball" program that displays the state of the Spaceball in a command window, just type "make". Once libsball.a and the test program have been built, run the test program with the system serial port device name which the Spaceball is attached to as an argument. Example: "testsball /dev/ttya" If libsball fails to properly open and initialize the serial port, it will print an error and exit. If the test program succeeds in opening the serial port, it will begin printing the status of the attached Spaceball as shown below: thor - johns:/disk5/users/johns/graphics/libsball % testsball /dev/ttya Spaceball Unix test program, by John Stone Opening Spaceball: using port /dev/ttya for I/O Sucessfully opened Spaceball port. Monitoring Spaceball, press button 1 on Spaceball, or ctrl-c to exit. tx: 5 ty:-123 tz: -98 rx:-117 ry: 36 rz: -29 buttons:00 (after pressing the "a" button on the Spaceball, the test program will exit) Spaceball test complete. Closing down Spaceball port. Building the "sballfly" demo program ------------------------------------ Once you've built and tested the library using the "testsball" program, you can try out "sballfly" another simple program included in the sballfly subdirectory. You'll need to edit the Makefile for your OpenGL configuration, but it should be pretty self explanatory. What is a Spaceball and how does it work? -------------------------------------------- The Spaceball is an input device with a six degree of freedom ball controller, and 9 buttons. The Spaceball communicates with the host computer via standard RS-232, at 9600 baud, no parity, 8 data bits and 1 stop bit. The Spaceball generates bursts of "events" when the ball is pushed or twisted, or when buttons are pressed. How do I use the Spaceball and libsball in a 3-D application? -------------------------------------------------------------- The best way to use a Spaceball with 3-D applications is to use the translational and rotational deltas from the Spaceball to alter transformation matrices used in an application. In a 3-D cad or object editing system, the Spaceball might be used to position objects in space. In a 3-D fly-through, games, or virtual reality type applications, the Spaceball could be used to fly the camera or player around in space. In either case, libsball simply provides the translation and rotation values read directly from the Spaceball itself. In order to uses these values, they must be processed and used to create 3-D transformations. Common processing operations on the raw Spaceball output might include scaling, value clamping, and software sensitivity controls. New Spaceball users often find that it is very sensitive and they have a difficult time getting used to it when its run at full sensitivity. A better way of using the Spaceball output is to scale it to some useful units, and to write software that provides a "NULL" region, or areas where displacements below a certain threshold are ignored. This allows new Spaceball users to gradually become accustomed to the sensitivity of the device. As the Spaceball user's skill improves, the size of the "NULL" region can be decreased allowing the Spaceball to be used at full precision and sensitivity. In order to construct a transformation matrix from the output of the space Spaceball, it is a good idea to use quaternions for representing rotations. Ball rotational displacement events can be easily converted into quaternions, and the quaternions can be used to generate transformation matrices. At this time, libsball does not include code for the creation and maintenance of quaternions or transformation matrices, although such code has been written. The feedback and suggestions of libsball users will be used to determine an appropriate set of features for adding such support to libsball. Writing a code to use Libsball ------------------------------ In order to use libsball, the minimal steps necessary to get it initialized and talking to the attached Spaceball are: 1) call sball_open() with the tty/serial port device name that the Spaceball is connected to. i.e. sball_open("/dev/ttya"); sball_init() returns a void * handle which is used in all following sball_xxx() calls. If sball_open() fails to open the tty/serial port it will return NULL. 2) call sball_getstatus() to retrieve current displacement and button status. sball_getstatus() returns an integer flag which is 0 when there was no change in status to report, and returns a 1 if status information was reported. The parameters to sball_getstatus() are the Spaceball handle, and pointers to integers for tx, ty, tz, rx, ry, rz, and buttons. Buttons are stored as bits in the lowest 12 bits of buttons. Buttons are 1 if pressed, and 0 if unpressed. Buttons are conveniently handled by ANDing with one of the button masks defined in sball.h. Spaceball translation and rotation values are stored in the six integer parameters as signed values which range from -32767 to +32767. sball_getstatus() is currently implemented as a polling function, and does not actively request a status report from the Spaceball, so it will only report events that are generated by the Spaceball itself. 3) sball_close() free's the handle and closes the serial port to the Spaceball device. Other sball_xxx() functions are listed in sball.h, but may not be ready for real use at this time. In this release sball_open() does not attempt to perform any auto-detection or verification of the existence of a Spaceball on the requested tty/serial port, it will assume that an Spaceball is there, and will wait for event packets. Future revisions of libsball should perform a verification check on startup to make sure that a Spaceball is actually present on the serial port, and is communicating properly. sball_open() will currently return an error only if the specified port cannot be opened. Trademarks ---------- Spaceball is a trademark of SpaceTec IMC. SparcStation, and Ultra are trademarks of Sun Microsystems Inc. SGI, and IRIX are trademarks of Silicon Graphics Inc.