CAVE macros, variables, and miscellaneous functions

CAVE macros simplify access to the wand information. The global variables provide various information about the state of the CAVE.

Sensor & Controller macros

CAVESENSOR
(i) 		Macro for a pointer to the i'th tracking sensor; i.e. CAVEptr->sensor[i]. Sensor 0 is the head, sensors 1 and up are the wand or any other tracked devices. This pointer can be passed to CAVEGetSensorPosition, CAVEGetSensorOrientation, CAVEGetSensorVector, or CAVESensorTransform.
CAVENETSENSOR
(user, i) 		Macro for a pointer to the networked user user's i'th tracking sensor; i.e. user->sensor[i]. Sensor 0 is the head, sensors 1 and up are the wand or any other tracked devices.
CAVEBUTTONn = [ 0 | 1 ] There are three buttons attached to the wand. They can be accessed through the above macros, where n = 1, 2, 3, or 4. The macros have the value 1 when the button is pressed, and 0 when not pressed.
CAVEBUTTON1 corresponds to the left wand button
CAVEBUTTON2 corresponds to the middle wand button
CAVEBUTTON3 corresponds to the right wand button
CAVEBUTTON4 corresponds to the fourth button on the Logitech flying mouse
CAVE_JOYSTICK_X
CAVE_JOYSTICK_Y
The PC-based wand has a pressure-sensitive joystick in addition to buttons. These two macros will give the X & Y coordinate values of the joystick, normalized to be in the range [-1.0,1.0]. (Note: when the joystick is not being pressed, these values will be close to, but not exactly, 0).


Global Variables

The following are global variables used by the CAVE library. CAVENear and CAVEFar can be changed by an application. The other variables are meant for information only; your program should not change them.

int CAVENear, CAVEFar The near and far clipping plane distances for the CAVE's perspective projection. These are not shared; each rendering process has independent copies.
int CAVEEye The eye view which is currently being drawn when your display function is called; the possible values are CAVE_LEFT_EYE and CAVE_RIGHT_EYE. This variable is not shared, since the rendering processes are not synchronized except when they call swapbuffers.
int CAVEWall The wall which is currently being drawn when your display function is called. Possible values are CAVE_FRONT_WALL, CAVE_LEFT_WALL, CAVE_RIGHT_WALL, CAVE_FLOOR_WALL, CAVE_BACK_WALL, CAVE_CEILING_WALL, CAVE_SCREEN[0-7]_WALL, CAVE_SIMULATOR_WALL, CAVE_SIMULATOR1_WALL, and CAVE_SIMULATOR2_WALL. This variable is only considered to be valid within the CAVEDisplay callback; in non-rendering processes, and in the CAVEFrameFunction or CAVEInitApplication callbacks its value is undefined.
float *CAVEFramesPerSecond The current frame rate. This is pointer to a float because it is stored in shared memory, and so is the same for all processes.
float *CAVETime The current "CAVE time". This records the number of seconds since CAVEInit. The variable is updated in the display loop, once per frame, and is stored in shared memory.
char *CAVEVersion A string identifying the version of the CAVE library. It contains the version number and release date.
CAVE_CONTROLLER_ST *CAVEController A structure containing the status of the wand controls. The 'button' entry is an array of ints that give the state of the buttons (0 or 1); the 'valuator' entry is an array of floats that give the state of any valuators. The PC-based wand has two valuators - the joystick X and Y. The CAVEBUTTON and CAVE_JOYSTICK macros access this structure.
int *CAVENumUsers The number of networked users. This is the number of active nodes which the network has received data from, plus the local node.
CAVE_USER_ST **CAVEUser An array of networked user data. The first *CAVENumUsers entries of CAVEUser are pointers to structures containing the tracking data from the different nodes in the CAVE networking group. CAVEUser[0] contains the local node's data. The other entries are not guaranteed to always maintain the same position in the array; they may be moved as nodes join and leave the networking group. However, the pointer to a given CAVE's data will not change (unless the CAVE exits and then later rejoins the group).


6.4.3 Miscellaneous Functions

void CAVEAddCallback
(CAVEID cbtype, CAVECALLBACK function, void *app_data) 		Defines an application function which will be called by the library when appropriate. cbtype is the type of callback; its value should be one of: CAVE_DISPLAY_CALLBACK, CAVE_INITGRAPHICS_CALLBACK, CAVE_PERFRAME_CALLBACK, CAVE_NETADDUSER_CALLBACK, CAVE_NETDELETEUSER_CALLBACK, or CAVE_NETAPPDATA_CALLBACK. function is the application function to call; app_data is an argument to pass to the callback function. Defining a CAVE_DISPLAY_CALLBACK function is equivalent to calling CAVEDisplay; CAVE_INITGRAPHICS_CALLBACK is equivalent to CAVEInitApplication; CAVE_PERFRAME_CALLBACK is equivalent to CAVEFrameFunction.
The CAVE_NETADDUSER_CALLBACK will be called by the networking process whenever a new user is added to the CAVEUser array.
The CAVE_NETDELETEUSER_CALLBACK will be called by the networking process whenever a user is deleted from CAVEUser (a user is deleted when no new data has been received from the user for a significant amount of time).
The prototype for a networking add or delete callback is: void function
(CAVE_USER_ST *user, void *app_data). user is a pointer to the user structure which is being added or removed; app_data is the application data pointer which was passed to CAVEAddCallback.
The CAVE_NETAPPDATA_CALLBACK will be called by the networking process whenever any application data (i.e. data sent via CAVENetSend) is received from another node. If this callback is used, the data will not be read by CAVENetReceive. The prototype for the net application data callback is: void function
(CAVE_USER_ST *user, void *buffer, size_t size, void *app_data). user is a pointer to the user structure corresponding to the node which sent the data; buffer is a buffer containing the data; size is the size of the data in bytes; app_data is the application data pointer which was passed to CAVEAddCallback.
Note: The networking callbacks are called in the networking process; B they should avoid using significant amounts of CPU time, or this process will be slowed and the network data may be backed up.
volatile void * CAVEAllocDisplayData
(size_t size)
Allocates shared memory to use for passing data to the display processes, and returns a pointer to one block for the computation process to use. size is the size of the block in bytes. Four blocks of memory are actually allocated - the one that is returned, one for the display processes to use, and two others that are used in staging the data when it is sent by CAVEPassDisplayData
(). The blocks are all allocated using CAVEMalloc
(), so its shared arena must be large enough to hold the four blocks, plus any other shared data the application will allocate (the size can be set by CAVESetOption
()).
When this function is used instead of CAVEAllocDisplayDataByID
(), the application must make sure that all the calls occur in one process, in the same order on all machines.
volatile void * CAVEAllocDisplayDataByID
(int id, size_t size)
Equivalent to CAVEAllocDisplayData
(), except that the application provides an ID number (id) for the block of data being allocated, in order to guarantee that corresponding blocks on separate nodes of a distributed CAVE are matched together correctly. id must be a positive integer.
int CAVEButtonChange
(int button) 		Returns a flag indicating the change in a button's state, compared to the last time the function was called. 0 indicates the button has not changed, 1 indicates that it has been pressed, and -1 indicates that is has been released. button should be 1, 2, 3, or 4. The button states are remembered by this function in each process independently.
float CAVEConvertFromCAVEUnits
(float val, CAVEID units) 		Takes the distance val in CAVE units (the units specified in the configuration file by CAVEUnits), and returns its equivalent in the given units. units should be one of CAVE_FEET, CAVE_INCHES, CAVE_METERS, or CAVE_CENTIMETERS.
float CAVEConvertToCAVEUnits
(float val, CAVEID units) 		Takes the distance val in the given units, and returns the equivalent value in CAVE units (the units specified in the configuration file by CAVEUnits). units should be one of CAVE_FEET, CAVE_INCHES, CAVE_METERS, or CAVE_CENTIMETERS.
void CAVEDisplayBarrier
(void) 		Provides a synchronization barrier for the display processes. When this function is called from an application's display routine, it will wait until all of the display processes reach the barrier before returning. This function should not be called from any other processes; furthermore, it must be called by all the display processes that the library started, or the callers will block indefinitely.
boolean CAVEDisplayDataChanged
(volatile void *buf)
Returns TRUE if a new copy of the display data buffer buf has been passed to the display processes since the previous frame. buf can be the pointer returned by CAVEAllocDisplayData
() or one subsequently returned by CAVEGetDisplayData
().
boolean CAVEDisplayDataChangedByID
(int id)
Equivalent to CAVEDisplayDataChanged
(), except that the the buffer is identified by it's ID number id, which is the ID passed to CAVEAllocDisplayDataByID
() (or returned by CAVEGetDisplayDataID
()).
boolean CAVEDisplayDataIDExists
(int id)
Returns TRUE if a display data buffer has been allocated for ID number id, FALSE if not.
void CAVEDisplaySync
(void) 		Blocks the calling process until the end of the current rendering frame; the call blocks on a semaphore which will be released by the master display process just after the display buffers are swapped. Any number of processes may use this function simultaneously. This should not be called from a display process, or it will deadlock.
void CAVEDistribBarrier
(int chanID) 		Provides a synchronization barrier for separate nodes in a distributed CAVE. The calling process will wait until the barrier is reached on all of the distributed nodes before returning. This function should only be called by one process on each node. chandID is the ID of a distribution communications channel which was opened with CAVEDistribOpenConnection
(). If distribution is not active, this function will return immediately.
void CAVEDistribCloseConnection
(int chanID) 		Closes a distributed CAVE communications channel. chanID is the channel ID which was passed to CAVEDistribOpenConnection
(). This function should be called by the process which calls CAVEDistribOpenConnection
() before exiting.
boolean CAVEDistribMaster
(void) 		Returns TRUE when called on the master node of a distributed CAVE; FALSE for all other nodes. Returns TRUE when called in a non-distributed (single node) CAVE.
int CAVEDistribNumNodes
(void)
Returns the total number of nodes in the distributed CAVE. Returns 1 if distribution is not active.
void CAVEDistribOpenConnection
(int chanID) 		Opens a communication channel between the master and slave nodes of the distributed CAVE. chanID is an integer identifying the channel; it must be in the range 0 to CAVE_DISTRIB_MAX_CHANNELID (defined in cave.h, currently 31). Returns TRUE if successful, FALSE if the channel could not be opened. Once the channel is opened, it can be used with CAVEDistribRead
(), CAVEDistribWrite(), CAVEDistribBarrier
(), and CAVEDistribCloseConnection(); these functions should only be called in the same process which opened the channel. Only one process on a CAVE node should open a given channel; each channel must be opened by all nodes in a distributed CAVE.
int CAVEDistribRead
(int chanID, void *buffer, size_t size) 		Reads the next block of data sent over a distributed CAVE channel by CAVEDistribWrite
(). chanID is the channel ID which was passed to CAVEDistribOpenConnection
(); buffer is a buffer of at least size bytes which the data will be copied into. The function's returned value is the number of bytes received. This function blocks until data is received, unless distribution is not being used, in which case it returns immediately (with a value of 0).
On the master node, a single call to CAVEDistribRead
() will receive data from only one of the slave nodes, in no particular order; it should be called once for each of the slaves (assuming they all call CAVEDistribWrite
()); the number of slave nodes is CAVEDistribNumNodes
()-1.
void CAVEDistribWrite
(int chanID, void *buffer, size_t size) 		Sends a block of data over a given distributed CAVE channel. chanID is the channel ID which was passed to CAVEDistribOpenConnection
(); buf is a pointer to the data to send; size is the number of bytes to send. When called by the master node, this sends a copy of the data to each of the slave nodes; when called by a slave node, this sends the data only to the master. If distribution is not active, this function will return immediately without doing anything.
void CAVEFree
(void *mem) 		Frees a chunk of shared memory which was allocated by CAVEMalloc
().
void CAVEFreeLock
(CAVELOCK lock) 		Frees up a CAVE lock, releasing the shared memory that it uses. The lock should be one returned by CAVENewLock
().
void CAVEGetActiveChannels
(CAVEID wall[CAVE_NUM_WALL_IDS]) 		Returns a set of flags indicating which views (channels) are being rendered by the application. The data returned is similar to that returned by CAVEGetPipeChannels
(), except that it covers all of the running display processes.
boolean CAVEgetbutton
(CAVE_DEVICE_ID device) 		A CAVE equivalent to the IrisGL function getbutton
(); returns the state of a button device. device should be one of the CAVE device names listed in cave.h; the names are the same as those used by IrisGL, except prefixed with CAVE_ (e.g. CAVE_AKEY). In IrisGL this function just calls getbutton
() for the corresponding GL device. In OpenGL this function consults a table in shared memory which is updated whenever the main display process receives X events; it can thus be called from any CAVE process (note that the mouse pointer must be in the master display's window for events to be received).
volatile void * CAVEGetDisplayData
(volatile void *buf, size_t *size)
Returns a pointer to the shared buffer with the latest display data which has been passed to the display processes (by CAVEPassDisplayData
()). buf can be the pointer returned by CAVEAllocDisplayData
() or one subsequently returned by CAVEGetDisplayData
(). If size is non-NULL, it will return the number of bytes which were sent by CAVEPassDisplayData
().
volatile void * CAVEGetDisplayDataByID
(int id, size_t *size)
Equivalent to CAVEGetDisplayData
(), except that the the buffer is identified by it's ID number id, which is the ID passed to CAVEAllocDisplayDataByID
() (or returned by CAVEGetDisplayDataID
()).
int CAVEGetDisplayDataID
(void *buf)
Returns the ID number associated with the display data buffer buf.
void CAVEGetEyePosition
(CAVEID eye, float *x, float *y, float *z) 		Returns the position of an eye. The first argument indicates which eye's position you are requesting; it should have the value CAVE_LEFT_EYE or CAVE_RIGHT_EYE. The remaining three arguments return the position, in CAVE coordinates.
int CAVEGetFrameNumber
(void) 		Returns the number of the frame currently being rendered. Frames are numbered starting from 0, from the moment the display loop is started by CAVEInit
().
void CAVEGetOrientation
(CAVEID oname, float *angle) 		Returns the orientation of a sensor or eye. The oname argument indicates which object's orientation you are requesting; it should be one of CAVE_HEAD, CAVE_WAND, CAVE_LEFT_EYE, CAVE_RIGHT_EYE, CAVE_HEAD_NAV, CAVE_WAND_NAV, CAVE_LEFT_EYE_NAV, or CAVE_RIGHT_EYE_NAV (note that the eyes will have the same orientation as the head). The _NAV id's request the values in navigated (world) coordinates; the other id's request tracker coordinates. The orientation is returned in angle, which should be an array of three floats; angle[0] is the elevation (X rotation), angle[1] is the azimuth (Y rotation), and angle[2] is the roll (Z rotation).
void CAVEGetPipeChannels
(CAVEID wall[CAVE_NUM_WALL_IDS]) 		Returns a set of flags indicating which views (channels) are being rendered by the calling display process (pipe). For each wall ID id, wall[id] will be either CAVE_NULL, CAVE_LEFT_EYE, CAVE_RIGHT_EYE, or CAVE_BOTH_EYES. CAVE_NULL indicates that neither eye-view for that wall is being rendered by this pipe; CAVE_LEFT_EYE indicates that the left eye-view is being rendered; CAVE_RIGHT_EYE indicates that the right eye-view is being rendered; CAVE_BOTH_EYES indicates that both views are being rendered.
void CAVEGetPosition
(CAVEID posname, float *pos) 		Returns the position of a sensor or eye. The posname argument indicates what position you are requesting; it should be one of CAVE_HEAD, CAVE_WAND, CAVE_LEFT_EYE, CAVE_RIGHT_EYE, CAVE_HEAD_NAV, CAVE_WAND_NAV, CAVE_LEFT_EYE_NAV, or CAVE_RIGHT_EYE_NAV. The _NAV id's request the values in navigated (world) coordinates; the other id's request tracker coordinates. The position is returned in pos, which should be an array of three floats.
void CAVEGetSensorOrientation
(CAVE_SENSOR_ST *sensor, CAVEID frame, float *angle) 		Returns the orientation of the tracked sensor whose data is pointed to by sensor. sensor can be a locally tracked sensor, or one from a networked user; the macros CAVESENSOR
() and CAVENETSENSOR() return appropriate pointers. frame indicates the frame of reference for the returned data; it should be either CAVE_TRACKER_FRAME for physical, tracker coordinates, or CAVE_NAV_FRAME for world, navigated coordinates. The orientation is returned in angle, which should be an array of three floats; angle[0] is the elevation (X rotation), angle[1] is the azimuth (Y rotation), and angle[2] is the roll (Z rotation).
void CAVEGetSensorPosition
(CAVE_SENSOR_ST *sensor, CAVEID frame, float *pos) 		Returns the position of the tracked sensor whose data is pointed to by sensor. sensor can be a locally tracked sensor, or one from a networked user; the macros CAVESENSOR
() and CAVENETSENSOR() return appropriate pointers. frame indicates the frame of reference for the returned data; it should be either CAVE_TRACKER_FRAME for tracker coordinates, or CAVE_NAV_FRAME for navigated coordinates. The position is returned in pos, an array of three floats.
void CAVEGetSensorVector
(CAVE_SENSOR_ST *sensor, CAVEID vecname, float *vec) 		Returns a unit vector of the tracked sensor whose data is pointed to by sensor. sensor can be a locally tracked sensor, or one from a networked user; the macros CAVESENSOR
() and CAVENETSENSOR() return appropriate pointers. vecname indicates which vector to return, and its frame of reference. The allowed values for vecname are: CAVE_FRONT, CAVE_BACK, CAVE_LEFT, CAVE_RIGHT, CAVE_UP, and CAVE_DOWN, or any of these with the suffix _NAV. The _NAV forms return vectors in navigated coordinates; the base forms return vectors in tracker coordinates. The unit vector is returned in vec, an array of three floats.
float CAVEGetTime
(void) 		Returns the current "CAVE time", i.e. the number of seconds since the CAVE was initialized. The difference between this and *CAVETime is that CAVEGetTime computes the time when it is called, whereas *CAVETime is only updated once per frame.
long CAVEgetvaluator
(CAVE_DEVICE_ID device) 		A CAVE equivalent to the IrisGL function getvaluator
(); returns the state of a valuator device. device should be one of the CAVE device names listed in cave.h; the names are the same as those used by IrisGL, except prefixed with CAVE_ (e.g. CAVE_MOUSEX). In IrisGL this function just calls getvaluator
() for the corresponding GL device. In OpenGL this function consults a table in shared memory which is updated whenever the main display process receives X events; it can thus be called from any CAVE process.
void CAVEGetVector
(CAVEID vectorid, float vector[3]) 		Computes a given tracker unit vector. The vector to return is specified by vectorid, which can be one of: CAVE_HEAD_FRONT, CAVE_HEAD_BACK, CAVE_HEAD_LEFT, CAVE_HEAD_RIGHT, CAVE_HEAD_UP, CAVE_HEAD_DOWN, CAVE_WAND_FRONT, CAVE_WAND_BACK, CAVE_WAND_LEFT, CAVE_WAND_RIGHT, CAVE_WAND_UP, CAVE_WAND_DOWN, or any of these constants suffixed with _NAV (e.g. CAVE_HEAD_FRONT_NAV). The _NAV constants request vectors in navigated coordinates; the other constants request tracker coordinates. The unit vector is returned in vector.
void CAVEGetViewport
(int *origX, int *origY, int *width, int *height) 		Returns the origin and size of the viewport for the view currently being rendered by the calling process. origX and origY return the position of the lower left corner of the viewport, measured in pixels, from the origin of the window within which the view is being drawn. width and height return the size of the viewport in pixels. This function should only be called from a CAVEDisplay callback.
void CAVEGetWindowGeometry
(int *origX, int *origY, int *width, int *height) 		Returns the origin and size of the calling process's window (this function should only be called in a display process). origX and origY return the position of the lower left corner of the window, measured from the lower left corner of the screen, in pixels. width and height return the size of the window in pixels.
GLXContext CAVEGLXContext
(void) 		Returns a pointer to the calling process's GLX rendering context. This should only be called from a display process. This function is only available in the OpenGL CAVE library.
void CAVEHalt
(void) 		Tells all the child CAVE processes to exit. This performs the exact same actions as CAVEExit
(), except that it returns to the caller, rather than calling exit
().
void CAVEHeadTransform
(void) 		Sets up a transformation using the head tracking data, which can be used to position an object at the same location and with the same orientation as the user's head.
The transformation is relative to CAVE tracker coordinates; this function should be called with no transformations active other than that initialized by the CAVE library.
int CAVEInStereo
(void) 		Returns 1 if the CAVE is displaying stereoscopic images, 0 if it is monoscopic. Note that CAVEInStereo
() returning true does not necessarily indicate that a rendering process will call the application's display function twice per frame, as each eye's view could be being handled by a separate process.
void *CAVEMalloc
(size_t size) 		Allocates a chunk of size bytes of shared memory. If no more shared memory is available, NULL is returned. The memory may be freed by CAVEFree
(). The arena used by CAVEMalloc
() is initialized in CAVEConfigure(); CAVEMalloc
() can be called at any time after that.
boolean CAVEMasterDisplay
(void) 		Returns TRUE for the one process which is drawing the 'master' wall (on a machine), FALSE for all others. This can be used when exactly one display process should execute something. Note that the master display process may be responsible for rendering other walls in addition to the master wall; this function's return value depends only on which process it is called in, not whether the master wall itself is currently being drawn.
When running a distributed CAVE, each node has its own master display process; CAVEMasterDisplay
() will return TRUE for one process on each node.
boolean CAVEMasterWall
(void) 		Returns TRUE if the calling process is currently rendering the 'master' wall.
When running a distributed CAVE, each node has its own master wall; CAVEMasterWall
() will return TRUE for one wall on each node.
void CAVENavConvertCAVEToWorld
(float inposition[3], float outposition[3]) 		Converts a position (inposition) in physical CAVE coordinates (such as a tracker position) to navigated world coordinates. The converted position is returned in outposition.
void CAVENavConvertVectorCAVEToWorld
(float invector[3], float outvector[3]) 		Converts a vector (invector) in the physical CAVE coordinate system to the navigated world coordinate system. The converted vector is returned in outvector.
void CAVENavConvertVectorWorldToCAVE
(float invector[3], float outvector[3]) 		Converts a vector (invector) in the navigated world coordinate system to the physical CAVE coordinate system. The converted vector is returned in outvector.
void CAVENavConvertWorldToCAVE
(float inposition[3], float outposition[3]) 		Converts a position (inposition) in navigated world coordinates to physical CAVE coordinates (the coordinate system used by the trackers). The converted position is returned in outposition.
void CAVENavGetMatrix
(Matrix m) 		Copies the current navigation transformation matrix into m.
void CAVENavInverseTransform
() 		Applies the inverse of the current navigation transformation. This allows a program to switch from navigated coordinates to physical (tracker) coordinates.
void CAVENavLoadIdentity
(void) 		Resets the navigation transformation matrix to identity.
void CAVENavLoadMatrix
(Matrix m) 		Replaces the navigation transformation matrix with the given matrix m.
void CAVENavLock
(void) 		Sets a lock for controlling access to the navigation transformation matrix. While the lock is set, the display processes will be blocked when they try to make a copy of it for the next frame. This can be used to make a series of navigation calls atomic; e.g.: 
		CAVENavLock
();
		CAVENavLoadIdentity
();
		CAVENavTranslate
(x, y, z);
		CAVENavRot
(angle,'y');
		CAVENavUnlock
();
Locking is not needed around single navigation function calls, as that is handled internally. A lock should not be set for very long periods, as it will block the display processes and reduce the frame rate.
void CAVENavMultMatrix
(Matrix m) 		Post-multiplies the current navigation transformation matrix by the given matrix m.
void CAVENavPreMultMatrix
(Matrix m) 		Pre-multiplies the current navigation transformation matrix by the given matrix m. This corresponds to adding a transformation in world coordinates.
void CAVENavRot
(float angle, char axis) 		Performs a rotation of the CAVE, adding it to the navigation transformation. angle is in degrees; axis should be 'x', 'y', or 'z'.
void CAVENavScale
(float xscale, float yscale, float zscale) 		Performs a scaling of the CAVE, adding it to the navigation transformation.
void CAVENavTransform
() 		Applies the current navigation transformation. This should be called in the draw routine when you wish to use world (navigated) coordinates rather than physical (tracker) coordinates.
void CAVENavTranslate
(float xtrans, float ytrans, float ztrans) 		Performs a translation of the CAVE, adding it to the navigation transformation.
void CAVENavUnlock
(void) 		Releases the navigation lock set by CAVENavLock
().
void CAVENavWorldRot
(float angle, char axis) 		Performs a rotation of the CAVE, adding it to the navigation transformation. angle is in degrees; axis should be 'x', 'y', or 'z'. The axis of rotation is defined in world coordinates, as opposed to the local CAVE coordinates used in CAVENavRot
().
void CAVENavWorldScale
(float xscale, float yscale, float zscale) 		Performs a scaling of the CAVE, adding it to the navigation transformation. The scaling is specified in world coordinates.
void CAVENavWorldTranslate
(float xtrans, float ytrans, float ztrans) 		Performs a translation of the CAVE, adding it to the navigation transformation. The translation is specified in world coordinates.
CAVE_USER_ST * CAVENetFindUser
(CAVENETID id) 		Returns a pointer to the user struct for the networked user with the given ID. If no such user is found, NULL is returned.
void CAVENetGetOrientation
(volatile CAVE_USER_ST *user, CAVEID oname, float *or) 		Returns the orientation of a networked user's sensor or eye. user is a pointer to the user structure (an entry in CAVEUser) to get the data from. oname indicates which object's orientation you are requesting; it should be one of CAVE_HEAD, CAVE_WAND, CAVE_LEFT_EYE, CAVE_RIGHT_EYE, CAVE_HEAD_NAV, CAVE_WAND_NAV, CAVE_LEFT_EYE_NAV, or CAVE_RIGHT_EYE_NAV. The first four choices return data in the local CAVE's tracker coordinate system; the last four return data in world (navigated) coordinates. (Note that the eyes will have the same orientation as the head). The orientation is returned in angle, which should be an array of three floats; angle[0] is the elevation (X rotation), angle[1] is the azimuth (Y rotation), and angle[2] is the roll (Z rotation).
void CAVENetGetPosition
(volatile CAVE_USER_ST *user, CAVEID posname, float *pos) 		Returns the position of a networked user's sensor or eye. user is a pointer to the user structure (an entry in CAVEUser) to get the data from. posname indicates what position you are requesting; it should be one of CAVE_HEAD, CAVE_WAND, CAVE_LEFT_EYE, CAVE_RIGHT_EYE, CAVE_HEAD_NAV, CAVE_WAND_NAV, CAVE_LEFT_EYE_NAV, or CAVE_RIGHT_EYE_NAV. The first four choices return positions in the local CAVE's tracker coordinate system; the last four return positions in world (navigated) coordinates. The position is returned in pos, which should be an array of three floats.
void CAVENetGetVector
(volatile CAVE_USER_ST *user, CAVEID vecname, float *vec) 		Computes a given tracker unit vector for a networked user. user is a pointer to the user structure (an entry in CAVEUser) to get the data from. The vector to return is specified by vecname, which can be one of: CAVE_HEAD_FRONT, CAVE_HEAD_BACK, CAVE_HEAD_LEFT, CAVE_HEAD_RIGHT, CAVE_HEAD_UP, CAVE_HEAD_DOWN, CAVE_WAND_FRONT, CAVE_WAND_BACK, CAVE_WAND_LEFT, CAVE_WAND_RIGHT, CAVE_WAND_UP, or CAVE_WAND_DOWN, or any of these names suffixed with _NAV (e.g. CAVE_WAND_FRONT_NAV). The _NAV choices return data in world coordinates; the other choices return data in the local CAVE's tracker coordinate system. The unit vector is returned in vec.
void CAVENetHeadTransform
(volatile CAVE_USER_ST *user) 		Sets up a transformation using a networked user's head tracking data, which can be used to position an object at the same location and with the same orientation as that user's head. user is a pointer to the user structure to get the data from.
int CAVENetReceive
(void *buf, size_t size, CAVE_USER_ST **user) 		Receives any application data which has been broadcast by another node in the CAVE networking group. The data returned will be the result of exactly one CAVENetSend
() call. Data sent by the local application will not be received. buf is a pointer to the buffer to store the data in; size is the size of the buffer in bytes. user will return a pointer to the user structure corresponding to the node which broadcast the data. The return value is the number of bytes of data which were read; it is 0 if no new packets were available. If the incoming packet is larger than size, the excess bytes are discarded.
void CAVENetSend
(void *data, size_t size) 		Broadcasts application data to all other nodes in the CAVE networking group. data is a pointer to the data to send; size is the size of the data in bytes.
void CAVENetWandTransform
(volatile CAVE_USER_ST *user) 		Sets up a transformation using a networked user's wand tracking data, which can be used to position an object at the same location and with the same orientation as that user's wand. user is a pointer to the user structure to get the data from.
int CAVENewID
(void) 		Returns a new, unique integer, which may be used as an ID number for display data or a distributed CAVE channel.
CAVELOCK CAVENewLock
(void) 		Creates a new CAVE lock structure which can be used for mutual exclusion between CAVE processes which use shared memory. A CAVE lock has two modes - read locking and write locking. Any number of processes can set a lock for read locking simultaneously; only one process can write lock it at any time. The lock returned by this function can be passed to CAVESetReadLock
(), CAVESetWriteLock
(), CAVEUnsetReadLock(), CAVEUnsetWriteLock(), and CAVEFreeLock
(). The lock is created in shared memory; roughly 1300 locks can be allocated given the current size of the CAVE library's arena.
On the Onyx, these locks use hardware spin-locks, which are not guaranteed to prevent starvation.
int CAVENumPipes
(void) 		Returns the number of drawing processes ("pipes") which are active.
void CAVEPassAllDisplayData
(void)
Calls CAVEPassDisplayData
() for all display data that has been allocated.
void CAVEPassDisplayData
(volatile void *buf, size_t size)
Sends data from the buffer buf, which was returned by CAVEAllocDisplayData
(), to the display processes. size is the number of bytes to send, starting from the beginning of the buffer; if size is 0, the entire buffer is sent. The data is copied from buf into one of the staging buffers, which will then be returned by CAVEGetDisplayData
() on the next frame. When AppDistribution is active, this function should only be called on the master node.
void CAVEPassDisplayDataByID
(int id, size_t size)
Equivalent to CAVEPassDisplayData
(), except that the the buffer is identified by it's ID number id, which is the ID passed to CAVEAllocDisplayDataByID
() (or returned by CAVEGetDisplayDataID
()).
int CAVEPipeNumber
(void) 		Returns a unique ID number for the calling drawing process ("pipe"). The pipe number will range from 0 to CAVENumPipes
()-1. If called from a non-drawing process, the return value is -1.
CAVEID CAVEProcessType
(void) 		Returns an identifier indicating what type of process it was called from. The possible return values are CAVE_APP_PROCESS (for the main process or any other process that the application forks from it), CAVE_DISPLAY_PROCESS (for the rendering processes started by CAVEInit
()), CAVE_TRACKER_PROCESS (for the tracking process), CAVE_NETWORK_PROCESS (for the networking process), and CAVE_DISTRIB_PROCESS (for the distribution administration process). CAVE_TRACKER_PROCESS and CAVE_DISTRIB_PROCESS should never be seen by application code, as those processes are handled entirely by the CAVE library; CAVE_NETWORK_PROCESS should only be seen from the network data callback function.
void CAVEResetTracker
(void) 		Signals the tracking process to reset the tracker hardware (via the SIGUSR2 signal).
void CAVEScramnetFree
(void *mem) 		Frees a chunk of shared memory which was allocated by CAVEScramnetMalloc
().
void * CAVEScramnetMalloc
(size_t size) 		Allocates a chunk of size bytes of Scramnet shared memory. If no more memory is available, NULL is returned. The memory may be freed by CAVEScramnetFree
(). Scramnet memory is replicated between machines on the Scramnet network, and may be used for shared data in a distributed CAVE. When used in a distributed CAVE application, each node must make the exact same sequence of calls to CAVEScramnetMalloc
() in order to receive the same pointers for each allocation. NB: In order to use this function, you must set the Scramnet arena size with CAVESetOption
(CAVE_SCRAMNET_ARENASIZE,...), as the default size is 0. The arena used by CAVEScramnetMalloc
() is initialized in CAVEConfigure
(); CAVEScramnetMalloc
() can be called at any time after that.
void CAVESensorTransform
(CAVE_SENSOR_ST *sensor) 		Sets up a transformation using the given sensor's tracking data, which can be used to position an object at the same location and with the same orientation as the sensor. sensor can be a locally tracked sensor, or one from a networked user; the macros CAVESENSOR
() and CAVENETSENSOR() return appropriate pointers.
The transformation is relative to CAVE tracker coordinates; this function should be called with no transformations active other than that initialized by the CAVE library.
void CAVESetOption
(CAVEID option, int value) 		Sets options for various library functions. Options which affect the amount of memory allocated for CAVE operations (CAVE_NET_NUMBUFFERS, CAVE_NET_BUFFERSIZE, CAVE_SHMEM_SIZE) must be set before calling CAVEConfigure
(). Options which affect the graphics initialization (CAVE_GL_SAMPLES, CAVE_GL_STENCILSIZE, CAVE_GL_ACCUMSIZE) must be set before calling CAVEInit
(). The options available are:
CAVE_DIST_NETWORKSLAVE
A flag indicating whether the slave nodes in a distributed CAVE should do networking. If true, all nodes will fork network processes for sending and receiving data, although only the master will broadcast the tracking data. If false, only the master node will be able to send or receive network data, and only the master will have information about the other networked CAVEs in the CAVEUser array. The default value is false (0).
CAVE_GL_ACCUMSIZE
The number of accumulation buffer bitplanes (per color component) that should be allocated when the graphics windows are opened. The default value is 0.
CAVE_GL_SAMPLES
The number of samples per pixel to be allocated in multisampling mode. When this is 0, multisampling is not enabled; when non-zero, the non-multisampled Z buffer and stencil sizes are set to 0. The default value is 0. If the hardware does not support the number of samples requested, the largest possible number of samples less than the request will be allocated.
CAVE_GL_STENCILSIZE
The number of stencil buffer bitplanes that should be allocated when the graphics windows are opened. The default value is 0.
CAVE_NET_BUFFERSIZE
The size (in bytes) of the buffers that the networking process will use for sending and receiving application data. The default value is 4096 bytes.
CAVE_NET_NUMBUFFERS
The number of buffers to use for queueing application data received by the networking process. The default value is 32. This is only meaningful if CAVENetReceive
() is used; if an application data callback is used instead, the library will not use a buffer queue.
CAVE_NET_UPDATELOCALDATA
A flag indicating whether CAVEUser[0] (the network data for the local user) should be updated when networking is disabled. If value is 1, the data will be updated once per frame by the master display process; if it is 0, the data will not be updated. The update will always occur if networking is enabled. The default value is 0.
This is useful for applications which make use of CAVEUser[0] and will need the data updated even when networking is not active. Other applications should leave it off to avoid unnecessary overhead in the display process.
CAVE_PROJ_INCLUDENAVIGATION
A flag indicating whether the navigation matrix should be included in the CAVE's projection transformation. When this is enabled, rendering will be in navigated, world coordinates by default, so CAVENavTransform
() should not be called. The default value is 0.
CAVE_PROJ_USEWINDOW
A flag indicating whether CAVEGetProjection
() should use the current window size when computing the projection for the simulator view. The default value is 1.
CAVE_PROJ_USEMODELVIEW
A flag indicating whether the projection matrix set up by the CAVE library's display loop should use the ModelView matrix for part of the transformation. The default value is 1, in which case the GL Projection matrix is used solely for the viewing frustum transformation, while transformations based on the display wall's orientation and position are loaded in the ModelView matrix (this is the traditional method). When the flag is 0, the entire transformation is loaded in the Projection matrix; this mode will make reflection-mapped textures match between walls of the CAVE; however, it breaks fog.
CAVE_SCRAMNET_ARENASIZE
Defines the size of the Scramnet shared memory arena used by CAVEScramnetMalloc
(). The size is limited by the amount of physical memory on the Scramnet card (typically 128K or 2M), and by the amount of memory used for other purposes, such as distributed CAVE synchronization. The default size is 0.
CAVE_SHMEM_SIZE
Defines the size of the shared arena used by CAVEMalloc
(); value is the arena size in bytes. This must be done before CAVEConfigure
() is called, as the arena cannot be changed once it is initialized. The default arena size is 8 megabytes.
CAVE_SHMEM_ADDRESS
Defines the base address of the shared memory arena used by CAVEMalloc
(). This defaults to 0x70000000.
CAVE_SIM_DRAWOUTLINE
A flag indicating whether the CAVE outline should be drawn in the simulator display. This is equivalent to the Insert-key keyboard control. The default value is 1.
CAVE_SIM_DRAWTIMING
A flag indicating whether the timing information should be drawn in the simulator display. This is equivalent to the keyboard control 't'. The default value is 0.
CAVE_SIM_DRAWUSER
A flag indicating whether the user's head should be drawn in the simulator display. This is equivalent to the keyboard control 'u'. The default value is 1.
CAVE_SIM_DRAWWAND
A flag indicating whether the wand icon should be drawn in the simulator display. This is equivalent to the keyboard control 'w'. The default value is 1.
CAVE_SIM_VIEWMODE
Selects which viewing mode to use in the simulator display; possible values are 0, 1, and 2. This is equivalent to the keyboard controls '0'/'1'/'2'. The default value is 1.
CAVE_TRACKER_SIGNALRESET
A flag indicating whether signals should be used for the tracker reset function. CAVEResetTracker
() sends a SIGUSR2 signal to the process handling tracking, to cause it to call the actual reset function. If your application uses SIGUSR2 itself, you may wish to disable this, although it should only be significant when the SerialTracking configuration is enabled, as then the tracking is done by the main display process. The default value is 1.
void CAVESetReadLock
(CAVELOCK lock) 		Sets a CAVE lock to indicate that the calling process will be reading the associated shared data. While the read lock is set, any number of other processes may also obtain read locks, but any processes requesting write locks will be blocked until all the read locks are released (by CAVEUnsetReadLock
()).
void CAVESetWriteLock
(CAVELOCK lock) 		Sets a CAVE lock to indicate that the calling process will be writing the associated shared data. While the write lock is set, no other process may obtain a read or write lock on the given CAVE lock. The write lock is released by CAVEUnsetWriteLock
().
void CAVEUnsetReadLock
(CAVELOCK lock) 		Releases a read lock which was set by CAVESetReadLock
(). This reduces the count of readers by one; if the count reaches 0, a process waiting to set a write lock may then be allowed through.
void CAVEUnsetWriteLock
(CAVELOCK lock) 		Releases a write lock which was set by CAVESetWriteLock
(). If other processes are waiting to set a read or write lock on this lock, one of them will then be allowed through.
void *CAVEUserSharedMemory
(int size) 		Creates a shared memory arena which can be used by your program. The argument is the size of the arena in bytes. The return value is a pointer to the arena which can be passed to amalloc in order to allocate space from it (be aware that amalloc requires some extra space for overhead - a few hundred bytes of general overhead, plus 16 bytes per amalloc'ed chunk of memory). This function should be called before CAVEInit, so that all processes will have access to the shared memory.
char * CAVEWallName
(CAVE_WALL_ID wall) 		Returns a string containing the name corresponding to the given wall ID. For example, CAVEWallName
(CAVE_FRONT_WALL) will return "front".
void CAVEWallTransform
(void) 		Sets up a transformation based on the calling process's wall. This transformation will make the origin coincide with the lower left corner of the wall, with the X and Y axes aligned with edges of the wall. It can be used to draw objects directly on the wall. CAVEWallTransform
() affects both the ModelView and the Projection matrices, so if you wish to preserve the old transformation before calling it, you must push and pop both of these matrices.
void CAVEWandTransform
(void) 		Sets up a transformation using the wand's tracking data, which can be used to position an object at the same location and with the same orientation as the wand.
The transformation is relative to CAVE tracker coordinates; this function should be called with no transformations active other than that initialized by the CAVE library.
Display * CAVEXDisplay
(void) 		Returns the X Windows display pointer for the calling process's rendering window. This should only be called from a display process. This function is only available in the OpenGL CAVE library.
XVisualInfo * CAVEXVisualInfo
(void) 		Returns an XVisualInfo pointer for the calling rendering process's window's X visual. This function is only available in the OpenGL CAVE library.
Window CAVEXWindow
(void) 		Returns a pointer to the X window being used by the calling rendering process. This function is only available in the OpenGL CAVE library.