Two Viewer CAVElib
(aka Project Zaphod)
This document describes changes being made to the CAVE library interface to
support multiple tracked users in a single ImmersaDesk or CAVE application.
The test library and headers can be found in /usr/local/CAVE/zaphod/.
The current test library supports multiple viewers and multiple wands, as
described below. The simulator tracker does not officially
include a multi-user mode, but it can be faked using the SimulatorNumWands option.
New functions
Although the existing CAVE library can support up to 32 tracked sensors and
multiple input devices, it treats all the sensors (except the first) as
interchangeable, and the input devices as a single collection of buttons and
valuators. The new additions to the library API distinguish between tracked viewers
(heads) and wands, and also associates button/valuator data with individual
wands. The new functions are:
- int CAVENumViewers(void)
- Returns the total number of viewers that are being tracked; this can range
from 1 to CAVE_MAX_VIEWERS (4). The viewers are numbered sequentially, from
0 to CAVENumViewers()-1 (the viewer numbers are used in arguments to
other functions below).
- int CAVENumWands(void)
- Returns the total number of tracked wands; this can range from 0 to CAVE_MAX_SENSORS
(32). The wands are numbered sequentially, from 0 to CAVENumWands()-1.
- CAVE_SENSOR_ST * CAVEHeadSensor(int viewerNum)
- Returns a pointer to the sensor struct for the given viewer. This pointer can
be passed to CAVEGetSensorPosition(), CAVEGetSensorOrientation(),
CAVEGetSensorVector(), and CAVESensorTransform().
If viewer #viewerNum does not exist, NULL is returned.
- CAVE_SENSOR_ST * CAVEWandSensor(int wandNum)
- Returns a pointer to the sensor struct for the given wand. This pointer can
be passed to CAVEGetSensorPosition(), CAVEGetSensorOrientation(),
CAVEGetSensorVector(), and CAVESensorTransform().
If wand #wandNum does not exist, NULL is returned.
- CAVE_CONTROLLER_ST * CAVEWandControls(int wandNum)
- Returns a pointer to the controller struct containing the button/valuator data
which is associated with the given wand. The controller data can be read from the
button[] and valuator[] entries of the struct.
If wand #wandNum does not exist, NULL is returned.
- void CAVEGetViewerEyePosition(int viewerNum,CAVEID eye,float *x,float *y,float *z)
- Returns the position of the given viewer's left or right eye.
- pfList * pfCAVEViewerChannels(int viewerNum)
- Returns a pfList which contains pointers to all of the Performer channels which
are rendering views for viewer #viewerNum.
- int CAVEViewer
- Global variable containing the number of the user whose view is currently
being rendered. This is only meaningful within the display process.
"Obsolete" functions
Most of the standard CAVE library functions assume a single viewer and a single
wand. To properly support multi-viewer mode, an application will have to use the
functions listed above in place of the traditional functions. For example,
CAVEGetPosition(CAVE_HEAD_NAV, pos);
would be changed to
CAVEGetSensorPosition(CAVEHeadSensor(viewer), CAVE_NAV_FRAME, pos);
where viewer takes on appropriate values in the range 0 to CAVENumViewers()-1.
Similarly, a reference to CAVEBUTTON1 would be changed to
CAVEWandControls(wand)->button[0].
The older library functions will still work, however, they will only report data
for the first viewer and wand. The functions which fall into this category are:
- CAVEGetPosition()
- CAVEGetOrientation()
- CAVEGetVector()
- CAVEGetEyePosition()
- CAVEHeadTransform()
- CAVEWandTransform()
- CAVEButtonChange()
- the CAVEBUTTONn and CAVE_JOYSTICK_X/Y macros
Navigation
Currently, navigation is shared by all viewers. An option may be added in the future
to support separate navigation matrices for each viewer.
Simulator
To run a 2-viewer CAVE simulator, place the following in your .caverc:
Simulator y
SimulatorNumViewers 2
ChannelGeom simulator,*,0 - 512x512+0+0
ChannelGeom simulator,*,1 - 512x512+520+0
This will display the two views side by side, with the first user's display on
the left. The simulator tracking and wand controls are the same as in the regular
CAVE library, except that you can select one user or the other to control.
The F1 key selects the first user, the F2 key selects the second user.
Last modified 6 July 1997.
Dave Pape, pape@evl.uic.edu